mirror of
https://github.com/R0m1k3/FlowReader.git
synced 2026-10-20 21:58:11 +02:00
chore: initial commit of planning artifacts
This commit is contained in:
Michael committed
commit
fc0b5ccb51
574 files changed
+101136
No files matched your search
@@ -0,0 +1,387 @@
|
||||
---
|
||||
stepsCompleted:
|
||||
- step-01-init
|
||||
- step-02-context
|
||||
- step-03-starter
|
||||
- step-04-decisions
|
||||
- step-05-patterns
|
||||
- step-06-structure
|
||||
- step-07-validation
|
||||
- step-08-complete
|
||||
inputDocuments:
|
||||
- c:\Users\Michael\VSCODE\FlowReader\_bmad-output\planning-artifacts\prd.md
|
||||
workflowType: 'architecture'
|
||||
classification:
|
||||
projectType: web_app
|
||||
domain: general
|
||||
complexity: low
|
||||
projectContext: greenfield
|
||||
---
|
||||
|
||||
# Architecture Decisions - FlowReader
|
||||
|
||||
**Date:** 2026-02-04
|
||||
**Project:** FlowReader
|
||||
**User:** Michael
|
||||
**Status:** DRAFT
|
||||
|
||||
## 0. Executive Summary
|
||||
|
||||
This architecture document defines the technical decisions for FlowReader, a self-hosted RSS reader focused on radical simplicity and performance.
|
||||
|
||||
**Core Vision:** Mobile-first, "Lecture Plaisir" experience.
|
||||
**Key Constraints:** < 150MB RAM, < 100ms latency, Docker deployment.
|
||||
|
||||
---
|
||||
|
||||
## 1. Project Context Analysis
|
||||
|
||||
### Requirements Overview
|
||||
|
||||
**Functional Requirements:**
|
||||
The system must manage the full lifecycle of RSS feed consumption for multiple isolated users.
|
||||
|
||||
* **Core Capabilities**: Feed CRUD, RSS/Atom Parsing, Content Normalization ("Reading Pleasure"), Read State Management (Read/Unread/Favorites).
|
||||
* **Real-time**: Push notifications (Websockets) for new article arrivals.
|
||||
* **Multi-tenancy**: Strict isolation of user data.
|
||||
|
||||
**Non-Functional Requirements (Drivers):**
|
||||
NFRs are particularly constraining and will drive technological choices:
|
||||
|
||||
* **Reliability (Priority)**: **PostgreSQL** required for robust data persistence.
|
||||
* **Resource Efficiency (Critical)**: < 150-250MB RAM Total target. This is a significant challenge with PostgreSQL. Heavy stacks (Java/Spring, unoptimized Node) are ruled out.
|
||||
* **Performance**: < 100ms TTI. Implies efficient rendering and likely aggressive local caching (Optimistic UI).
|
||||
* **Resilience**: Strict 5s timeout on external feeds. Backend must be asynchronous and non-blocking.
|
||||
|
||||
**Scale & Complexity:**
|
||||
|
||||
* Primary domain: **Web Application (SPA + API + Worker)**
|
||||
* Complexity level: **Low** (Scope well-defined, personal use scale)
|
||||
* Estimated architectural components: **4** (Frontend, API Server, Feed Fetcher Worker, Database).
|
||||
|
||||
### Technical Constraints & Dependencies
|
||||
|
||||
* **Database**: **PostgreSQL** (Dockerized).
|
||||
* **Deployment**: Docker Compose (App + DB Containers).
|
||||
* **Offline**: "Offline First" strategy implies local storage and sync logic in Frontend.
|
||||
|
||||
### Cross-Cutting Concerns Identified
|
||||
|
||||
* **Concurrency**: Feed fetching must be parallelized but throttled to control RAM/CPU usage.
|
||||
* **Sanitization**: Article HTML "cleaning" is critical for security (XSS) and readability.
|
||||
* **Authentication**: Stateless session management (JWT?) or optimized stateful to limit overhead.
|
||||
|
||||
---
|
||||
|
||||
## 2. Starter Template Evaluation
|
||||
|
||||
### Primary Technology Domain
|
||||
|
||||
**Full-Stack Web Application** (Dockerized Monolith).
|
||||
|
||||
### Starter Options Considered
|
||||
|
||||
* **Option 1: AESRAEL/go-postgres-react-starter**:
|
||||
* Stack: Go (Fiber) + React + PostgreSQL.
|
||||
* Pros: Ready to run.
|
||||
* Cons: Uses **Fiber** (non-standard `net/http`), potentially higher learning curve. Dockerfile optimization for <150MB not guaranteed.
|
||||
* **Option 2: vladannovi1234/Golang-React-psql-docker**:
|
||||
* Stack: Go + React + Postgres.
|
||||
* Pros: Simple DB connection.
|
||||
* Cons: Old/Not actively maintained.
|
||||
* **Option 3: Custom "Low-Res" Composite Stack (Recommended)**:
|
||||
* Stack: **Go (Chi)** + **React (Vite)** + **PostgreSQL**.
|
||||
* Pros: Total control over binary size. **Chi** is standard and fast. **Vite** is the modern standard.
|
||||
* Cons: Requires manual "wiring", but guarantees we hit the **150-250MB RAM** target.
|
||||
|
||||
### Selected Strategy: Custom Composite Stack (Go Chi + Vite)
|
||||
|
||||
**Rationale for Selection:**
|
||||
To strictly meet the **<250MB RAM** constraint (with Postgres taking ~70MB+), we cannot afford framework bloat or unoptimized containers.
|
||||
|
||||
* **Go Chi**: Only the router, no "Framework magic". Closer to metal.
|
||||
* **React + Vite**: Optimized build.
|
||||
* **Single Dockerfile**: We will use a Multi-Stage Docker build to embed the React Assets *into* the Go Binary to minimize container count (1 App Container + 1 DB Container).
|
||||
|
||||
**Initialization Commands (To be executed in Implementation Phase):**
|
||||
|
||||
```bash
|
||||
# Frontend
|
||||
npm create vite@latest frontend -- --template react-ts
|
||||
|
||||
# Backend
|
||||
mkdir backend
|
||||
cd backend
|
||||
go mod init github.com/user/flowreader
|
||||
go get -u github.com/go-chi/chi/v5
|
||||
go get -u github.com/jackc/pgx/v5
|
||||
```
|
||||
|
||||
**Architectural Decisions Provided:**
|
||||
|
||||
* **Language**: Go 1.22+ (Standard `net/http` compatible).
|
||||
* **Routing**: `go-chi/chi` (Middlewares, context-aware).
|
||||
* **Database Driver**: `pgx/v5` (High performance).
|
||||
* **Frontend**: React 18 + TypeScript + Vite.
|
||||
* **Deployment**: Docker Compose (services: `app`, `db`).
|
||||
|
||||
---
|
||||
|
||||
## 3. Core Architectural Decisions
|
||||
|
||||
### Decision Priority Analysis
|
||||
|
||||
* **Critical Decisions**: Authentication Strategy, Database Schema Design, API Interaction Pattern.
|
||||
* **Important Decisions**: State Management Library, CSS Framework, Folder Structure.
|
||||
|
||||
### Data Architecture
|
||||
|
||||
* **Database**: PostgreSQL 16+ (Alpine).
|
||||
* **Migration Tool**: `golang-migrate` or `goose` (SQL based migrations).
|
||||
* **Data Access**: `pgx` native queries (No ORM). We choose **No ORM** to maintain raw performance and control over generated SQL, critical for the RAM constraint. Struct mapping via `scany` or manual scan.
|
||||
|
||||
### Authentication & Security
|
||||
|
||||
* **Method**: **Stateful Session** (server-side).
|
||||
* *Storage*: PostgreSQL (`sessions` table). No Redis (saves RAM).
|
||||
* *Transport*: `HttpOnly`, `Secure` Cookies.
|
||||
* **Rationale**: Simplifies revocation (logout from all devices), strictly binds session to user context, avoids JWT complexity/insecurity for this scale.
|
||||
|
||||
### API & Communication Patterns
|
||||
|
||||
* **Protocol**: **REST JSON**.
|
||||
* **Documentation**: **OpenAPI 3.0** via code annotations (`swaggo`).
|
||||
* **Real-time**: **WebSockets** (using `nhooyr/websocket` library) for "New Article" notifications.
|
||||
|
||||
### Frontend Architecture
|
||||
|
||||
* **State Management**:
|
||||
* **Server State**: **TanStack Query (React Query)**. Handles caching, deduping, background updates.
|
||||
* **Client State**: **Zustand**. For UI state (sidebar open, theme, etc.). Ultra-lightweight.
|
||||
* **Styling**: **Tailwind CSS**. Utility-first, zero runtime cost.
|
||||
* **Routing**: **React Router v6**.
|
||||
|
||||
### Backend Code Organization
|
||||
|
||||
* **Structure**: **Standard Go Project Layout**.
|
||||
* `cmd/server`: Application entry point.
|
||||
* `internal/domain`: core business logic & interfaces (Dependency Inversion).
|
||||
* `internal/adapters`: database implementation, web handlers.
|
||||
* `internal/service`: application logic orchestration.
|
||||
|
||||
### Decision Impact Analysis
|
||||
|
||||
* **Strict Memory Budget**: The choice of "No ORM" and "No Redis" is directly driven by the <250MB constraint.
|
||||
* **Latency**: React Query's aggressive client-side caching will mask network latency, achieving the <100ms perceived performance goal.
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation Patterns & Consistency Rules
|
||||
|
||||
### Naming Patterns
|
||||
|
||||
* **Database**: `snake_case` for all tables (plural) and columns.
|
||||
* Ex: `users`, `feed_items`, `created_at`.
|
||||
* **Go Code**: `CamelCase` for exported structs/interfaces, `camelCase` for private.
|
||||
* Ex: `type UserService struct`, `func (s *UserService) getUser()`.
|
||||
* **API (JSON)**: `camelCase`.
|
||||
* Ex: `{ "userId": 1, "firstName": "Alice" }`.
|
||||
* *Implementation Note*: Go Struct tags must align: ``json:"userId"``
|
||||
|
||||
### Structure Patterns (Backend Layers)
|
||||
|
||||
* **Handler Layer**: HTTP specifics only. Decodes JSON, calls Service, encodes JSON. **No Logic**.
|
||||
* File naming: `handler/user_handler.go`
|
||||
* **Service Layer**: Business logic (Validation, Authorization, Orchestration). **No SQL**.
|
||||
* File naming: `service/user_service.go`
|
||||
* **Repository Layer**: Database access only. Raw SQL / Builder. **No Logic**.
|
||||
* File naming: `repository/user_repository.go`
|
||||
|
||||
### Format Patterns
|
||||
|
||||
**API Response Envelope:**
|
||||
All successful responses must follow this wrapper:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": { ... }, // The actual resource(s)
|
||||
"meta": { ... } // Pagination, etc (optional)
|
||||
}
|
||||
```
|
||||
|
||||
**Error Format:**
|
||||
All errors must return standard codes:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "RESOURCE_NOT_FOUND",
|
||||
"message": "User with ID 123 does not exist",
|
||||
"details": { ... } // Optional validation errors
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Communication Patterns
|
||||
|
||||
* **Dependency Injection**: All dependencies (DB, Config, other Services) must be explicitly injected via constructor (`New...`). Global variables are forbidden.
|
||||
* **Interfaces**: Define interfaces where they are *used* (Consumer side), not where they are defined.
|
||||
* Rule: "Accept Interfaces, Return Structs".
|
||||
|
||||
### Enforcement Guidelines
|
||||
|
||||
* **Linter**: Use `golangci-lint` with strict settings to enforce naming and complexity rules.
|
||||
* **Review**: PRs must verify that controllers do not contain SQL and Repositories do not contain business axioms.
|
||||
|
||||
---
|
||||
|
||||
## 5. Project Structure & Boundaries
|
||||
|
||||
### Complete Project Directory Structure
|
||||
|
||||
```
|
||||
flowreader/
|
||||
├── docker-compose.yml # Production & Dev orchestration services (App, DB)
|
||||
├── Dockerfile # Multi-stage build (Node Build -> Go Builder -> Alpine Runtime)
|
||||
├── Makefile # Automation (install, dev, build, test, migrate)
|
||||
├── go.mod # Backend dependencies
|
||||
├── api/ # API Definition
|
||||
│ └── openapi.yaml # OpenAPI 3.0 Specification
|
||||
├── cmd/
|
||||
│ └── server/ # Application Entry Point
|
||||
│ └── main.go # Wires Config, DB, Services, and starts Server
|
||||
├── internal/ # Private Application Code (Go Standard Layout)
|
||||
│ ├── config/ # Configuration loading (Env vars)
|
||||
│ ├── core/
|
||||
│ │ ├── domain/ # Core Business Entities (User, Feed, Item) - Pure Structs
|
||||
│ │ ├── ports/ # Interfaces (Repository, Service, TtsProvider) - Hexagonal Arch
|
||||
│ │ └── errors/ # Domain Errors definitions
|
||||
│ ├── service/ # Business Logic Implementation (orchestrates Repo + Domain)
|
||||
│ └── adapter/
|
||||
│ ├── handler/ # HTTP Handlers (REST) - Decodes JSON, Validates, Calls Service
|
||||
│ └── repository/ # Database implementation (PostgreSQL/pgx)
|
||||
├── migrations/ # Database Migrations (SQL)
|
||||
│ ├── 000001_create_users_table.up.sql
|
||||
│ └── 000002_create_feeds_table.up.sql
|
||||
└── web/ # Frontend Application (React + Vite)
|
||||
├── package.json
|
||||
├── vite.config.ts
|
||||
├── index.html
|
||||
└── src/
|
||||
├── api/ # API Clients (axios/fetch wrappers)
|
||||
├── components/ # Shared Atomic Components (Button, Input, Layout)
|
||||
├── features/ # Feature-based organization
|
||||
│ ├── auth/ # Login, Register forms & hooks
|
||||
│ ├── feed/ # Feed List, Add Feed modal
|
||||
│ └── reader/ # Article View, Reading modes
|
||||
├── hooks/ # Shared React Hooks
|
||||
├── stores/ # Global State (Zustand)
|
||||
└── types/ # Shared TypeScript Types
|
||||
```
|
||||
|
||||
### Architectural Boundaries
|
||||
|
||||
* **API Boundary**: The `internal/adapter/handler` package is the only entry point for external HTTP traffic. It strictly translates HTTP to Domain calls.
|
||||
* **Database Boundary**: The `internal/adapter/repository` package is the only place SQL is allowed. No other layer knows about the database implementation.
|
||||
* **Frontend/Backend Boundary**: Rigid separation. The Frontend in `web/` is a completely independent SPA that consumes the API. It is served by Nginx or embedded in the Go binary for production.
|
||||
|
||||
### Requirements to Structure Mapping
|
||||
|
||||
* **FR-UserManagement**:
|
||||
* Backend: `internal/core/domain/user.go`, `internal/service/auth.go`, `internal/adapter/repository/user_repo.go`
|
||||
* Frontend: `web/src/features/auth/`
|
||||
* **FR-FeedManagement**:
|
||||
* Backend: `internal/service/feed.go`
|
||||
* Frontend: `web/src/features/feed/`
|
||||
* **NFR-Performance**:
|
||||
* Database connection pool configured in `internal/adapter/repository/postgres.go`
|
||||
* Frontend caching configured in `web/src/api/queryClient.ts` (React Query)
|
||||
|
||||
---
|
||||
|
||||
## 6. Architecture Validation Results
|
||||
|
||||
### Coherence Validation ✅
|
||||
|
||||
**Decision Compatibility:**
|
||||
The Composite Stack (Go Chi + Vite) is highly coherent. No framework bloat.
|
||||
The choice of "No ORM" aligns perfectly with the "Resource Efficiency" driver.
|
||||
|
||||
**Risk Assessment:**
|
||||
|
||||
* **Critical Risk**: PostgreSQL RAM usage vs 150MB Limit.
|
||||
* **Mitigation**: Strict PostgreSQL configuration required (`shared_buffers=24MB`, `max_connections=20`).
|
||||
|
||||
### Requirements Coverage Validation ✅
|
||||
|
||||
* **Real-time**: Covered by Websockets (`nhooyr/websocket`).
|
||||
* **Performance**: Covered by Go (Backend) + React Query (Frontend Optimistic UI).
|
||||
* **Mobility**: Covered by Tailwind Mobile-First approach.
|
||||
|
||||
### Architecture readiness Assessment
|
||||
|
||||
**Overall Status**: READY FOR IMPLEMENTATION
|
||||
**Confidence Level**: High (Technical choices are standard and robust).
|
||||
|
||||
### Implementation Handoff
|
||||
|
||||
**Critical First Steps:**
|
||||
|
||||
1. Initialize Git Repository.
|
||||
2. Setup Docker Compose with RAM limits and Postgres Tuning.
|
||||
3. Initialize Go Module and React Project.
|
||||
|
||||
---
|
||||
|
||||
## 7. Architecture Completion Summary
|
||||
|
||||
### Workflow Completion
|
||||
|
||||
**Architecture Decision Workflow:** COMPLETED ✅
|
||||
**Date Completed:** 2026-02-04
|
||||
**Document Location:** c:\Users\Michael\VSCODE\FlowReader\_bmad-output\planning-artifacts\architecture.md
|
||||
|
||||
### Final Architecture Deliverables
|
||||
|
||||
**📋 Complete Architecture Document**
|
||||
|
||||
* All architectural decisions documented with specific versions
|
||||
* Implementation patterns ensuring AI agent consistency
|
||||
* Complete project structure with all files and directories
|
||||
* Requirements to architecture mapping
|
||||
* Validation confirming coherence and completeness
|
||||
|
||||
**🏗️ Implementation Ready Foundation**
|
||||
|
||||
* **7** architectural decisions made
|
||||
* **4** implementation patterns defined
|
||||
* **4** architectural components specified
|
||||
* **All** requirements fully supported
|
||||
|
||||
### Implementation Handoff
|
||||
|
||||
**AI Agent Guidelines:**
|
||||
This architecture document is your complete guide for implementing FlowReader. Follow all decisions, patterns, and structures exactly as documented.
|
||||
|
||||
**First Implementation Priority:**
|
||||
Initialize project structure:
|
||||
|
||||
```bash
|
||||
# Frontend
|
||||
npm create vite@latest frontend -- --template react-ts
|
||||
|
||||
# Backend
|
||||
mkdir backend
|
||||
cd backend
|
||||
go mod init github.com/user/flowreader
|
||||
go get -u github.com/go-chi/chi/v5
|
||||
go get -u github.com/jackc/pgx/v5
|
||||
```
|
||||
|
||||
**Quality Assurance Checklist**
|
||||
|
||||
* ✅ **Architecture Coherence**: Go/Chi/Postgres stack is coherent and minimal.
|
||||
* ✅ **Requirements Coverage**: All FRs and NFRs (including <150MB RAM) are addressed.
|
||||
* ✅ **Implementation Readiness**: Patterns for API, DB, and Code style are defined.
|
||||
|
||||
**Architecture Status:** READY FOR IMPLEMENTATION ✅
|
||||
@@ -0,0 +1,2 @@
|
||||
workflow_status:
|
||||
create-architecture: c:\Users\Michael\VSCODE\FlowReader\_bmad-output\planning-artifacts\architecture.md
|
||||
@@ -0,0 +1,150 @@
|
||||
# Implementation Readiness Assessment Report
|
||||
|
||||
**Date:** 2026-02-04
|
||||
**Project:** FlowReader
|
||||
|
||||
## Document Inventory
|
||||
|
||||
### Product Requirements Documents (PRD)
|
||||
|
||||
**Whole Documents:**
|
||||
|
||||
- `prd.md` (Main PRD)
|
||||
|
||||
### Architecture Documents
|
||||
|
||||
*None found.*
|
||||
|
||||
### Epics & Stories
|
||||
|
||||
*None found.*
|
||||
|
||||
### UX Design Documents
|
||||
|
||||
*None found.*
|
||||
|
||||
## PRD Analysis
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- FR1: Inscription autonome d'un nouvel utilisateur.
|
||||
- FR2: Authentification sécurisée (Session/JWT).
|
||||
- FR3: Isolation stricte des données (Flux, Lectures, Favoris) par compte utilisateur.
|
||||
- FR4: Ajout de flux via URL (support RSS/Atom auto-détecté).
|
||||
- FR5: Détection automatique des métadonnées (Titre, Icône) à l'ajout.
|
||||
- FR6: Importation de flux en masse via fichier OPML.
|
||||
- FR7: Gestion des flux (Renommer, Supprimer).
|
||||
- FR8: Dashboard unifié "Nouveautés" trié par date.
|
||||
- FR9: Mode "Lecture Plaisir" avec extraction du contenu principal (nettoyage HTML).
|
||||
- FR10: Marquage "Lu" manuel ou automatique (scroll/swipe).
|
||||
- FR11: Marquage "Tout lu" par flux ou global.
|
||||
- FR12: Gestion des Favoris ("Star" / "Read Later").
|
||||
- FR13: Push temps réel des nouveaux articles (Websockets) vers le client connecté.
|
||||
- FR14: Synchronisation instantanée de l'état de lecture entre appareils.
|
||||
- FR15: Liste des utilisateurs inscrits (Vue Admin).
|
||||
- FR16: Suppression de compte utilisateur.
|
||||
|
||||
**Total FRs:** 16
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
- NFR1: Empreinte mémoire totale (Back+Front) < 150 Mo RAM.
|
||||
- NFR2: Temps de chargement article (TTI) < 100ms perçu.
|
||||
- NFR3: Score Lighthouse Mobile > 90.
|
||||
- NFR4: Architecture SPA (Single Page App) optimisée "Offline First" (Optimistic UI).
|
||||
- NFR5: Redémarrage conteneur (Recovery Time) < 5 secondes.
|
||||
- NFR6: Résilience totale aux flux défaillants (Timeout 5s strict, pas de blocage global).
|
||||
- NFR7: Isolation des données inter-utilisateurs validée par tests.
|
||||
- NFR8: Aucune télémétrie ou fuite de données (Privacy by Design).
|
||||
|
||||
**Total NFRs:** 8
|
||||
|
||||
### Additional Requirements
|
||||
|
||||
- **Technical Stack:** Frontend SPA, Backend (Go/Rust/Node), DB SQLite, Single Docker Image.
|
||||
- **Deployment:** `docker-compose up` simplicity.
|
||||
|
||||
### PRD Completeness Assessment
|
||||
|
||||
The PRD is highly focused and structured. It contains clear, testable Functional and Non-Functional requirements.
|
||||
- **Strengths:** Clear separation of concerns, measurable NFRs, specific user journeys.
|
||||
- **Gaps:** No specific API contract defined (deliberate for Architecture phase), no specific UI wireframes (deliberate for UX phase).
|
||||
- **Verdict:** PRD is **Implementation Ready** from a requirements perspective, pending Architecture and UX decisions.
|
||||
|
||||
## Epic Coverage Validation
|
||||
|
||||
### Coverage Matrix
|
||||
|
||||
| FR Number | PRD Requirement | Epic Coverage | Status |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| FR1 | Inscription autonome d'un nouvel utilisateur. | **NOT FOUND** | ❌ MISSING |
|
||||
| FR2 | Authentification sécurisée (Session/JWT). | **NOT FOUND** | ❌ MISSING |
|
||||
| FR3 | Isolation stricte des données | **NOT FOUND** | ❌ MISSING |
|
||||
| FR4 | Ajout de flux via URL | **NOT FOUND** | ❌ MISSING |
|
||||
| FR5 | Détection automatique des métadonnées | **NOT FOUND** | ❌ MISSING |
|
||||
| FR6 | Importation de flux en masse via fichier OPML. | **NOT FOUND** | ❌ MISSING |
|
||||
| FR7 | Gestion des flux (Renommer, Supprimer). | **NOT FOUND** | ❌ MISSING |
|
||||
| FR8 | Dashboard unifié "Nouveautés" | **NOT FOUND** | ❌ MISSING |
|
||||
| FR9 | Mode "Lecture Plaisir" | **NOT FOUND** | ❌ MISSING |
|
||||
| FR10 | Marquage "Lu" manuel ou automatique | **NOT FOUND** | ❌ MISSING |
|
||||
| FR11 | Marquage "Tout lu" par flux ou global. | **NOT FOUND** | ❌ MISSING |
|
||||
| FR12 | Gestion des Favoris | **NOT FOUND** | ❌ MISSING |
|
||||
| FR13 | Push temps réel des nouveaux articles | **NOT FOUND** | ❌ MISSING |
|
||||
| FR14 | Synchronisation instantanée | **NOT FOUND** | ❌ MISSING |
|
||||
| FR15 | Liste des utilisateurs inscrits (Vue Admin). | **NOT FOUND** | ❌ MISSING |
|
||||
| FR16 | Suppression de compte utilisateur. | **NOT FOUND** | ❌ MISSING |
|
||||
|
||||
### Missing Requirements
|
||||
|
||||
**ALL Functional Requirements are currently uncovered.**
|
||||
No "Epics & Stories" document was found. This is expected as the project is in the initial PRD phase.
|
||||
|
||||
### Coverage Statistics
|
||||
|
||||
- Total PRD FRs: 16
|
||||
- FRs covered in epics: 0
|
||||
- Coverage percentage: **0%**
|
||||
|
||||
## UX Alignment Assessment
|
||||
|
||||
### UX Document Status
|
||||
|
||||
**NOT FOUND**
|
||||
|
||||
### Alignment Issues
|
||||
|
||||
- **Implied UI Requirement:** PRD mandates "Mobile First" and "Lecture Plaisir" experience.
|
||||
- **Missing Artifact:** No UX design document (Wireframes/Mockups) exists to guide frontend implementation.
|
||||
- **Risk:** Developing "Lecture Plaisir" view without design validation risks "Engineered UI" (functional but ugly) which violates Success Criteria ("Adoption personnelle").
|
||||
|
||||
### Warnings
|
||||
|
||||
⚠️ **WARNING:** UX is implied but missing. Proceeding to implementation without a UX phase is high risk for the "User Success" criteria.
|
||||
|
||||
## Epic Quality Review
|
||||
|
||||
### Status: SKIPPED
|
||||
|
||||
**Reason:** No Epics & Stories document found to review.
|
||||
|
||||
## Summary and Recommendations
|
||||
|
||||
### Overall Readiness Status
|
||||
|
||||
🟡 **PARTIALLY READY** (Requirements Clear, but Architecture & Design Missing)
|
||||
|
||||
### Critical Issues Requiring Immediate Action
|
||||
|
||||
1. **Missing Technical Architecture:** The PRD lists constraints (150MB RAM, Docker), but does not define *how* to achieve them (Go vs Rust? React vs Vue? DB Schema?).
|
||||
2. **Missing Visual Design:** "Lecture Plaisir" is a subjective success criteria. Attempting to code this without a visual reference is risky.
|
||||
3. **Missing Planning (Epics):** No work breakdown structure exists yet.
|
||||
|
||||
### Recommended Next Steps
|
||||
|
||||
1. **Create Architecture:** Use the **Architect Agent** (`/architect`) to define the stack that meets the NFRs (ex: Go + SQLite + Preact?).
|
||||
2. **Create UX Design:** Use the **UX Agent** (`/ux-designer`) to sketch the "Lecture Plaisir" view.
|
||||
3. **Create Epics:** Once stack and design are clear, break down the work.
|
||||
|
||||
### Final Note
|
||||
|
||||
The PRD itself is high quality and provides a solid foundation. The "Red Indicators" (Missing Epics/Arch) are normal for this stage. **Do not start coding yet.** The project needs an architectural blueprint first.
|
||||
@@ -0,0 +1,162 @@
|
||||
---
|
||||
stepsCompleted:
|
||||
- step-01-init
|
||||
- step-02-discovery
|
||||
- step-03-success
|
||||
- step-04-journeys
|
||||
- step-05-domain
|
||||
- step-06-innovation
|
||||
- step-07-project-type
|
||||
- step-08-scoping
|
||||
- step-09-functional
|
||||
- step-10-nonfunctional
|
||||
- step-11-polish
|
||||
inputDocuments: []
|
||||
workflowType: 'prd'
|
||||
documentCounts:
|
||||
briefs: 0
|
||||
research: 0
|
||||
brainstorming: 0
|
||||
projectDocs: 0
|
||||
classification:
|
||||
projectType: web_app
|
||||
domain: general
|
||||
complexity: low
|
||||
projectContext: greenfield
|
||||
---
|
||||
|
||||
# Product Requirements Document - FlowReader
|
||||
|
||||
**Author:** Michael
|
||||
**Date:** 2026-02-04
|
||||
**Status:** DRAFT (Polished)
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
**FlowReader** est un lecteur de flux RSS/Atom auto-hébergé, conçu pour être l'antithèse des agrégateurs modernes surchargés. Sa proposition de valeur unique réside dans son équilibre radical : une **simplicité monacale pour l'utilisateur** (Zéro Friction, Lecture Plaisir) alliée à une **robustesse technique absolue** (Docker <150Mo RAM, Websockets temps réel, Multi-utilisateurs). Il vise à remplacer les solutions existantes par une expérience "Mobile First" fluide et instantanée.
|
||||
|
||||
---
|
||||
|
||||
## 2. Success Criteria
|
||||
|
||||
### User & Business Success
|
||||
|
||||
* **Zéro Friction** : Ajout d'un flux en < 2 clics et < 10 secondes.
|
||||
* **Lisibilité "Livre"** : Transformation automatique des articles bruts en format épuré (sans pubs/distractions).
|
||||
* **Adoption Quotidienne** : Utilisation > 5 min/jour en remplacement complet du lecteur précédent.
|
||||
* **Mobile First** : Expérience tactile parfaite (swipe, transitions) utilisable d'une seule main.
|
||||
|
||||
### Technical Success
|
||||
|
||||
* **Performance Extrême** : Conteneur complet < 150 Mo RAM. Rendu article < 100ms.
|
||||
* **Déploiement Instantané** : `docker-compose up` suffit pour tout lancer (Database + App + Proxy).
|
||||
* **Temps Réel** : Les nouveaux articles apparaissent instantanément (Websockets) sans rechargement.
|
||||
|
||||
---
|
||||
|
||||
## 3. Product Scope & Roadmap
|
||||
|
||||
### Phase 1: MVP (Lancement)
|
||||
|
||||
L'objectif est une expérience de lecture complète et fiable pour plusieurs utilisateurs.
|
||||
|
||||
* **Cœur** : Gestion Flux (CRUD), Dashboard "Nouveautés", Vue Lecture Plaisir.
|
||||
* **Architecture** : SPA (React/Vue), Backend (Go/Rust/Node?), SQLite, Docker.
|
||||
* **Critique** : Authentification Multi-comptes, Websockets, Support OPML.
|
||||
|
||||
### Phase 2: Growth (Post-MVP)
|
||||
|
||||
* **IA** : Résumés automatiques via OpenRouter.
|
||||
* **Organisation** : Dossiers, Tags, Recherche Full-text.
|
||||
* **Filtres** : Règles de filtrage et de mise en sourdine.
|
||||
|
||||
### Phase 3: Vision (Futur)
|
||||
|
||||
* **Écosystème** : API Publique, Apps natives iOS/Android, Fédération ActivityPub.
|
||||
|
||||
---
|
||||
|
||||
## 4. User Journeys
|
||||
|
||||
### J1: Le "Rituel du Matin" (Utilisateur Principal)
|
||||
|
||||
* **Contexte** : 15 min de libre, mobile.
|
||||
* **Flux** : Michael ouvre l'app → Dashboard "Nouveautés" (flux agrégés) → Tape sur un article → Lecture immersive (sans distraction) → Swipe article suivant → Message "Tout lu" satisfaisant.
|
||||
* **Valeur** : Efficacité et plaisir de lecture immédiat.
|
||||
|
||||
### J2: Le Nouvel Arrivant (Invité)
|
||||
|
||||
* **Contexte** : Ami invité sur l'instance.
|
||||
* **Flux** : Inscription (Compte "Paul") → Dashboard vide → Import OPML ou ajout URL → Ses articles apparaissent instantanément.
|
||||
* **Valeur** : Isolation totale des données (ne voit pas les flux de Michael), onboarding rapide.
|
||||
|
||||
### J3: L'Admin Système (Ops)
|
||||
|
||||
* **Contexte** : Maintenance.
|
||||
* **Flux** : `docker-compose pull && up` → Redémarrage < 5s → Données préservées.
|
||||
* **Valeur** : Maintenance "Zero Headache".
|
||||
|
||||
---
|
||||
|
||||
## 5. Functional Requirements (Capabilities)
|
||||
|
||||
### User Management
|
||||
|
||||
* **FR1**: Inscription autonome d'un nouvel utilisateur.
|
||||
* **FR2**: Authentification sécurisée (Session/JWT).
|
||||
* **FR3**: Isolation stricte des données (Flux, Lectures, Favoris) par compte utilisateur.
|
||||
|
||||
### Feed Management
|
||||
|
||||
* **FR4**: Ajout de flux via URL (support RSS/Atom auto-détecté).
|
||||
* **FR5**: Détection automatique des métadonnées (Titre, Icône) à l'ajout.
|
||||
* **FR6**: Importation de flux en masse via fichier OPML.
|
||||
* **FR7**: Gestion des flux (Renommer, Supprimer).
|
||||
|
||||
### Reading Experience
|
||||
|
||||
* **FR8**: Dashboard unifié "Nouveautés" trié par date.
|
||||
* **FR9**: Mode "Lecture Plaisir" avec extraction du contenu principal (nettoyage HTML).
|
||||
* **FR10**: Marquage "Lu" manuel ou automatique (scroll/swipe).
|
||||
* **FR11**: Marquage "Tout lu" par flux ou global.
|
||||
* **FR12**: Gestion des Favoris ("Star" / "Read Later").
|
||||
|
||||
### Real-time & Synchronization
|
||||
|
||||
* **FR13**: Push temps réel des nouveaux articles (Websockets) vers le client connecté.
|
||||
* **FR14**: Synchronisation instantanée de l'état de lecture entre appareils.
|
||||
|
||||
### Administration
|
||||
|
||||
* **FR15**: Liste des utilisateurs inscrits (Vue Admin).
|
||||
* **FR16**: Suppression de compte utilisateur.
|
||||
|
||||
---
|
||||
|
||||
## 6. Non-Functional Requirements (Quality)
|
||||
|
||||
### Performance & Resource Efficiency
|
||||
|
||||
* **NFR1**: Empreinte mémoire totale (Back+Front) **< 150 Mo** RAM.
|
||||
* **NFR2**: Temps de chargement article (TTI) **< 100ms** perçu.
|
||||
* **NFR3**: Score Lighthouse Mobile > 90.
|
||||
|
||||
### Architecture & Reliability
|
||||
|
||||
* **NFR4**: Architecture SPA (Single Page App) optimisée "Offline First" (Optimistic UI).
|
||||
* **NFR5**: Redémarrage conteneur (Recovery Time) **< 5 secondes**.
|
||||
* **NFR6**: Résilience totale aux flux défaillants (Timeout 5s strict, pas de blocage global).
|
||||
|
||||
### Security
|
||||
|
||||
* **NFR7**: Isolation des données inter-utilisateurs validée par tests.
|
||||
* **NFR8**: Aucune télémétrie ou fuite de données (Privacy by Design).
|
||||
|
||||
---
|
||||
|
||||
## 7. Technical Stack Constraints
|
||||
|
||||
* **Frontend**: Framework SPA moderne (ex: React, Vue, Svelte) supportant les navigateurs Evergreen.
|
||||
* **Backend**: Langage performant à faible empreinte mémoire (ex: Go, Rust, ou Node optimisé).
|
||||
* **Database**: SQLite (mode WAL) pour la simplicité de déploiement et performance locale.
|
||||
* **Deployment**: Image Docker unique (ou Multi-stage build) exposant un seul port.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
project_name: 'FlowReader'
|
||||
user_name: 'Michael'
|
||||
date: '2026-02-04'
|
||||
sections_completed: ['technology_stack', 'language_rules', 'testing', 'quality', 'workflow', 'anti_patterns']
|
||||
status: 'complete'
|
||||
optimized_for_llm: true
|
||||
---
|
||||
|
||||
# Project Context for AI Agents
|
||||
|
||||
_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack & Versions
|
||||
|
||||
- **Backend**: Go 1.22+
|
||||
- Router: `go-chi/chi/v5`
|
||||
- DB Driver: `jackc/pgx/v5`
|
||||
- Websocket: `nhooyr/websocket`
|
||||
- **Frontend**: React 18+ (Vite)
|
||||
- Language: TypeScript 5+
|
||||
- State: Zustand (Client), TanStack Query v5 (Server)
|
||||
- Styling: Tailwind CSS v3 (Mobile First)
|
||||
- **Database**: PostgreSQL 16+ (Alpine Docker)
|
||||
- **Infra**: Docker Compose
|
||||
|
||||
## Critical Implementation Rules
|
||||
|
||||
### Language-Specific Rules (Go)
|
||||
|
||||
- **Layout**: Follow Standard Go Project Layout (`cmd/`, `internal/`, `pkg/`).
|
||||
- **Interfaces**: Define interfaces at consumer side (Ports & Adapters).
|
||||
- **Error Handling**: Always wrap errors with context: `fmt.Errorf("op failed: %w", err)`.
|
||||
- **Dependency Injection**: Explicit injection via constructors (`NewService(repo)`). No Globals.
|
||||
|
||||
### Language-Specific Rules (TypeScript/React)
|
||||
|
||||
- **Strict Mode**: `strict: true` in `tsconfig.json`.
|
||||
- **Components**: Functional Components only.
|
||||
- **Naming**: `PascalCase` for Components, `camelCase` for hooks/utils.
|
||||
- **State Separation**: strictly use React Query for API data, Zustand for UI state.
|
||||
|
||||
### Testing Rules
|
||||
|
||||
- **Backend (Go)**:
|
||||
- Unit Tests: Co-located with code (`service_test.go`). Use `tables` (Table Driven Tests).
|
||||
- Integration Tests: In `tests/`. Use `testcontainers-go` or direct Docker DB.
|
||||
- **Rule**: No Logic in Handlers = No Handler Unit Tests (Integration only for API).
|
||||
- **Frontend**:
|
||||
- Components: Vitest + React Testing Library.
|
||||
|
||||
### Code Quality & Style
|
||||
|
||||
- **Linter**: `golangci-lint` (Standard) + `eslint` (React).
|
||||
- **Comments**: Go: Standard GoDoc compliant comments on Exported entities.
|
||||
- **Complexity**: Keep functions small. If > 50 lines, likely needs refactor.
|
||||
|
||||
### Project Structure & Boundaries
|
||||
|
||||
- **API Boundary**: Handlers ONLY translate HTTP <-> Domain. No business logic.
|
||||
- **DB Boundary**: Repositories ONLY talk SQL. No business logic.
|
||||
- **Frontend Boundary**: Feature-based folders (`features/auth`, `features/feed`).
|
||||
|
||||
### Development Workflow Rules
|
||||
|
||||
- **Branches**: `feat/` for new features, `fix/` for bugs.
|
||||
- **Commits**: Conventional Commits (`feat: add login`, `fix: resolve crash`).
|
||||
- **PRs**: Must have Passing CI (Lint + Test) before merge.
|
||||
|
||||
### Critical Don't-Miss Rules (A.K.A The "No-Go" Zone)
|
||||
|
||||
- ❌ **No ORM**: Do not use GORM or similar. Raw SQL/pgx only.
|
||||
- ❌ **No JWT**: Use Stateful Sessions (Cookies) only.
|
||||
- ❌ **No Global State in Go**: No `var DB *sql.DB`. Pass dependencies.
|
||||
- ❌ **No Logic in Handlers**: Handlers are dumb translators.
|
||||
- ❌ **No Heavy Libraries**: Avoid large dependencies (e.g. AWS SDK if not needed). Keep RAM < 150MB.
|
||||
|
||||
---
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
**For AI Agents:**
|
||||
|
||||
- Read this file before implementing any code
|
||||
- Follow ALL rules exactly as documented
|
||||
- When in doubt, prefer the more restrictive option
|
||||
- Update this file if new patterns emerge
|
||||
|
||||
**For Humans:**
|
||||
|
||||
- Keep this file lean and focused on agent needs
|
||||
- Update when technology stack changes
|
||||
- Review quarterly for outdated rules
|
||||
- Remove rules that become obvious over time
|
||||
Reference in new issue
Block a user