From ba8fe1f29980748e99583bec86ed17daf44e0fdd Mon Sep 17 00:00:00 2001 From: Thomas Laure Date: Sat, 14 Mar 2026 20:20:30 +0100 Subject: [PATCH] docs: add landing page and team phases to roadmap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Insert Phase 2 (Landing Page): marketing site, waitlist, pricing - Insert Phase 5 (Team): workspace, roles, billing - Renumber AI Layer → 3, Automation → 4, Ecosystem → 6 - Rewrite README.md with updated positioning and tech stack - Update CLAUDE.md phases to match Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 10 ++-- README.md | 145 +++++++++++++++++++++++++----------------------- docs/ROADMAP.md | 105 +++++++++++++++++++++++++++++------ 3 files changed, 170 insertions(+), 90 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 07703aa..b9cd38b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,10 +50,12 @@ docker compose up -d --build ## 1.2 Project Phases -1. **Phase 1 (MVP):** Core RSS engine, PostgreSQL schema, Dashboard UI ✅ -2. **Phase 2 (AI Layer):** Symfony AI for summaries and auto-tagging -3. **Phase 3 (Automation):** Newsletter scheduler, Raindrop.io sync -4. **Phase 4 (Ecosystem):** Spotlight command engine, MCP server +1. **Phase 1 (MVP):** Core RSS engine, PostgreSQL schema, Inbox UI ✅ +2. **Phase 2 (Landing Page):** Marketing site, waitlist, pricing +3. **Phase 3 (AI Layer):** Symfony AI for summaries and auto-tagging +4. **Phase 4 (Automation):** Newsletter scheduler, Raindrop.io sync +5. **Phase 5 (Team):** Multi-user workspace, roles, billing +6. **Phase 6 (Ecosystem):** Spotlight command engine, MCP server, social sharing --- diff --git a/README.md b/README.md index 55a0af2..cfb4004 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,113 @@ # Signalist -Here is the technical and functional specification document for **Signalist**. +**AI-powered news curation and publishing platform for small teams.** ---- - -# Technical Specifications: Signalist +Signalist helps news curators, content teams, and media monitors stay on top of +their industry — aggregating RSS feeds, synthesizing content with AI, and +publishing insights across newsletters and social media. -## 1. Project Overview - -**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. +--- -## 2. Functional Requirements +## What it does -### 2.1 Feed Management (RSS) +**Monitor → Curate → Synthesize → Publish** -* **Categorization:** Create, update, and delete thematic categories. -* **Aggregation:** Link one or multiple RSS feeds to a specific category. -* **Content Extraction:** Use libraries (e.g., Readability) to fetch full article content for AI processing, bypassing partial RSS snippets. +- **Aggregate** RSS feeds into categorized, searchable inboxes +- **Summarize** articles automatically with LLMs (OpenAI, Anthropic, Mistral) +- **Bookmark & tag** content with AI-assisted auto-tagging +- **Generate newsletters** from curated articles, configurable by reading time +- **Publish** to social media (X, LinkedIn, Threads, Bluesky, WhatsApp) +- **Search** with full-text and semantic (vector) search -### 2.2 Navigation & Filtering +--- -* **Global Dashboard:** A chronological feed of all incoming articles. -* **Categorized Views:** Filter content by category, specific source, or date range. -* **Advanced Search:** Support for both full-text search and semantic search (Vector Search). +## Tech Stack -### 2.3 Bookmarking & Tagging +| Layer | Technology | +|-------|------------| +| **Backend** | PHP 8.5 · Symfony 7.4 · API Platform 4.x · FrankenPHP | +| **Frontend** | React 19 · TypeScript · Vite 7 · MUI v7 · react-i18next | +| **Database** | PostgreSQL 16 · pgvector | +| **Queue** | Symfony Messenger · Redis | +| **AI** | Symfony AI (OpenAI / Anthropic / Mistral) | +| **Auth** | LexikJWT | +| **Testing** | PHPUnit · Behat · Vitest · React Testing Library | -* **Storage:** Save articles to a "Bookmarks" section. -* **Intelligent Tagging:** * Automatic tag generation via LLM based on content analysis. -* Manual tag management. +--- +## Architecture -* **Raindrop.io Integration:** Synchronize bookmarks and tags with the Raindrop.io API. +Hexagonal Architecture + CQRS + DDD -### 2.4 AI-Powered Newsletters +``` +Request → Controller → InputDTO → Command/Query → Handler → Repository + ↓ + Messenger (async) + ↓ + AI / RSS / External APIs +``` -* **Dynamic Generation:** Use LLMs (via Symfony AI) to synthesize summaries of unread articles. -* **Newsletter Structure:** Grouped by category, including clickable titles and concise summaries. -* **Reading Time Calibration:** * Default duration: 5 minutes. -* Customizable duration: Logic based on a **200 words-per-minute** ratio. +--- +## Getting Started -* **Scheduling:** Automated delivery at set intervals (daily, weekly, custom) using Symfony Scheduler. -* **Manual Composition:** Interface to manually select articles and send to a custom mailing list. +### Prerequisites -### 2.5 Social Sharing +- Docker & Docker Compose +- Make -* Direct sharing integration for WhatsApp, X (Twitter), LinkedIn, Threads, Bluesky. +### Install ---- +```bash +git clone https://github.com/thlaure/Signalist.git +cd Signalist +make install +``` -## 3. Interface & User Experience (UX) +Or manually: -### 3.1 Layout +```bash +docker compose up -d --build +docker compose exec app composer install +docker compose exec app php bin/console lexik:jwt:generate-keypair +docker compose exec app php bin/console doctrine:migrations:migrate +``` -* **Dashboard:** Central feed focused on readability and minimalism. -* **Sidepanel:** Left-aligned navigation for categories, bookmarks, and settings. -* **Visual Style:** Minimalist UI, high-contrast typography, native dark mode support. +The app is available at `http://localhost:8000`. -### 3.2 "Spotlight" Command Center +### Useful commands -* Global search/command bar (accessible via `Cmd+K`). -* **Natural Language Processing (NLP):** Map user intent to backend actions (e.g., "Add [https://example.com/feed](https://example.com/feed) to Dev category"). -* **Direct Execution:** Perform CRUD operations and AI queries directly from the command bar. +| Command | Description | +|---------|-------------| +| `make lint` | PHP CS Fixer | +| `make analyse` | PHPStan (level 9) | +| `make rector` | Rector modernization | +| `make quality` | All quality checks | +| `make tests-unit` | PHPUnit unit tests | +| `make grumphp` | Full pre-commit suite | +| `make help` | All available commands | --- -## 4. Technical Stack - -### 4.1 Backend - -* **Framework:** Symfony 8.x (utilizing PHP 8.5 features). -* **Frontend:** React with TypeScript, Vite, and MUI for component styling. -* **Architecture:** CQRS, Clean Architecture, SOLID principles, Hexagonal architecture for maintainability and testability. -* **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. -* **Database:** PostgreSQL with **pgvector** extension for storing and querying embeddings. -* **Queue Management:** Symfony Messenger + Redis for background RSS crawling and LLM processing. - -### 4.2 AI & Interoperability +## Roadmap -* **Symfony AI:** Core component for LLM abstraction (OpenAI, Anthropic, Mistral). -* **AI Agents:** Implementation of `#[AsTool]` attributes to connect the Spotlight interface to PHP services. -* **MCP (Model Context Protocol):** Implementation of a native MCP server to allow external LLMs to query the user's Signalist data securely. +1. **Phase 1 — MVP** ✅ Core RSS engine, auth, Inbox UI +2. **Phase 2 — Landing Page** Marketing site, waitlist, pricing +3. **Phase 3 — AI Layer** Summaries, embeddings, semantic search, auto-tagging +4. **Phase 4 — Automation** Newsletter scheduler, Raindrop.io sync +5. **Phase 5 — Team** Multi-user workspace, roles, billing +6. **Phase 6 — Ecosystem** Spotlight (`Cmd+K`), MCP server, social publishing -### 4.3 Third-Party APIs - -* **Raindrop.io:** OAuth2 authentication for bookmark synchronization. -* **Emailing:** Symfony Mailer +See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full task breakdown. --- -## 5. Development Constraints & Accuracy +## Contributing -* **Factual Integrity:** All AI-generated summaries must provide a direct link to the original source to prevent misinformation. -* **Performance:** RSS parsing and vector generation must be handled asynchronously to maintain UI responsiveness. -* **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. +This project is in active development. Contributions are not open yet. --- -## 6. Project Roadmap - -1. **Phase 1 (MVP):** Core RSS engine, PostgreSQL schema, and basic Dashboard UI. -2. **Phase 2 (AI Layer):** Symfony AI integration for summaries and automated tagging. -3. **Phase 3 (Automation):** Newsletter scheduler and Raindrop.io sync. -4. **Phase 4 (Ecosystem):** Spotlight command engine and MCP server implementation. +## License ---- +Private — all rights reserved. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 4ce8d58..e49157d 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -261,9 +261,42 @@ --- -## Phase 2 — AI Layer: Summaries, Embeddings & Semantic Search +## Phase 2 — Landing Page -### 2.1 Symfony AI Integration +### 2.1 Design & Content + +| Task | Status | +|------|--------| +| Value proposition copywriting | Not Started | +| Wireframes / mockup (Figma or equivalent) | Not Started | +| Pricing tiers definition (free, team, enterprise) | Not Started | + +### 2.2 Implementation + +| Task | Status | +|------|--------| +| Landing page setup (separate from app) | Not Started | +| Hero section (headline, subheadline, CTA) | Not Started | +| Features section | Not Started | +| Pricing section | Not Started | +| Social proof / testimonials section | Not Started | +| Waitlist / early access form | Not Started | +| SEO meta tags + Open Graph | Not Started | +| Responsive design (mobile + desktop) | Not Started | + +### 2.3 Infrastructure + +| Task | Status | +|------|--------| +| Domain configuration | Not Started | +| Deploy to production (Vercel / Netlify / other) | Not Started | +| Analytics (privacy-friendly, e.g. Plausible) | Not Started | + +--- + +## Phase 3 — AI Layer: Summaries, Embeddings & Semantic Search + +### 3.1 Symfony AI Integration | Task | Status | |------|--------| @@ -272,7 +305,7 @@ | Environment variables for API keys | Not Started | | AI client adapter (`Infrastructure/AI/`) | Not Started | -### 2.2 Article Embeddings (pgvector) +### 3.2 Article Embeddings (pgvector) | Task | Status | |------|--------| @@ -285,7 +318,7 @@ | Embedding generation adapter (OpenAI / Mistral) | Not Started | | Unit tests for embedding pipeline | Not Started | -### 2.3 Semantic Search +### 3.3 Semantic Search | Task | Status | |------|--------| @@ -299,7 +332,7 @@ | Frontend search UI with results | Not Started | | Unit + integration tests | Not Started | -### 2.4 LLM Summarization +### 3.4 LLM Summarization | Task | Status | |------|--------| @@ -311,7 +344,7 @@ | Frontend summary display | Not Started | | Unit tests for summarization | Not Started | -### 2.5 Auto-Tagging +### 3.5 Auto-Tagging | Task | Status | |------|--------| @@ -324,7 +357,7 @@ | Frontend tag display + filtering | Not Started | | Unit tests | Not Started | -### 2.6 Data Anonymization (GDPR) +### 3.6 Data Anonymization (GDPR) | Task | Status | |------|--------| @@ -336,9 +369,9 @@ --- -## Phase 3 — Automation: Newsletters, Scheduling & Sync +## Phase 4 — Automation: Newsletters, Scheduling & Sync -### 3.1 Newsletter Domain +### 4.1 Newsletter Domain | Task | Status | |------|--------| @@ -354,7 +387,7 @@ | Newsletter API Platform resource | Not Started | | Unit tests for all handlers | Not Started | -### 3.2 Newsletter Content Generation +### 4.2 Newsletter Content Generation | Task | Status | |------|--------| @@ -366,7 +399,7 @@ | HTML email template | Not Started | | Unit tests | Not Started | -### 3.3 Newsletter Scheduling +### 4.3 Newsletter Scheduling | Task | Status | |------|--------| @@ -379,7 +412,7 @@ | Schedule management UI (frontend) | Not Started | | Unit + integration tests | Not Started | -### 3.4 Raindrop.io Sync +### 4.4 Raindrop.io Sync | Task | Status | |------|--------| @@ -394,9 +427,49 @@ --- -## Phase 4 — Ecosystem: Spotlight, MCP Server & Social Sharing +## Phase 5 — Team: Multi-User Workspace & Collaborative Curation + +### 5.1 Organization & Roles + +| Task | Status | +|------|--------| +| `Organization` entity + migration | Not Started | +| `OrganizationMember` entity (userId, orgId, role) + migration | Not Started | +| Roles: `admin`, `curator`, `reader` | Not Started | +| `InviteMemberCommand` + `InviteMemberHandler` | Not Started | +| `RemoveMemberCommand` + `RemoveMemberHandler` | Not Started | +| `UpdateMemberRoleCommand` + `UpdateMemberRoleHandler` | Not Started | +| Organization API endpoints | Not Started | +| Role-based access control (Symfony voters) | Not Started | +| Unit tests | Not Started | + +### 5.2 Shared Workspace + +| Task | Status | +|------|--------| +| Feeds and categories scoped to organization | Not Started | +| Shared bookmarks with curator attribution | Not Started | +| Collaborative annotations on bookmarks | Not Started | +| Activity feed (who curated what, when) | Not Started | +| Per-member read status (independent of shared articles) | Not Started | +| Frontend team workspace UI | Not Started | +| Unit + integration tests | Not Started | + +### 5.3 Billing & Plans + +| Task | Status | +|------|--------| +| Plan model (free, team, enterprise) | Not Started | +| Per-seat pricing logic | Not Started | +| Usage limits per plan (feeds, members, AI calls) | Not Started | +| Stripe integration (subscriptions) | Not Started | +| Plan management UI | Not Started | + +--- + +## Phase 6 — Ecosystem: Spotlight, MCP Server & Social Sharing -### 4.1 Spotlight Command Interface +### 6.1 Spotlight Command Interface | Task | Status | |------|--------| @@ -409,7 +482,7 @@ | Frontend + backend integration | Not Started | | Unit tests for command parser | Not Started | -### 4.2 MCP Server (Model Context Protocol) +### 6.2 MCP Server (Model Context Protocol) | Task | Status | |------|--------| @@ -423,7 +496,7 @@ | Authentication for MCP endpoints | Not Started | | Integration tests | Not Started | -### 4.3 Social Sharing +### 6.3 Social Sharing | Task | Status | |------|--------|