|
1 | 1 | # Signalist |
2 | 2 |
|
3 | | -Here is the technical and functional specification document for **Signalist**. |
| 3 | +**AI-powered news curation and publishing platform for small teams.** |
4 | 4 |
|
5 | | ---- |
6 | | - |
7 | | -# Technical Specifications: Signalist |
| 5 | +Signalist helps news curators, content teams, and media monitors stay on top of |
| 6 | +their industry — aggregating RSS feeds, synthesizing content with AI, and |
| 7 | +publishing insights across newsletters and social media. |
8 | 8 |
|
9 | | -## 1. Project Overview |
10 | | - |
11 | | -**Signalist** is a smart intelligence platform (SaaS) designed to aggregate, filter, and synthesize RSS feeds using Artificial Intelligence. The application features a natural language command interface (like Spotlight on macOS) and exposes its data via the Model Context Protocol (MCP) to integrate with the broader LLM ecosystem. |
| 9 | +--- |
12 | 10 |
|
13 | | -## 2. Functional Requirements |
| 11 | +## What it does |
14 | 12 |
|
15 | | -### 2.1 Feed Management (RSS) |
| 13 | +**Monitor → Curate → Synthesize → Publish** |
16 | 14 |
|
17 | | -* **Categorization:** Create, update, and delete thematic categories. |
18 | | -* **Aggregation:** Link one or multiple RSS feeds to a specific category. |
19 | | -* **Content Extraction:** Use libraries (e.g., Readability) to fetch full article content for AI processing, bypassing partial RSS snippets. |
| 15 | +- **Aggregate** RSS feeds into categorized, searchable inboxes |
| 16 | +- **Summarize** articles automatically with LLMs (OpenAI, Anthropic, Mistral) |
| 17 | +- **Bookmark & tag** content with AI-assisted auto-tagging |
| 18 | +- **Generate newsletters** from curated articles, configurable by reading time |
| 19 | +- **Publish** to social media (X, LinkedIn, Threads, Bluesky, WhatsApp) |
| 20 | +- **Search** with full-text and semantic (vector) search |
20 | 21 |
|
21 | | -### 2.2 Navigation & Filtering |
| 22 | +--- |
22 | 23 |
|
23 | | -* **Global Dashboard:** A chronological feed of all incoming articles. |
24 | | -* **Categorized Views:** Filter content by category, specific source, or date range. |
25 | | -* **Advanced Search:** Support for both full-text search and semantic search (Vector Search). |
| 24 | +## Tech Stack |
26 | 25 |
|
27 | | -### 2.3 Bookmarking & Tagging |
| 26 | +| Layer | Technology | |
| 27 | +|-------|------------| |
| 28 | +| **Backend** | PHP 8.5 · Symfony 7.4 · API Platform 4.x · FrankenPHP | |
| 29 | +| **Frontend** | React 19 · TypeScript · Vite 7 · MUI v7 · react-i18next | |
| 30 | +| **Database** | PostgreSQL 16 · pgvector | |
| 31 | +| **Queue** | Symfony Messenger · Redis | |
| 32 | +| **AI** | Symfony AI (OpenAI / Anthropic / Mistral) | |
| 33 | +| **Auth** | LexikJWT | |
| 34 | +| **Testing** | PHPUnit · Behat · Vitest · React Testing Library | |
28 | 35 |
|
29 | | -* **Storage:** Save articles to a "Bookmarks" section. |
30 | | -* **Intelligent Tagging:** * Automatic tag generation via LLM based on content analysis. |
31 | | -* Manual tag management. |
| 36 | +--- |
32 | 37 |
|
| 38 | +## Architecture |
33 | 39 |
|
34 | | -* **Raindrop.io Integration:** Synchronize bookmarks and tags with the Raindrop.io API. |
| 40 | +Hexagonal Architecture + CQRS + DDD |
35 | 41 |
|
36 | | -### 2.4 AI-Powered Newsletters |
| 42 | +``` |
| 43 | +Request → Controller → InputDTO → Command/Query → Handler → Repository |
| 44 | + ↓ |
| 45 | + Messenger (async) |
| 46 | + ↓ |
| 47 | + AI / RSS / External APIs |
| 48 | +``` |
37 | 49 |
|
38 | | -* **Dynamic Generation:** Use LLMs (via Symfony AI) to synthesize summaries of unread articles. |
39 | | -* **Newsletter Structure:** Grouped by category, including clickable titles and concise summaries. |
40 | | -* **Reading Time Calibration:** * Default duration: 5 minutes. |
41 | | -* Customizable duration: Logic based on a **200 words-per-minute** ratio. |
| 50 | +--- |
42 | 51 |
|
| 52 | +## Getting Started |
43 | 53 |
|
44 | | -* **Scheduling:** Automated delivery at set intervals (daily, weekly, custom) using Symfony Scheduler. |
45 | | -* **Manual Composition:** Interface to manually select articles and send to a custom mailing list. |
| 54 | +### Prerequisites |
46 | 55 |
|
47 | | -### 2.5 Social Sharing |
| 56 | +- Docker & Docker Compose |
| 57 | +- Make |
48 | 58 |
|
49 | | -* Direct sharing integration for WhatsApp, X (Twitter), LinkedIn, Threads, Bluesky. |
| 59 | +### Install |
50 | 60 |
|
51 | | ---- |
| 61 | +```bash |
| 62 | +git clone https://github.com/thlaure/Signalist.git |
| 63 | +cd Signalist |
| 64 | +make install |
| 65 | +``` |
52 | 66 |
|
53 | | -## 3. Interface & User Experience (UX) |
| 67 | +Or manually: |
54 | 68 |
|
55 | | -### 3.1 Layout |
| 69 | +```bash |
| 70 | +docker compose up -d --build |
| 71 | +docker compose exec app composer install |
| 72 | +docker compose exec app php bin/console lexik:jwt:generate-keypair |
| 73 | +docker compose exec app php bin/console doctrine:migrations:migrate |
| 74 | +``` |
56 | 75 |
|
57 | | -* **Dashboard:** Central feed focused on readability and minimalism. |
58 | | -* **Sidepanel:** Left-aligned navigation for categories, bookmarks, and settings. |
59 | | -* **Visual Style:** Minimalist UI, high-contrast typography, native dark mode support. |
| 76 | +The app is available at `http://localhost:8000`. |
60 | 77 |
|
61 | | -### 3.2 "Spotlight" Command Center |
| 78 | +### Useful commands |
62 | 79 |
|
63 | | -* Global search/command bar (accessible via `Cmd+K`). |
64 | | -* **Natural Language Processing (NLP):** Map user intent to backend actions (e.g., "Add [https://example.com/feed](https://example.com/feed) to Dev category"). |
65 | | -* **Direct Execution:** Perform CRUD operations and AI queries directly from the command bar. |
| 80 | +| Command | Description | |
| 81 | +|---------|-------------| |
| 82 | +| `make lint` | PHP CS Fixer | |
| 83 | +| `make analyse` | PHPStan (level 9) | |
| 84 | +| `make rector` | Rector modernization | |
| 85 | +| `make quality` | All quality checks | |
| 86 | +| `make tests-unit` | PHPUnit unit tests | |
| 87 | +| `make grumphp` | Full pre-commit suite | |
| 88 | +| `make help` | All available commands | |
66 | 89 |
|
67 | 90 | --- |
68 | 91 |
|
69 | | -## 4. Technical Stack |
70 | | - |
71 | | -### 4.1 Backend |
72 | | - |
73 | | -* **Framework:** Symfony 8.x (utilizing PHP 8.5 features). |
74 | | -* **Frontend:** React with TypeScript, Vite, and MUI for component styling. |
75 | | -* **Architecture:** CQRS, Clean Architecture, SOLID principles, Hexagonal architecture for maintainability and testability. |
76 | | -* **Testing:** PHPUnit for backend (unit and integration + code coverage UI, test what it needs to be tested, 100% coverage), Jest + React Testing Library for frontend. |
77 | | -* **Database:** PostgreSQL with **pgvector** extension for storing and querying embeddings. |
78 | | -* **Queue Management:** Symfony Messenger + Redis for background RSS crawling and LLM processing. |
79 | | - |
80 | | -### 4.2 AI & Interoperability |
| 92 | +## Roadmap |
81 | 93 |
|
82 | | -* **Symfony AI:** Core component for LLM abstraction (OpenAI, Anthropic, Mistral). |
83 | | -* **AI Agents:** Implementation of `#[AsTool]` attributes to connect the Spotlight interface to PHP services. |
84 | | -* **MCP (Model Context Protocol):** Implementation of a native MCP server to allow external LLMs to query the user's Signalist data securely. |
| 94 | +1. **Phase 1 — MVP** ✅ Core RSS engine, auth, Inbox UI |
| 95 | +2. **Phase 2 — Landing Page** Marketing site, waitlist, pricing |
| 96 | +3. **Phase 3 — AI Layer** Summaries, embeddings, semantic search, auto-tagging |
| 97 | +4. **Phase 4 — Automation** Newsletter scheduler, Raindrop.io sync |
| 98 | +5. **Phase 5 — Team** Multi-user workspace, roles, billing |
| 99 | +6. **Phase 6 — Ecosystem** Spotlight (`Cmd+K`), MCP server, social publishing |
85 | 100 |
|
86 | | -### 4.3 Third-Party APIs |
87 | | - |
88 | | -* **Raindrop.io:** OAuth2 authentication for bookmark synchronization. |
89 | | -* **Emailing:** Symfony Mailer |
| 101 | +See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full task breakdown. |
90 | 102 |
|
91 | 103 | --- |
92 | 104 |
|
93 | | -## 5. Development Constraints & Accuracy |
| 105 | +## Contributing |
94 | 106 |
|
95 | | -* **Factual Integrity:** All AI-generated summaries must provide a direct link to the original source to prevent misinformation. |
96 | | -* **Performance:** RSS parsing and vector generation must be handled asynchronously to maintain UI responsiveness. |
97 | | -* **Scalability:** The architecture must support the "Bring Your Own Key" (BYOK) model for LLM API costs, but if the user does not provide a key, the system should default to a shared organizational key with usage limits. |
| 107 | +This project is in active development. Contributions are not open yet. |
98 | 108 |
|
99 | 109 | --- |
100 | 110 |
|
101 | | -## 6. Project Roadmap |
102 | | - |
103 | | -1. **Phase 1 (MVP):** Core RSS engine, PostgreSQL schema, and basic Dashboard UI. |
104 | | -2. **Phase 2 (AI Layer):** Symfony AI integration for summaries and automated tagging. |
105 | | -3. **Phase 3 (Automation):** Newsletter scheduler and Raindrop.io sync. |
106 | | -4. **Phase 4 (Ecosystem):** Spotlight command engine and MCP server implementation. |
| 111 | +## License |
107 | 112 |
|
108 | | ---- |
| 113 | +Private — all rights reserved. |
0 commit comments