From 7ae6ef7ef1d12a3463ed88856d9f8ae6ca8cdd88 Mon Sep 17 00:00:00 2001
From: oabrivard <olivier@abrivard.fr>
Date: Sat, 21 Mar 2026 16:10:39 +0100
Subject: [PATCH] Defined implementation plan

---
 docs/implementation-plan/01-phase-roadmap.md  |  608 ++++
 docs/implementation-plan/02-backend-plan.md   | 3189 +++++++++++++++++
 docs/implementation-plan/03-frontend-plan.md  | 2654 ++++++++++++++
 .../04-infrastructure-plan.md                 | 2418 +++++++++++++
 4 files changed, 8869 insertions(+)
 create mode 100644 docs/implementation-plan/01-phase-roadmap.md
 create mode 100644 docs/implementation-plan/02-backend-plan.md
 create mode 100644 docs/implementation-plan/03-frontend-plan.md
 create mode 100644 docs/implementation-plan/04-infrastructure-plan.md

diff --git a/docs/implementation-plan/01-phase-roadmap.md b/docs/implementation-plan/01-phase-roadmap.md
new file mode 100644
index 0000000..59b575d
--- /dev/null
+++ b/docs/implementation-plan/01-phase-roadmap.md
@@ -0,0 +1,608 @@
+# Phased Delivery Roadmap: AI Weekly Synth Rewrite
+
+**Date**: 2026-03-21
+**Author**: Phase Roadmap Planner
+**Input**: Team analysis (01-04) and project decisions (05)
+
+---
+
+## Overview
+
+This roadmap decomposes the AI Weekly Synth rewrite into 7 phases. Each phase produces a working, deployable application. The phases are ordered to deliver value incrementally: Phase 1 proves the stack works end-to-end, and each subsequent phase adds exactly one major capability.
+
+The decisions document establishes: Rust (Axum) + Postgres + SolidJS + Tailwind CSS, all 3 LLM providers, user-provided API keys, email + magic link auth, Docker-only deployment, no data migration, and testing as part of the plan.
+
+---
+
+## Dependency Graph
+
+```
+Phase 1: Foundation (Axum + Postgres + SolidJS + Auth + Settings CRUD)
+   |
+   +---> Phase 2: Sources CRUD + Scraper Service
+   |        |
+   |        +---> Phase 4: LLM Provider Abstraction (Gemini first)
+   |                 |
+   |                 +---> Phase 5: Generation Pipeline + SSE Progress
+   |                 |        |
+   |                 |        +---> Phase 6: Multi-Provider (OpenAI + Anthropic)
+   |                 |
+   +---> Phase 3: Admin Module (Provider/Model Curation, Rate Limits)
+   |        |
+   |        +---> Phase 4 (admin curates provider list that Phase 4 uses)
+   |
+   +-------------------------------+---> Phase 7: Email (Resend) + Export (PDF/Markdown)
+```
+
+Summary of dependencies:
+- Phase 2 depends on Phase 1 (auth, DB, frontend scaffolding)
+- Phase 3 depends on Phase 1 (auth with admin role, DB)
+- Phase 4 depends on Phase 2 (scraper) + Phase 3 (admin-curated provider/model list)
+- Phase 5 depends on Phase 4 (LLM provider working)
+- Phase 6 depends on Phase 5 (pipeline working with one provider)
+- Phase 7 depends on Phase 1 only (can be started after Phase 1, but best done after Phase 5 so there is content to email/export)
+
+---
+
+## Risk-Ordered Priority
+
+If time runs out, this is the order of criticality (most critical first):
+
+1. **Phase 1 -- Foundation**: Without this, nothing works. This is the riskiest phase because it involves setting up Rust/Axum from scratch (learning curve), hand-rolling auth (magic links, sessions, captcha), and standing up the SolidJS frontend with routing and auth context. Everything depends on this.
+
+2. **Phase 5 -- Generation Pipeline + SSE**: This is the core value proposition of the application. Without synthesis generation, the app is a settings manager.
+
+3. **Phase 4 -- LLM Provider Abstraction (Gemini)**: Prerequisite for Phase 5. Getting one provider working end-to-end with structured output and web search grounding proves the LLM integration works.
+
+4. **Phase 2 -- Sources CRUD + Scraper**: Sources feed the generation pipeline. The scraper is used during generation to validate URLs.
+
+5. **Phase 3 -- Admin Module**: Users cannot configure providers/models without this. However, for a single-user self-hosted scenario, environment variables or seed data could serve as a temporary workaround.
+
+6. **Phase 6 -- Multi-Provider**: Adds OpenAI and Anthropic. High value but the app is fully functional with Gemini alone.
+
+7. **Phase 7 -- Email + Export**: Nice-to-have features. The app works without them. Users can copy-paste or screenshot.
+
+---
+
+## Phase 1: Foundation
+
+### Goal
+Prove the entire stack works end-to-end: Rust serving a SolidJS SPA, Postgres connected, email + magic link authentication functioning, and one complete CRUD flow (user settings).
+
+### Deliverables
+
+**Backend (Rust/Axum)**:
+- Project scaffold: Cargo workspace, `main.rs`, config loading (dotenvy), tracing/logging setup
+- Postgres connection pool (sqlx) with compile-time checked queries
+- Database migrations: `users`, `sessions`, `magic_link_tokens`, `settings` tables
+- Unified error handling (`AppError` enum with `IntoResponse`)
+- Auth system:
+  - `POST /api/v1/auth/register` -- email + Cloudflare Turnstile captcha validation, sends magic link via Resend
+  - `POST /api/v1/auth/login` -- request magic link (same response whether email exists or not)
+  - `GET /api/v1/auth/verify?token=...` -- verify token, create session, set cookie, redirect to app
+  - `POST /api/v1/auth/logout` -- invalidate session, clear cookie
+  - `GET /api/v1/auth/me` -- return current user info
+- Session middleware: cookie extraction, SHA-256 lookup, expiration check (30-day), user injection into request extensions
+- CSRF protection: `X-Requested-With` header check on mutating requests + `SameSite=Lax` cookies
+- Rate limiting on auth endpoints (per-IP, per-email)
+- Settings CRUD: `GET /api/v1/settings`, `PUT /api/v1/settings`
+- CLI command: `create-admin` to bootstrap the first admin account
+- Static file serving: serve the SolidJS build output from the Axum binary
+- Security headers (CSP, X-Content-Type-Options, X-Frame-Options, HSTS, Referrer-Policy)
+- CORS configuration
+
+**Frontend (SolidJS)**:
+- Vite + SolidJS + TypeScript + Tailwind CSS project scaffold
+- Auth context with signals (session check via `GET /api/v1/auth/me` on load)
+- Route guard (redirect to `/login` if unauthenticated)
+- Login page: email field, Turnstile widget, "Recevoir un lien de connexion" button, "Creer un compte" link
+- Sign-up page: email + optional display name + Turnstile + "Creer mon compte" button
+- Magic link confirmation screen ("Verifiez votre boite de reception", resend with cooldown)
+- Navbar: logo, nav links (Syntheses, Sources), user email, Settings gear, Logout
+- Mobile hamburger menu
+- Active route indicator on nav links
+- Settings page: theme, max age days, categories (dynamic list with add/remove), max items per category, search agent behavior, AI model dropdown (hardcoded placeholder for now)
+- Error boundary (top-level `ErrorBoundary` component)
+- Session expiry handling (401 -> redirect to login with message)
+- i18n-ready structure: all user-facing strings in a central `fr.ts` locale file, accessed via a helper function
+
+**Infrastructure**:
+- `Dockerfile` (multi-stage: Rust build + SolidJS build -> minimal runtime image)
+- `docker-compose.yml` with Postgres service + app service
+- `.env.example` with all required environment variables documented
+- Resend integration for sending magic link emails
+
+**CLI**:
+- `./ai-synth create-admin admin@example.com` creates an admin user (no magic link needed, account is pre-verified)
+
+### Definition of Done
+- `docker compose up` starts the app with Postgres
+- A new user can sign up (receives magic link email via Resend), click the link, and land on the home page
+- The admin can be created via CLI
+- Authenticated user can view and update their settings
+- Unauthenticated requests return 401
+- Session persists across browser restarts (within 30-day window)
+- Logout invalidates the session server-side
+- Turnstile captcha prevents automated signups
+- All pages render correctly on desktop and mobile
+
+### Dependencies
+None -- this is the first phase.
+
+### Risk Factors
+1. **Hand-rolled auth is the highest-risk component**. Magic link token lifecycle (generation, SHA-256 hashing, single-use enforcement, expiration, email enumeration prevention) must be implemented correctly from the start. A subtle bug here creates a security vulnerability.
+2. **Rust learning curve**. Async Rust with Axum, sqlx, and tower middleware is non-trivial for someone learning Rust. Expect the borrow checker, lifetime annotations, and trait bounds to slow things down significantly in this phase.
+3. **Email deliverability**. Magic links only work if emails arrive. Resend handles SPF/DKIM/DMARC, but initial setup, domain verification, and inbox placement testing can take time.
+4. **Cloudflare Turnstile integration**. Requires server-side verification of the captcha token. The API is simple, but handling failures (network issues, invalid tokens, expired tokens) needs careful error UX.
+
+### Testing Scope
+- **Unit tests**: Config parsing, session token generation/hashing, magic link token lifecycle, CSRF header validation, settings validation (serde + validator), `AppError` response formatting
+- **Integration tests**: Full auth flow (register -> verify -> me -> logout), settings CRUD with auth, admin CLI command, rate limiting on auth endpoints (verify lockout after N failures), 401 on unauthenticated access
+- **Frontend**: Manual smoke testing of all screens and flows (automated E2E testing deferred to a later phase when there is more to test)
+
+### Milestones
+1. **M1.1 -- Rust skeleton compiles and serves "Hello World"**: Axum router, tracing, config loading, Postgres pool connected, migrations run. Docker build works.
+2. **M1.2 -- Auth flow works end-to-end**: Register, magic link email sent (Resend), verify token, session cookie set, `GET /me` returns user, logout clears session. CLI create-admin works.
+3. **M1.3 -- SolidJS shell renders**: Login page, navbar, settings page (static, no API calls yet). Tailwind styling matches the current app's visual language. Mobile hamburger menu works.
+4. **M1.4 -- Frontend + backend integrated**: SolidJS auth context calls the API. Login/signup flow works through the UI. Settings page reads/writes via the API. Session expiry redirects to login.
+5. **M1.5 -- Tests and hardening**: Unit and integration tests pass. Security headers configured. CSRF protection tested. Rate limiting on auth endpoints verified.
+
+---
+
+## Phase 2: Sources CRUD + Scraper Service
+
+### Goal
+Add the custom sources management feature (CRUD, bulk import, CSV import/export) and build the URL scraper service that will be used during synthesis generation.
+
+### Deliverables
+
+**Backend**:
+- Database migration: `sources` table
+- Sources API:
+  - `GET /api/v1/sources` -- list user's sources
+  - `POST /api/v1/sources` -- add a single source (title + URL, validated)
+  - `DELETE /api/v1/sources/:id` -- delete a source (ownership check)
+  - `POST /api/v1/sources/bulk` -- bulk import (JSON array)
+  - `POST /api/v1/sources/import-csv` -- CSV import (multipart upload)
+  - `GET /api/v1/sources/export-csv` -- CSV export download
+- Input validation: URL format validation, title length limits, max sources per user
+- Scraper service (`services/scraper.rs`):
+  - `reqwest` HTTP client (shared from `AppState`, with timeouts: 5s connect, 15s response, 30s total)
+  - SSRF prevention: DNS resolution check against private IP ranges, protocol restriction (http/https only), redirect validation
+  - HTML parsing with `scraper` crate: soft-404 detection, publication date extraction (meta tags, JSON-LD, `<time>` elements), body text extraction (max 4000 chars, strip scripts/nav/footer)
+  - Custom User-Agent header
+
+**Frontend**:
+- Sources page:
+  - List view with title and URL for each source
+  - Add form: title + URL fields with validation feedback
+  - Delete with standardized confirmation dialog (same pattern as settings)
+  - Bulk import via textarea
+  - CSV import (file picker) and export (download button)
+- Empty state with onboarding hint
+
+### Definition of Done
+- User can add, view, and delete custom sources
+- Bulk import (JSON and CSV) works correctly
+- CSV export downloads a valid file
+- URL validation rejects malformed URLs
+- Ownership isolation: user A cannot see or delete user B's sources
+- Scraper service can fetch a URL, parse HTML, detect soft-404s, extract publication dates, and extract body text
+- SSRF protection rejects requests to private/internal IPs
+
+### Dependencies
+Phase 1 (auth, DB pool, frontend scaffolding, Docker setup)
+
+### Risk Factors
+1. **Scraper robustness**. Real-world HTML is messy. Publication date extraction from meta tags, JSON-LD, and `<time>` elements covers many sites but not all. Expect edge cases.
+2. **SSRF prevention correctness**. DNS rebinding attacks can bypass naive IP checks. The implementation must resolve DNS and check the IP before connecting, and re-check on redirects.
+3. **CSV parsing**. Malformed CSV files, encoding issues (UTF-8 BOM, Windows line endings), and large files can cause problems.
+
+### Testing Scope
+- **Unit tests**: URL validation, SSRF IP range checks, HTML parsing (soft-404 detection, date extraction, body text extraction -- use fixture HTML files), CSV parsing/generation
+- **Integration tests**: Full CRUD lifecycle for sources (create, list, delete), bulk import, CSV import/export, ownership isolation (user A cannot access user B's sources), SSRF rejection for private IPs
+
+### Milestones
+1. **M2.1 -- Sources CRUD API complete**: All endpoints working with auth. Integration tests pass.
+2. **M2.2 -- Scraper service complete**: Fetches, parses, validates URLs. SSRF protection in place. Unit tests with fixture HTML pass.
+3. **M2.3 -- Frontend sources page complete**: All interactions working, CSV import/export, empty state.
+
+---
+
+## Phase 3: Admin Module
+
+### Goal
+Build the admin interface for curating LLM providers/models and configuring rate limits. This phase establishes the provider/model catalog that users will select from in their settings.
+
+### Deliverables
+
+**Backend**:
+- Database migrations: `llm_providers` table (provider name, display name, models JSON array, is_enabled, created_at, updated_at), `rate_limits` table (per-provider limits)
+  - Note: In the decisions doc, users bring their own API keys. The `llm_providers` table here stores the admin-curated list of available providers and models, NOT API keys. User API keys are stored separately (see Phase 4).
+- Admin API (all require admin role):
+  - `GET /api/v1/admin/providers` -- list all provider configs
+  - `POST /api/v1/admin/providers` -- add/update a provider config (provider name, display name, list of enabled models)
+  - `DELETE /api/v1/admin/providers/:id` -- remove a provider
+  - `GET /api/v1/admin/rate-limits` -- get rate limit configs
+  - `PUT /api/v1/admin/rate-limits/:provider_id` -- update rate limit config
+  - `GET /api/v1/admin/users` -- list all users
+  - `PUT /api/v1/admin/users/:id/role` -- change user role
+- Public endpoint (authenticated, non-admin):
+  - `GET /api/v1/config/providers` -- list enabled providers and their model names (no sensitive data)
+- `RequireAdmin` middleware layer (checks `user.role == "admin"`, returns 403 otherwise)
+- Rate limiter service: in-memory token-bucket per provider (using `DashMap`), configurable from admin, hot-reload on config change
+- Audit logging table and writes for admin actions
+
+**Frontend**:
+- Admin layout at `/admin` (separate route prefix, sidebar navigation)
+- Admin nav: visible only to admin users (hidden from DOM for non-admins)
+- Provider configuration page (`/admin/providers`):
+  - Card/tab per provider (Gemini, OpenAI, Anthropic)
+  - Enable/disable toggle per provider
+  - Model list management (checkboxes to enable/disable specific models)
+  - Default model selection (dropdown)
+  - Status indicators (configured/not configured)
+- Rate limit configuration page (`/admin/rate-limits`):
+  - Per-provider rate limit fields (requests per minute)
+  - Global limits
+  - Save button
+- User management page (`/admin/users`):
+  - User list with email, role, creation date
+  - Role change (promote/demote admin)
+
+**Settings page update**:
+- Replace the hardcoded AI model dropdown with a dynamic two-level selection:
+  - Provider dropdown (populated from `GET /api/v1/config/providers`)
+  - Model dropdown (populated based on selected provider)
+- If only one provider is configured, hide the provider dropdown
+
+### Definition of Done
+- Admin can add, configure, enable/disable providers and models
+- Admin can configure per-provider rate limits
+- Admin can view user list and change roles
+- Non-admin users cannot access admin pages (403 from API, routes hidden in UI)
+- `GET /api/v1/config/providers` returns the list of enabled providers and models
+- Settings page dynamically populates provider/model dropdowns from the admin config
+- Rate limiter enforces configured limits
+- Audit log records all admin actions
+
+### Dependencies
+Phase 1 (auth with admin role, DB, frontend scaffolding)
+
+### Risk Factors
+1. **Rate limiter complexity**. In-memory state with hot-reload from DB requires careful concurrency handling (DashMap + atomic operations). Edge cases around config reload while requests are in flight.
+2. **Admin UX complexity**. The provider configuration page has many interacting elements (enable/disable, model list, default model). Getting the UX right takes iteration.
+3. **Role-based access control**. Must be watertight -- every admin endpoint must be protected both in the frontend (route guard) and backend (middleware). A missed check is a privilege escalation vulnerability.
+
+### Testing Scope
+- **Unit tests**: Rate limiter (token bucket logic, config reload), admin role check middleware
+- **Integration tests**: Admin CRUD for providers, rate limits. Non-admin access rejection (403). Role change. Audit log entries created. Public config endpoint returns correct data. Settings page provider/model population.
+
+### Milestones
+1. **M3.1 -- Admin API complete**: All admin endpoints working with role protection. Integration tests pass.
+2. **M3.2 -- Rate limiter service**: In-memory rate limiter with DB-backed config. Hot-reload tested.
+3. **M3.3 -- Admin frontend complete**: All admin pages functional. Non-admin users see no admin UI.
+4. **M3.4 -- Settings page updated**: Dynamic provider/model selection working.
+
+---
+
+## Phase 4: LLM Provider Abstraction (Gemini First)
+
+### Goal
+Implement the LLM provider trait and the first concrete implementation (Google Gemini), including user API key management. Prove that the abstraction works for structured output and web search grounding.
+
+### Deliverables
+
+**Backend**:
+- Database migration: `user_api_keys` table (user_id, provider, encrypted_key using AES-256-GCM, nonce, key_prefix for display, created_at, updated_at)
+- API key encryption service:
+  - Master key from `MASTER_KEY_SECRET` environment variable
+  - AES-256-GCM encryption/decryption using `aes-gcm` crate
+  - Per-key unique nonce via `OsRng`
+  - Keys decrypted in memory only when making LLM calls, dropped immediately after
+  - `secrecy` + `zeroize` crates for sensitive value handling
+- User API key endpoints:
+  - `GET /api/v1/user/api-keys` -- list user's keys (provider + key_prefix only, never the full key)
+  - `POST /api/v1/user/api-keys` -- add/update an API key for a provider
+  - `DELETE /api/v1/user/api-keys/:provider` -- remove a key
+  - `POST /api/v1/user/api-keys/:provider/test` -- test the key with a minimal LLM call
+- `LlmProvider` trait:
+  ```
+  provider_id() -> &str
+  generate_search_pass(model, system_prompt, user_prompt, response_schema) -> Result<Value>
+  generate_rewrite_pass(model, system_prompt, user_prompt, response_schema) -> Result<Value>
+  ```
+- `GeminiProvider` implementation:
+  - `generateContent` API call with `googleSearch` tool for Pass 1
+  - Structured output via `responseSchema` + `responseMimeType: "application/json"`
+  - Standard generation (no tools) for Pass 2
+  - Dynamic category schema construction from user settings
+- Provider factory function: creates the correct provider implementation from config + user's decrypted API key
+
+**Frontend**:
+- User API key management in Settings page:
+  - Per-provider section showing key status (configured/not configured, key prefix)
+  - Add/update key input (masked, with show/hide toggle)
+  - Test button per provider (calls test endpoint, shows success/failure)
+  - Delete key button
+- Warning display when a provider does not support web search grounding
+
+### Definition of Done
+- User can add, test, and remove their Gemini API key
+- API keys are encrypted at rest (AES-256-GCM) and never returned in full via the API
+- The `LlmProvider` trait is defined and `GeminiProvider` passes a manual test:
+  - Pass 1: structured search results with `googleSearch` grounding
+  - Pass 2: rewrite with structured output
+- Test endpoint validates the key works
+- Provider factory correctly creates a `GeminiProvider` from config + user key
+
+### Dependencies
+- Phase 2 (scraper service -- used in the pipeline validation)
+- Phase 3 (admin-curated provider/model list -- the factory reads from this)
+
+### Risk Factors
+1. **Gemini API specifics**. The `responseSchema` for structured JSON output + `googleSearch` tool configuration via the REST API (not a Rust SDK) requires careful request construction. Gemini's API versions and response formats can change.
+2. **Encryption correctness**. AES-256-GCM with per-key nonces must be implemented correctly. A nonce reuse with the same key breaks GCM security entirely. Using `OsRng` for nonce generation mitigates this.
+3. **Structured output parsing**. The dynamic schema (generated from user categories) must produce valid JSON Schema that Gemini accepts. Edge cases in category names (special characters, very long names) can break schema generation.
+4. **API key security**. The full lifecycle (transmit over HTTPS, encrypt at rest, decrypt in memory, drop after use) has multiple points where a mistake could leak keys (logging, error messages, debug output).
+
+### Testing Scope
+- **Unit tests**: AES-256-GCM encryption round-trip, key prefix extraction, dynamic schema generation from categories, provider factory (mocked), Gemini request/response serialization
+- **Integration tests**: User API key CRUD (verify encryption at rest, verify key is never returned in full), test endpoint (with a mock HTTP server standing in for Gemini), provider trait contract tests (mock implementation)
+- **Manual test**: End-to-end Gemini call with a real API key (not in CI, developer-run)
+
+### Milestones
+1. **M4.1 -- User API key management**: CRUD endpoints working, encryption at rest verified, frontend key management in Settings.
+2. **M4.2 -- LlmProvider trait defined**: Trait, types, factory function. Mock implementation for testing.
+3. **M4.3 -- GeminiProvider working**: Both passes (search + rewrite) produce valid structured output. Manual test with real API key succeeds.
+4. **M4.4 -- Dynamic schema generation**: Category-based schema construction tested with various category configurations.
+
+---
+
+## Phase 5: Generation Pipeline + SSE Progress
+
+### Goal
+Wire everything together into the full synthesis generation pipeline: user triggers generation, backend runs the two-pass pipeline (search -> scrape/validate -> rewrite), sends real-time progress via SSE, and saves the result. The user can view the synthesis.
+
+### Deliverables
+
+**Backend**:
+- Database migration: `syntheses` table (user_id, week, sections JSON, status, created_at), `generation_jobs` table (ephemeral, or in-memory `DashMap`)
+- Generation pipeline orchestration (`services/synthesis.rs`):
+  1. Load user settings and sources
+  2. Resolve provider + model (from user's settings + admin config + user's API key)
+  3. Build dynamic schema from categories
+  4. Rate limit check (acquire slot)
+  5. Pass 1: Search (via `LlmProvider::generate_search_pass`)
+  6. Validate and scrape URLs (via scraper service, with SSRF protection)
+  7. Rate limit check (acquire slot for Pass 2)
+  8. Pass 2: Rewrite (via `LlmProvider::generate_rewrite_pass` with scraped content)
+  9. Parse and validate structured output
+  10. Save synthesis to database
+- Async generation API:
+  - `POST /api/v1/syntheses/generate` -- triggers generation, returns immediately with `job_id` (202 Accepted)
+  - `GET /api/v1/syntheses/generate/:job_id/progress` -- SSE endpoint streaming progress events
+- SSE progress events:
+  - `{ step: "search", message: "Recherche d'actualites en cours...", percent: 10 }`
+  - `{ step: "scraping", message: "Verification des sources (3/12)...", percent: 40 }`
+  - `{ step: "rewrite", message: "Redaction des resumes...", percent: 75 }`
+  - `{ step: "saving", message: "Sauvegarde...", percent: 95 }`
+  - `complete` event with `synthesis_id`
+  - `error` event with message
+- Syntheses API:
+  - `GET /api/v1/syntheses` -- list user's syntheses (paginated, sorted by created_at desc)
+  - `GET /api/v1/syntheses/:id` -- get synthesis detail
+  - `DELETE /api/v1/syntheses/:id` -- delete a synthesis (ownership check, confirmation handled by frontend)
+- Job state management: in-memory `DashMap<String, JobStatus>` with TTL cleanup (jobs expire after 1 hour)
+- Prompt construction: system prompt and user prompt templates built from user settings (theme, categories, max age, search agent behavior, custom sources)
+
+**Frontend**:
+- Home page (Dashboard):
+  - Grid of synthesis cards (responsive: 1/2/3 columns)
+  - Each card: week badge, creation date, preview of first section items (line-clamped)
+  - Footer: "Lire la synthese" link, delete button with confirmation dialog
+  - Empty state with onboarding hint
+  - Banner when a generation is in progress ("Une generation est en cours...")
+- Generate page:
+  - Confirmation text showing theme, age window, provider, model
+  - "Lancer la generation" button
+  - Progress bar with step descriptions (SSE-driven)
+  - Step checklist (done/in-progress/pending)
+  - "Vous pouvez quitter cette page" note
+  - Error display with retry option
+  - Auto-redirect to synthesis detail on completion
+- Synthesis detail page:
+  - Section-by-section display: section title, then cards for each news item (title as external link, summary paragraph)
+  - Back navigation
+  - Delete button with confirmation dialog
+- SSE client: `EventSource` connection management, reconnection on disconnect, state synchronization if user navigates away and returns
+
+### Definition of Done
+- User clicks "Lancer la generation" and sees real-time progress via SSE
+- Generation runs asynchronously -- user can navigate away and return
+- Home page shows an in-progress banner during generation
+- On completion, the synthesis is saved and viewable
+- Synthesis detail shows all sections with items, titles as links, and summaries
+- User can delete syntheses
+- Ownership isolation: user A cannot view or delete user B's syntheses
+- Generation failures display an error message with context
+- Rate limiting prevents excessive generation requests
+
+### Dependencies
+Phase 4 (LLM provider working with Gemini)
+
+### Risk Factors
+1. **Pipeline reliability**. The two-pass pipeline with scraping in between is complex. Failures at any stage (LLM timeout, scraping failure, invalid structured output) must be handled gracefully. Partial results (some URLs fail to scrape) should not abort the entire generation.
+2. **SSE connection management**. SSE connections can be dropped by reverse proxies, load balancers, or browser timeouts. The frontend must handle reconnection and state recovery. The backend must not leak resources (orphaned SSE connections, zombie tokio tasks).
+3. **Structured output parsing**. LLMs occasionally produce malformed JSON even with schema constraints. The pipeline must handle parsing failures gracefully (retry once, or fall back to best-effort extraction).
+4. **Generation duration**. End-to-end generation (2 LLM calls + N URL scrapes) can take 30-90+ seconds. The async model handles this, but progress reporting must be accurate (not fake percentages).
+5. **Concurrent generation**. What happens if a user triggers a second generation while one is running? Decision needed: reject with "already in progress" or queue.
+
+### Testing Scope
+- **Unit tests**: Prompt construction (from settings + sources), structured output parsing (valid and malformed JSON), job status management, SSE event serialization
+- **Integration tests**: Full generation pipeline with mocked LLM provider (returns canned structured output) and mocked scraper (returns canned HTML). Verify: correct DB state after generation, SSE events sequence, error handling (LLM failure, scraper failure). Syntheses CRUD with ownership isolation.
+- **E2E test**: Manual test with real Gemini API key. Full flow: configure settings, add sources, generate, view result.
+
+### Milestones
+1. **M5.1 -- Syntheses CRUD**: List, get, delete endpoints and frontend pages. Works with manually inserted test data.
+2. **M5.2 -- Pipeline orchestration**: Full two-pass pipeline runs synchronously (no SSE yet) with mocked LLM. Saves result to DB.
+3. **M5.3 -- SSE progress**: Async generation with SSE streaming. Frontend displays progress bar and step checklist.
+4. **M5.4 -- Home page integration**: In-progress banner, auto-refresh on completion, empty state.
+5. **M5.5 -- End-to-end with real LLM**: Manual test with Gemini. Prompt tuning. Error handling hardened.
+
+---
+
+## Phase 6: Multi-Provider (OpenAI + Anthropic)
+
+### Goal
+Add OpenAI and Anthropic as LLM providers, implementing the `LlmProvider` trait for each with their respective web search and structured output capabilities. The generation pipeline adapts per provider.
+
+### Deliverables
+
+**Backend**:
+- `OpenAiProvider` implementation:
+  - Pass 1: Uses OpenAI Responses API with `web_search` tool for grounded search results. Structured output via `response_format: { type: "json_schema", json_schema: ... }`.
+  - Pass 2: Standard chat completion with structured JSON output.
+  - Model mapping: validate user-selected model against admin-enabled models.
+- `AnthropicProvider` implementation:
+  - Pass 1: Uses Claude's `web_search` tool for grounded results. Structured output via tool-use pattern (define a tool whose input schema matches the desired output, instruct Claude to call it).
+  - Pass 2: Standard message with JSON output instructions. Server-side parsing and validation (Anthropic does not have native JSON schema enforcement as robust as Gemini/OpenAI).
+- Pipeline adaptation per provider:
+  - Decision logic: if native web search grounding produces high-quality results (detected by checking citation count, URL validity), skip the scrape/rewrite pass.
+  - If not, fall back to the full two-pass pipeline.
+  - Provider-specific prompt adjustments (each provider responds differently to the same prompt structure).
+- Error handling per provider: different error codes, rate limit headers, and retry semantics for each provider's API.
+
+**Frontend**:
+- Settings page: provider dropdown now populated with all admin-enabled providers (Gemini, OpenAI, Anthropic)
+- Generate page: warning when selected provider has limited web search capabilities
+- Provider-specific info text in settings ("La recherche web en temps reel est disponible avec ce fournisseur" vs "Les resultats seront bases sur les connaissances du modele")
+
+### Definition of Done
+- User can select OpenAI or Anthropic as their provider, add their API key, and generate a synthesis
+- Structured output is correctly parsed for all three providers
+- Web search grounding works for all three providers (using their respective tools)
+- Pipeline adapts per provider (skip scrape pass when native grounding is sufficient)
+- Error handling is provider-specific (correct error messages for quota exceeded, invalid key, model not available, etc.)
+- All existing Gemini functionality continues to work unchanged
+
+### Dependencies
+Phase 5 (generation pipeline working end-to-end with Gemini)
+
+### Risk Factors
+1. **Provider API differences are deeper than they appear**. Each provider's web search tool returns results in different formats with different citation structures. The abstraction must handle this without becoming a leaky mess.
+2. **Anthropic structured output**. Claude does not have Gemini/OpenAI's level of JSON schema enforcement. The backend must handle parsing failures and potentially retry with clearer instructions.
+3. **Testing across providers**. Each provider requires a real API key for meaningful testing. Mocks can only go so far -- real provider behavior (latency, rate limits, output quality) varies.
+4. **Pipeline adaptation heuristic**. Deciding when to skip the scrape/rewrite pass is a quality judgment. Too aggressive skipping produces lower-quality summaries. Too conservative means the pipeline is always slow.
+
+### Testing Scope
+- **Unit tests**: OpenAI and Anthropic request/response serialization, provider-specific error mapping, pipeline adaptation logic
+- **Integration tests**: Full pipeline with mocked OpenAI and Anthropic HTTP responses. Verify structured output parsing, error handling, pipeline adaptation.
+- **Manual tests**: End-to-end generation with real OpenAI and Anthropic API keys. Quality comparison across providers.
+
+### Milestones
+1. **M6.1 -- OpenAiProvider working**: Both passes produce valid structured output. Manual test with real key.
+2. **M6.2 -- AnthropicProvider working**: Both passes produce valid structured output. Structured output parsing handles edge cases. Manual test with real key.
+3. **M6.3 -- Pipeline adaptation**: Provider-specific behavior (skip scrape when appropriate) implemented and tested.
+4. **M6.4 -- Frontend updated**: Provider selection, warnings, and info text. All three providers selectable.
+
+---
+
+## Phase 7: Email (Resend) + Export (PDF/Markdown)
+
+### Goal
+Add the ability to send a synthesis by email (via Resend) and export it as PDF or Markdown.
+
+### Deliverables
+
+**Backend**:
+- Email sending service (`services/email.rs` -- extends the existing magic link email service):
+  - `POST /api/v1/syntheses/:id/send-email` -- send synthesis to a specified email address
+  - HTML email template: renders the synthesis (sections, items, links) as a formatted email
+  - Plain-text fallback
+  - Sender address configured via environment variable
+  - Default recipient: the user's own email
+- Export service:
+  - `GET /api/v1/syntheses/:id/export/markdown` -- returns the synthesis as a Markdown file download
+  - `GET /api/v1/syntheses/:id/export/pdf` -- returns the synthesis as a PDF file download
+  - Markdown generation: convert sections/items to Markdown format (headers, bullet points, links)
+  - PDF generation: use a Rust PDF library (e.g., `printpdf` or `genpdf`, or convert Markdown to PDF via `pulldown-cmark` + a PDF renderer)
+
+**Frontend**:
+- Synthesis detail page additions:
+  - "Envoyer par email" button with email input (pre-filled with user's email)
+  - "S'envoyer a soi-meme" quick button
+  - Export dropdown: "Exporter en Markdown" and "Exporter en PDF"
+  - Loading states and success/error feedback for email and export actions
+
+### Definition of Done
+- User can send a synthesis by email to any address (via Resend)
+- Email is well-formatted HTML with plain-text fallback
+- User can export a synthesis as Markdown (downloads a `.md` file)
+- User can export a synthesis as PDF (downloads a `.pdf` file)
+- Default email recipient is the user's own email
+- Ownership check: user can only email/export their own syntheses
+
+### Dependencies
+Phase 1 (Resend integration already exists for magic links, auth). Best done after Phase 5 (so there is actual content to email/export).
+
+### Risk Factors
+1. **PDF generation in Rust**. The Rust PDF ecosystem is less mature than in other languages. `genpdf` is the most ergonomic option but has limited styling control. `printpdf` is low-level. Consider generating HTML and using a headless browser or `wkhtmltopdf` as a last resort (adds a Docker dependency).
+2. **Email formatting**. HTML emails are notoriously difficult to render consistently across email clients. Keep the template simple (tables-based layout, inline CSS, no external resources).
+3. **Resend rate limits**. The free tier has limits. Bulk email sending (e.g., user sends to a mailing list) could hit these. Rate limit email sends per user.
+
+### Testing Scope
+- **Unit tests**: Markdown generation from synthesis data, HTML email template rendering, PDF generation (verify output is valid PDF)
+- **Integration tests**: Email endpoint (mock Resend API), export endpoints (verify correct Content-Type and Content-Disposition headers, verify file content), ownership isolation
+
+### Milestones
+1. **M7.1 -- Email sending**: Backend endpoint working, HTML template rendered, Resend integration tested.
+2. **M7.2 -- Markdown export**: Endpoint returns correctly formatted `.md` file.
+3. **M7.3 -- PDF export**: Endpoint returns a valid PDF.
+4. **M7.4 -- Frontend integration**: Email and export buttons on synthesis detail page, with loading states and feedback.
+
+---
+
+## Summary Table
+
+| Phase | Name | Core Capability | Key Risk | Estimated Relative Effort |
+|-------|------|----------------|----------|--------------------------|
+| 1 | Foundation | Stack proof, auth, settings CRUD | Rust learning curve + hand-rolled auth | Very Large |
+| 2 | Sources + Scraper | Sources CRUD, URL scraping | Scraper robustness, SSRF | Medium |
+| 3 | Admin Module | Provider/model curation, rate limits | Rate limiter concurrency, RBAC | Medium |
+| 4 | LLM Abstraction (Gemini) | Provider trait, encryption, Gemini impl | Structured output, API key security | Large |
+| 5 | Generation Pipeline + SSE | End-to-end synthesis generation | Pipeline reliability, SSE management | Very Large |
+| 6 | Multi-Provider | OpenAI + Anthropic | Provider API differences, quality | Large |
+| 7 | Email + Export | Resend email, PDF/Markdown export | PDF generation in Rust | Small-Medium |
+
+---
+
+## Cross-Phase Concerns
+
+These items are not isolated to a single phase but evolve incrementally:
+
+### Testing Strategy
+- **Phase 1**: Unit tests for core utilities, integration tests for auth flow. Establish CI pipeline (cargo test + clippy + cargo audit).
+- **Phase 2-3**: Integration tests grow with each CRUD module. Introduce fixture-based testing for scraper.
+- **Phase 4**: Add mock-based testing for external API calls. Provider trait contract tests.
+- **Phase 5**: First E2E tests (pipeline with mocked externals). SSE client testing.
+- **Phase 6**: Expand provider mocks. Cross-provider output comparison.
+- **Phase 7**: Template rendering tests. Full E2E manual test of the complete application.
+
+### Security Hardening
+- **Phase 1**: Auth, CSRF, CSP, security headers, rate limiting on auth endpoints, session security.
+- **Phase 2**: SSRF prevention in scraper.
+- **Phase 3**: RBAC, audit logging.
+- **Phase 4**: API key encryption at rest, secret handling (secrecy + zeroize).
+- **Phase 5**: Input sanitization for prompt injection (max lengths, delimiter patterns).
+- **Phase 6**: Per-provider error handling (avoid leaking provider API details to users).
+- **Phase 7**: Email input validation (prevent header injection).
+
+### i18n Readiness
+- All phases: user-facing strings go through the locale file (`fr.ts`). No hardcoded French strings in component logic.
+- Phase 1 establishes the pattern. Subsequent phases follow it.
+
+### Docker and Deployment
+- Phase 1 establishes the Dockerfile and docker-compose.yml.
+- Subsequent phases only add environment variables (documented in `.env.example`).
+- No deployment changes required between phases -- the same `docker compose up` works throughout.
diff --git a/docs/implementation-plan/02-backend-plan.md b/docs/implementation-plan/02-backend-plan.md
new file mode 100644
index 0000000..1152bb3
--- /dev/null
+++ b/docs/implementation-plan/02-backend-plan.md
@@ -0,0 +1,3189 @@
+# Backend Implementation Plan: AI Weekly Synth
+
+**Date**: 2026-03-21
+**Role**: Backend Implementation Planner
+**Target**: Rust (Axum) + PostgreSQL + Multi-LLM
+
+---
+
+## Table of Contents
+
+1. [Project Structure](#1-project-structure)
+2. [Database Schema](#2-database-schema)
+3. [API Endpoints](#3-api-endpoints)
+4. [Authentication & Authorization](#4-authentication--authorization)
+5. [LLM Provider Abstraction](#5-llm-provider-abstraction)
+6. [URL Scraping (Server-Side)](#6-url-scraping-server-side)
+7. [Async Generation & SSE](#7-async-generation--sse)
+8. [Email (Resend Integration)](#8-email-resend-integration)
+9. [Encryption](#9-encryption)
+10. [Error Handling](#10-error-handling)
+11. [Testing Strategy](#11-testing-strategy)
+
+---
+
+## 1. Project Structure
+
+### 1.1 Single Crate with Module Hierarchy
+
+A single crate is sufficient for this application. A Cargo workspace adds overhead (inter-crate dependency management, slower incremental compilation across crate boundaries) without meaningful benefit for an app of this size. If the LLM abstraction layer grows significantly, it can be extracted into a workspace member later.
+
+```
+ai-synth-backend/
+├── Cargo.toml
+├── Cargo.lock
+├── .env.example
+├── migrations/
+│   ├── 20260321000001_create_users.sql
+│   ├── 20260321000002_create_sessions.sql
+│   ├── 20260321000003_create_magic_link_tokens.sql
+│   ├── 20260321000004_create_user_settings.sql
+│   ├── 20260321000005_create_sources.sql
+│   ├── 20260321000006_create_syntheses.sql
+│   ├── 20260321000007_create_user_provider_keys.sql
+│   ├── 20260321000008_create_admin_provider_models.sql
+│   ├── 20260321000009_create_admin_rate_limits.sql
+│   └── 20260321000010_create_generation_jobs.sql
+├── src/
+│   ├── main.rs                        # Entry point: CLI (create-admin, serve), tracing init, DB pool, run server
+│   ├── cli.rs                         # CLI argument parsing (clap): serve, create-admin
+│   ├── config.rs                      # AppConfig struct, loaded from env vars via dotenvy
+│   ├── app_state.rs                   # AppState: PgPool, reqwest::Client, AppConfig, RateLimiter, JobStore
+│   ├── error.rs                       # AppError enum, IntoResponse impl, From impls
+│   ├── router.rs                      # All route definitions, middleware wiring, layer composition
+│   │
+│   ├── middleware/
+│   │   ├── mod.rs
+│   │   ├── auth.rs                    # AuthUser extractor (session cookie -> user lookup)
+│   │   ├── admin.rs                   # AdminUser extractor (AuthUser + role == admin check)
+│   │   └── csrf.rs                    # X-Requested-With header check on mutating methods
+│   │
+│   ├── models/
+│   │   ├── mod.rs
+│   │   ├── user.rs                    # User, UserRole, CreateUser
+│   │   ├── session.rs                 # Session
+│   │   ├── magic_link.rs             # MagicLinkToken
+│   │   ├── settings.rs               # UserSettings, UpdateSettings
+│   │   ├── source.rs                  # Source, CreateSource
+│   │   ├── synthesis.rs               # Synthesis, NewsSection, NewsItem
+│   │   ├── provider_key.rs            # UserProviderKey, CreateProviderKey
+│   │   ├── admin_model.rs             # AdminProviderModel
+│   │   ├── rate_limit.rs              # AdminRateLimit
+│   │   └── generation_job.rs          # GenerationJob, JobStatus, JobProgress
+│   │
+│   ├── handlers/
+│   │   ├── mod.rs
+│   │   ├── auth.rs                    # register, request_magic_link, verify_magic_link, logout, me
+│   │   ├── syntheses.rs               # list, get, delete, trigger_generate
+│   │   ├── sources.rs                 # list, create, delete
+│   │   ├── settings.rs                # get, update
+│   │   ├── provider_keys.rs           # list, add, delete (user's own API keys)
+│   │   ├── generation.rs              # SSE progress endpoint, job status
+│   │   ├── admin.rs                   # provider models CRUD, rate limits, user list
+│   │   └── health.rs                  # GET /health
+│   │
+│   ├── services/
+│   │   ├── mod.rs
+│   │   ├── llm/
+│   │   │   ├── mod.rs                 # LlmProvider trait, ProviderCapabilities, create_provider factory
+│   │   │   ├── types.rs               # SearchRequest, SearchResponse, RewriteRequest, shared types
+│   │   │   ├── gemini.rs              # GeminiProvider implementation
+│   │   │   ├── openai.rs              # OpenAiProvider implementation
+│   │   │   └── anthropic.rs           # AnthropicProvider implementation
+│   │   ├── generation.rs              # GenerationPipeline: orchestrates search -> scrape -> rewrite
+│   │   ├── scraper.rs                 # URL fetching, HTML parsing, date extraction, SSRF checks
+│   │   ├── email.rs                   # Resend HTTP API client (magic links + synthesis delivery)
+│   │   ├── captcha.rs                 # Cloudflare Turnstile verification
+│   │   ├── encryption.rs             # AES-256-GCM encrypt/decrypt for user API keys
+│   │   └── rate_limiter.rs            # Token-bucket rate limiter (per-provider, in-memory)
+│   │
+│   ├── db/
+│   │   ├── mod.rs
+│   │   ├── users.rs                   # find_by_email, find_by_id, create, update_role, list_all
+│   │   ├── sessions.rs                # create, find_by_hash, delete, delete_expired, delete_all_for_user
+│   │   ├── magic_links.rs             # create, consume (atomic find + mark used), delete_expired
+│   │   ├── settings.rs                # get_or_default, upsert
+│   │   ├── sources.rs                 # list_by_user, create, delete
+│   │   ├── syntheses.rs               # list_by_user, get_by_id, create, delete
+│   │   ├── provider_keys.rs           # list_by_user, create, delete, get_decrypted
+│   │   ├── admin_models.rs            # list_all, list_enabled, create, update, delete
+│   │   └── admin_rate_limits.rs       # get_by_provider, upsert, list_all
+│   │
+│   └── util/
+│       ├── mod.rs
+│       ├── token.rs                   # Secure random token generation, SHA-256 hashing
+│       └── validation.rs              # Shared validation helpers (URL scheme check, etc.)
+│
+└── tests/
+    ├── common/
+    │   └── mod.rs                     # Test helpers: setup DB, create test user, create test session
+    ├── api/
+    │   ├── auth_test.rs
+    │   ├── syntheses_test.rs
+    │   ├── sources_test.rs
+    │   ├── settings_test.rs
+    │   └── admin_test.rs
+    └── services/
+        ├── encryption_test.rs
+        ├── scraper_test.rs
+        └── rate_limiter_test.rs
+```
+
+### 1.2 Key Dependencies
+
+```toml
+[package]
+name = "ai-synth-backend"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+# Web framework
+axum = { version = "0.8", features = ["macros"] }
+axum-extra = { version = "0.10", features = ["cookie", "typed-header"] }
+tower = { version = "0.5", features = ["util", "timeout"] }
+tower-http = { version = "0.6", features = ["fs", "cors", "trace", "set-header"] }
+tokio = { version = "1", features = ["full"] }
+
+# Database
+sqlx = { version = "0.8", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "chrono", "json"] }
+
+# Serialization
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# HTTP client (LLM APIs + scraping)
+reqwest = { version = "0.12", features = ["json", "stream"] }
+
+# HTML parsing
+scraper = "0.22"
+
+# Date/time
+chrono = { version = "0.4", features = ["serde"] }
+
+# Cryptography
+sha2 = "0.10"               # SHA-256 for token hashing
+rand = "0.8"                 # OsRng for secure random generation
+aes-gcm = "0.10"            # AES-256-GCM for API key encryption
+base64 = "0.22"             # Encoding tokens and encrypted data
+
+# Secrets management
+secrecy = { version = "0.10", features = ["serde"] }
+zeroize = "1"
+
+# Validation
+validator = { version = "0.19", features = ["derive"] }
+
+# Logging
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
+
+# Config
+dotenvy = "0.15"
+clap = { version = "4", features = ["derive"] }
+
+# Concurrency
+dashmap = "6"
+tokio-stream = "0.1"        # For SSE streaming
+
+# Error handling
+anyhow = "1"
+thiserror = "1"
+
+# UUID
+uuid = { version = "1", features = ["v4", "serde"] }
+
+# URL parsing
+url = "2"
+
+# Async trait (still needed for trait objects)
+async-trait = "0.1"
+
+# Futures utilities
+futures = "0.3"
+
+[dev-dependencies]
+sqlx = { version = "0.8", features = ["runtime-tokio", "tls-rustls", "postgres"] }
+tower = { version = "0.5", features = ["util"] }
+http-body-util = "0.1"
+hyper = "1"
+```
+
+**Justification for key choices:**
+
+| Crate | Why |
+|---|---|
+| `axum 0.8` | Tower-based, composes naturally with middleware layers, best ergonomics for extractors |
+| `sqlx 0.8` with `postgres` | Compile-time query checking, native async, direct Postgres support (decision: no SQLite) |
+| `reqwest 0.12` | Industry standard async HTTP client, reused for LLM APIs and scraping |
+| `scraper 0.22` | Built on html5ever (same parser as Firefox), reliable HTML parsing |
+| `aes-gcm 0.10` | Pure Rust authenticated encryption, no OpenSSL dependency |
+| `secrecy + zeroize` | Prevents accidental logging of secrets, zeroes memory on drop |
+| `dashmap 6` | Lock-free concurrent HashMap for rate limiter and job store |
+| `clap 4` | CLI argument parsing for `serve` and `create-admin` subcommands |
+| `tokio-stream` | SSE implementation via `axum::response::Sse` |
+| `chrono` over `time` | Better serde integration, more format support, widely used |
+
+---
+
+## 2. Database Schema
+
+All migrations use PostgreSQL-native types. UUIDs are `UUID` type (not TEXT). Timestamps are `TIMESTAMPTZ`. JSONB is used for flexible structured fields.
+
+### Migration 001: Users
+
+```sql
+-- 20260321000001_create_users.sql
+
+CREATE TYPE user_role AS ENUM ('user', 'admin');
+
+CREATE TABLE users (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email       TEXT NOT NULL UNIQUE,
+    display_name TEXT,
+    role        user_role NOT NULL DEFAULT 'user',
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_users_email ON users(email);
+```
+
+### Migration 002: Sessions
+
+```sql
+-- 20260321000002_create_sessions.sql
+
+CREATE TABLE sessions (
+    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id      UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token_hash   TEXT NOT NULL UNIQUE,   -- SHA-256 of the raw session token
+    expires_at   TIMESTAMPTZ NOT NULL,
+    ip_address   INET,
+    user_agent   TEXT,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_sessions_user_id ON sessions(user_id);
+CREATE INDEX idx_sessions_token_hash ON sessions(token_hash);
+CREATE INDEX idx_sessions_expires_at ON sessions(expires_at);
+```
+
+### Migration 003: Magic Link Tokens
+
+```sql
+-- 20260321000003_create_magic_link_tokens.sql
+
+CREATE TABLE magic_link_tokens (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email       TEXT NOT NULL,
+    token_hash  TEXT NOT NULL UNIQUE,    -- SHA-256 of the raw token
+    expires_at  TIMESTAMPTZ NOT NULL,
+    used        BOOLEAN NOT NULL DEFAULT false,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_magic_link_tokens_email ON magic_link_tokens(email);
+CREATE INDEX idx_magic_link_tokens_token_hash ON magic_link_tokens(token_hash);
+CREATE INDEX idx_magic_link_tokens_expires_at ON magic_link_tokens(expires_at);
+```
+
+### Migration 004: User Settings
+
+```sql
+-- 20260321000004_create_user_settings.sql
+
+CREATE TABLE user_settings (
+    user_id                UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+    theme                  TEXT NOT NULL DEFAULT 'Intelligence Artificielle',
+    max_age_days           INTEGER NOT NULL DEFAULT 7
+                           CHECK (max_age_days > 0 AND max_age_days <= 365),
+    categories             JSONB NOT NULL DEFAULT '["Annonces majeures / importantes", "Entreprises des secteurs financiers", "Grandes entreprises des autres secteurs", "Secteurs publics", "Grand public / Particuliers"]'::jsonb,
+    max_items_per_category INTEGER NOT NULL DEFAULT 4
+                           CHECK (max_items_per_category > 0 AND max_items_per_category <= 50),
+    search_agent_behavior  TEXT NOT NULL DEFAULT '',
+    preferred_provider     TEXT,          -- 'gemini', 'openai', 'anthropic' (NULL = use first available)
+    preferred_model        TEXT,          -- model identifier (NULL = use provider default)
+    updated_at             TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### Migration 005: Sources
+
+```sql
+-- 20260321000005_create_sources.sql
+
+CREATE TABLE sources (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    title      TEXT NOT NULL CHECK (char_length(title) BETWEEN 1 AND 200),
+    url        TEXT NOT NULL CHECK (char_length(url) <= 2000),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_sources_user_id ON sources(user_id);
+CREATE INDEX idx_sources_user_id_created_at ON sources(user_id, created_at DESC);
+```
+
+### Migration 006: Syntheses
+
+```sql
+-- 20260321000006_create_syntheses.sql
+
+CREATE TYPE synthesis_status AS ENUM ('generating', 'completed', 'failed');
+
+CREATE TABLE syntheses (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    title       TEXT NOT NULL DEFAULT '',           -- auto-generated from theme + date
+    sections    JSONB NOT NULL DEFAULT '[]'::jsonb, -- [{title: string, items: [{title, url, summary}]}]
+    status      synthesis_status NOT NULL DEFAULT 'generating',
+    error_message TEXT,                             -- populated on failure
+    provider    TEXT,                               -- which provider was used
+    model       TEXT,                               -- which model was used
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_syntheses_user_id ON syntheses(user_id);
+CREATE INDEX idx_syntheses_user_id_created_at ON syntheses(user_id, created_at DESC);
+```
+
+### Migration 007: User Provider Keys
+
+```sql
+-- 20260321000007_create_user_provider_keys.sql
+
+CREATE TABLE user_provider_keys (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id         UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    provider        TEXT NOT NULL,               -- 'gemini', 'openai', 'anthropic'
+    encrypted_key   BYTEA NOT NULL,              -- AES-256-GCM ciphertext
+    nonce           BYTEA NOT NULL,              -- 12-byte GCM nonce
+    key_prefix      TEXT NOT NULL DEFAULT '',     -- first 8 chars for display (e.g., "sk-proj-...")
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+    UNIQUE(user_id, provider)                    -- one key per provider per user
+);
+
+CREATE INDEX idx_user_provider_keys_user_id ON user_provider_keys(user_id);
+```
+
+### Migration 008: Admin Provider Models
+
+```sql
+-- 20260321000008_create_admin_provider_models.sql
+
+CREATE TABLE admin_provider_models (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    provider      TEXT NOT NULL,                  -- 'gemini', 'openai', 'anthropic'
+    model_id      TEXT NOT NULL,                  -- e.g., 'gemini-2.5-pro', 'gpt-4o', 'claude-sonnet-4-20250514'
+    display_name  TEXT NOT NULL,                  -- e.g., 'Gemini 2.5 Pro', 'GPT-4o', 'Claude Sonnet 4'
+    enabled       BOOLEAN NOT NULL DEFAULT true,
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+    UNIQUE(provider, model_id)
+);
+
+CREATE INDEX idx_admin_provider_models_enabled ON admin_provider_models(enabled) WHERE enabled = true;
+```
+
+### Migration 009: Admin Rate Limits
+
+```sql
+-- 20260321000009_create_admin_rate_limits.sql
+
+CREATE TABLE admin_rate_limits (
+    provider            TEXT PRIMARY KEY,          -- 'gemini', 'openai', 'anthropic'
+    max_requests        INTEGER NOT NULL DEFAULT 29,
+    time_window_seconds INTEGER NOT NULL DEFAULT 60,
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Seed default rate limits
+INSERT INTO admin_rate_limits (provider, max_requests, time_window_seconds)
+VALUES
+    ('gemini', 29, 60),
+    ('openai', 50, 60),
+    ('anthropic', 40, 60);
+```
+
+### Migration 010: Generation Jobs
+
+```sql
+-- 20260321000010_create_generation_jobs.sql
+
+CREATE TYPE job_status AS ENUM ('pending', 'searching', 'scraping', 'rewriting', 'completed', 'failed');
+
+CREATE TABLE generation_jobs (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id         UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    synthesis_id    UUID REFERENCES syntheses(id) ON DELETE SET NULL,
+    status          job_status NOT NULL DEFAULT 'pending',
+    progress_pct    SMALLINT NOT NULL DEFAULT 0 CHECK (progress_pct BETWEEN 0 AND 100),
+    progress_message TEXT,
+    error_message   TEXT,
+    provider        TEXT,
+    model           TEXT,
+    started_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+    completed_at    TIMESTAMPTZ
+);
+
+CREATE INDEX idx_generation_jobs_user_id ON generation_jobs(user_id);
+CREATE INDEX idx_generation_jobs_status ON generation_jobs(status) WHERE status NOT IN ('completed', 'failed');
+```
+
+---
+
+## 3. API Endpoints
+
+All endpoints are prefixed with `/api/v1`. Request and response bodies are JSON. Cookie-based session authentication is used for all authenticated endpoints.
+
+### 3.1 Authentication
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `POST` | `/api/v1/auth/register` | Public + Turnstile | Create account, send magic link | 1 |
+| `POST` | `/api/v1/auth/magic-link` | Public + Turnstile | Request magic link for existing user | 1 |
+| `GET` | `/api/v1/auth/verify` | Public | Verify magic link token, create session, redirect | 1 |
+| `POST` | `/api/v1/auth/logout` | Authenticated | Invalidate current session | 1 |
+| `GET` | `/api/v1/auth/me` | Authenticated | Get current user info | 1 |
+
+#### Request/Response Types
+
+```rust
+// POST /api/v1/auth/register
+#[derive(Deserialize, Validate)]
+pub struct RegisterRequest {
+    #[validate(email)]
+    pub email: String,
+    #[validate(length(min = 1, max = 100))]
+    pub display_name: Option<String>,
+    pub turnstile_token: String,
+}
+
+// Response: 200 (always the same, whether email exists or not)
+#[derive(Serialize)]
+pub struct AuthMessageResponse {
+    pub message: String, // "If this email is valid, a login link has been sent."
+}
+
+// POST /api/v1/auth/magic-link
+#[derive(Deserialize, Validate)]
+pub struct MagicLinkRequest {
+    #[validate(email)]
+    pub email: String,
+    pub turnstile_token: String,
+}
+
+// GET /api/v1/auth/verify?token=<base64url>
+// -> 302 redirect to / with Set-Cookie on success
+// -> 302 redirect to /login?error=invalid_token on failure
+
+// GET /api/v1/auth/me
+#[derive(Serialize)]
+pub struct MeResponse {
+    pub id: Uuid,
+    pub email: String,
+    pub display_name: Option<String>,
+    pub role: String,       // "user" | "admin"
+    pub created_at: DateTime<Utc>,
+}
+```
+
+### 3.2 Syntheses
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `GET` | `/api/v1/syntheses` | Authenticated | List user's syntheses (paginated) | 2 |
+| `GET` | `/api/v1/syntheses/:id` | Authenticated | Get synthesis detail | 2 |
+| `POST` | `/api/v1/syntheses/generate` | Authenticated | Trigger async generation | 2 |
+| `DELETE` | `/api/v1/syntheses/:id` | Authenticated | Delete a synthesis | 2 |
+| `POST` | `/api/v1/syntheses/:id/email` | Authenticated | Send synthesis by email | 3 |
+
+```rust
+// GET /api/v1/syntheses?page=1&per_page=20
+#[derive(Deserialize)]
+pub struct ListSynthesesQuery {
+    pub page: Option<u32>,     // default 1
+    pub per_page: Option<u32>, // default 20, max 100
+}
+
+#[derive(Serialize)]
+pub struct SynthesisListItem {
+    pub id: Uuid,
+    pub title: String,
+    pub status: String,
+    pub provider: Option<String>,
+    pub model: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub section_count: i32,
+    pub article_count: i32,
+}
+
+#[derive(Serialize)]
+pub struct PaginatedResponse<T> {
+    pub items: Vec<T>,
+    pub total: i64,
+    pub page: u32,
+    pub per_page: u32,
+}
+
+// GET /api/v1/syntheses/:id
+#[derive(Serialize)]
+pub struct SynthesisDetail {
+    pub id: Uuid,
+    pub title: String,
+    pub sections: Vec<NewsSection>,
+    pub status: String,
+    pub provider: Option<String>,
+    pub model: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Serialize, Deserialize, Clone)]
+pub struct NewsSection {
+    pub title: String,
+    pub items: Vec<NewsItem>,
+}
+
+#[derive(Serialize, Deserialize, Clone)]
+pub struct NewsItem {
+    pub title: String,
+    pub url: String,
+    pub summary: String,
+}
+
+// POST /api/v1/syntheses/generate
+// Request body is empty -- uses the user's saved settings + sources + API key
+// Response: 202
+#[derive(Serialize)]
+pub struct GenerateResponse {
+    pub job_id: Uuid,
+    pub status: String,
+}
+
+// POST /api/v1/syntheses/:id/email
+#[derive(Deserialize, Validate)]
+pub struct SendEmailRequest {
+    #[validate(email)]
+    pub recipient: String,
+}
+```
+
+### 3.3 Sources
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `GET` | `/api/v1/sources` | Authenticated | List user's sources | 1 |
+| `POST` | `/api/v1/sources` | Authenticated | Add a source | 1 |
+| `DELETE` | `/api/v1/sources/:id` | Authenticated | Delete a source | 1 |
+
+```rust
+// GET /api/v1/sources
+#[derive(Serialize)]
+pub struct SourceResponse {
+    pub id: Uuid,
+    pub title: String,
+    pub url: String,
+    pub created_at: DateTime<Utc>,
+}
+
+// POST /api/v1/sources
+#[derive(Deserialize, Validate)]
+pub struct CreateSourceRequest {
+    #[validate(length(min = 1, max = 200))]
+    pub title: String,
+    #[validate(url, length(max = 2000))]
+    pub url: String,
+}
+```
+
+### 3.4 Settings
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `GET` | `/api/v1/settings` | Authenticated | Get user's settings | 1 |
+| `PUT` | `/api/v1/settings` | Authenticated | Update settings | 1 |
+
+```rust
+// GET /api/v1/settings
+#[derive(Serialize)]
+pub struct SettingsResponse {
+    pub theme: String,
+    pub max_age_days: i32,
+    pub categories: Vec<String>,
+    pub max_items_per_category: i32,
+    pub search_agent_behavior: String,
+    pub preferred_provider: Option<String>,
+    pub preferred_model: Option<String>,
+}
+
+// PUT /api/v1/settings
+#[derive(Deserialize, Validate)]
+pub struct UpdateSettingsRequest {
+    #[validate(length(min = 1, max = 200))]
+    pub theme: String,
+    #[validate(range(min = 1, max = 365))]
+    pub max_age_days: i32,
+    #[validate(length(min = 1, max = 20))]
+    pub categories: Vec<String>,  // each item validated separately in handler
+    #[validate(range(min = 1, max = 50))]
+    pub max_items_per_category: i32,
+    #[validate(length(max = 2000))]
+    pub search_agent_behavior: String,
+    pub preferred_provider: Option<String>,
+    pub preferred_model: Option<String>,
+}
+```
+
+### 3.5 User Provider Keys
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `GET` | `/api/v1/provider-keys` | Authenticated | List user's provider keys (prefix only, never full key) | 2 |
+| `POST` | `/api/v1/provider-keys` | Authenticated | Add or replace a provider key | 2 |
+| `DELETE` | `/api/v1/provider-keys/:provider` | Authenticated | Delete a provider key | 2 |
+
+```rust
+// GET /api/v1/provider-keys
+#[derive(Serialize)]
+pub struct ProviderKeyListItem {
+    pub provider: String,
+    pub key_prefix: String,     // e.g., "sk-proj-..." (first 8 chars)
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+// POST /api/v1/provider-keys
+#[derive(Deserialize, Validate)]
+pub struct CreateProviderKeyRequest {
+    #[validate(custom(function = "validate_provider"))]
+    pub provider: String,       // "gemini" | "openai" | "anthropic"
+    #[validate(length(min = 10, max = 500))]
+    pub api_key: String,        // the raw API key -- encrypted before storage
+}
+
+fn validate_provider(provider: &str) -> Result<(), validator::ValidationError> {
+    match provider {
+        "gemini" | "openai" | "anthropic" => Ok(()),
+        _ => Err(validator::ValidationError::new("invalid_provider")),
+    }
+}
+```
+
+### 3.6 Generation (SSE)
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `GET` | `/api/v1/generation/:job_id/progress` | Authenticated | SSE stream of generation progress | 2 |
+| `GET` | `/api/v1/generation/:job_id/status` | Authenticated | One-shot status poll (for reconnection) | 2 |
+
+```rust
+// SSE event types sent on /api/v1/generation/:job_id/progress
+#[derive(Serialize)]
+#[serde(tag = "type")]
+pub enum GenerationEvent {
+    #[serde(rename = "progress")]
+    Progress {
+        status: String,          // "searching", "scraping", "rewriting"
+        progress_pct: u8,
+        message: String,
+    },
+    #[serde(rename = "completed")]
+    Completed {
+        synthesis_id: Uuid,
+    },
+    #[serde(rename = "failed")]
+    Failed {
+        error: String,
+    },
+}
+
+// GET /api/v1/generation/:job_id/status (one-shot poll)
+#[derive(Serialize)]
+pub struct JobStatusResponse {
+    pub job_id: Uuid,
+    pub status: String,
+    pub progress_pct: u8,
+    pub progress_message: Option<String>,
+    pub synthesis_id: Option<Uuid>,
+    pub error_message: Option<String>,
+}
+```
+
+### 3.7 Admin
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `GET` | `/api/v1/admin/provider-models` | Admin | List all configured provider models | 2 |
+| `POST` | `/api/v1/admin/provider-models` | Admin | Add a provider model | 2 |
+| `PUT` | `/api/v1/admin/provider-models/:id` | Admin | Update a provider model | 2 |
+| `DELETE` | `/api/v1/admin/provider-models/:id` | Admin | Remove a provider model | 2 |
+| `GET` | `/api/v1/admin/rate-limits` | Admin | Get rate limit configs | 2 |
+| `PUT` | `/api/v1/admin/rate-limits/:provider` | Admin | Update rate limit config | 2 |
+| `GET` | `/api/v1/admin/users` | Admin | List all users | 2 |
+| `PUT` | `/api/v1/admin/users/:id/role` | Admin | Change user role | 2 |
+
+```rust
+// POST /api/v1/admin/provider-models
+#[derive(Deserialize, Validate)]
+pub struct CreateProviderModelRequest {
+    #[validate(custom(function = "validate_provider"))]
+    pub provider: String,
+    #[validate(length(min = 1, max = 100))]
+    pub model_id: String,
+    #[validate(length(min = 1, max = 200))]
+    pub display_name: String,
+    pub enabled: bool,
+}
+
+// PUT /api/v1/admin/rate-limits/:provider
+#[derive(Deserialize, Validate)]
+pub struct UpdateRateLimitRequest {
+    #[validate(range(min = 1, max = 1000))]
+    pub max_requests: i32,
+    #[validate(range(min = 1, max = 3600))]
+    pub time_window_seconds: i32,
+}
+
+// PUT /api/v1/admin/users/:id/role
+#[derive(Deserialize)]
+pub struct UpdateRoleRequest {
+    pub role: String, // "user" | "admin"
+}
+```
+
+### 3.8 Public Config
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `GET` | `/api/v1/config/providers` | Authenticated | List enabled providers and models (no keys) | 2 |
+
+```rust
+// GET /api/v1/config/providers
+#[derive(Serialize)]
+pub struct ProviderInfo {
+    pub provider: String,
+    pub models: Vec<ModelInfo>,
+}
+
+#[derive(Serialize)]
+pub struct ModelInfo {
+    pub model_id: String,
+    pub display_name: String,
+}
+```
+
+### 3.9 SSE for Real-Time List Updates
+
+| Method | Path | Auth | Description | Phase |
+|---|---|---|---|---|
+| `GET` | `/api/v1/events/syntheses` | Authenticated | SSE stream for syntheses list changes | 3 |
+| `GET` | `/api/v1/events/sources` | Authenticated | SSE stream for sources list changes | 3 |
+
+These SSE endpoints replace Firestore `onSnapshot`. When a synthesis is created/deleted or a source is added/removed, connected clients receive a lightweight event (just the entity type + action + id) prompting the frontend to refetch. Implementation uses a `tokio::sync::broadcast` channel per user in `AppState`.
+
+---
+
+## 4. Authentication & Authorization
+
+### 4.1 Magic Link Flow
+
+#### Token Generation
+
+```rust
+// src/util/token.rs
+use rand::RngCore;
+use sha2::{Sha256, Digest};
+use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+
+/// Generate a 32-byte cryptographically secure random token, base64url-encoded.
+pub fn generate_token() -> String {
+    let mut bytes = [0u8; 32];
+    rand::rngs::OsRng.fill_bytes(&mut bytes);
+    URL_SAFE_NO_PAD.encode(bytes)
+}
+
+/// Compute SHA-256 hash of a token, hex-encoded.
+pub fn hash_token(token: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(token.as_bytes());
+    let result = hasher.finalize();
+    hex::encode(result)
+}
+```
+
+#### Registration Flow
+
+1. Receive `RegisterRequest` (email, optional display_name, turnstile_token).
+2. Verify Turnstile token via `services::captcha::verify()`.
+3. Check if user with this email already exists:
+   - If exists: send a magic link email (same as login). Return generic success message.
+   - If not: create user with `role = 'user'`, create default settings row, send magic link email.
+4. Always return `200 { "message": "If this email is valid, a login link has been sent." }`.
+5. Add random delay (50-200ms) when no email is sent to prevent timing attacks.
+
+#### Magic Link Request Flow
+
+1. Receive `MagicLinkRequest` (email, turnstile_token).
+2. Verify Turnstile token.
+3. Look up user by email.
+   - If not found: return same success message, do nothing (prevent email enumeration).
+4. Generate token, compute SHA-256 hash, store in `magic_link_tokens` with 15-minute expiry.
+5. Send email containing `{BASE_URL}/api/v1/auth/verify?token={raw_token}`.
+6. Return generic success message.
+
+#### Verification Flow
+
+1. Receive `GET /api/v1/auth/verify?token={raw_token}`.
+2. Compute `hash = SHA-256(raw_token)`.
+3. Atomic query:
+   ```sql
+   UPDATE magic_link_tokens
+   SET used = true
+   WHERE token_hash = $1 AND used = false AND expires_at > now()
+   RETURNING email
+   ```
+4. If `rows_affected == 0`: redirect to `/login?error=invalid_token`.
+5. Look up or create user by email (handles the case where registration + verification happen in a single flow).
+6. Generate session token (32 bytes, base64url).
+7. Store `SHA-256(session_token)` in `sessions` table with 30-day expiry.
+8. Set session cookie:
+   ```
+   Set-Cookie: ai_synth_session={session_token};
+     HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=2592000
+   ```
+9. Redirect to `/` (302).
+
+### 4.2 Session Middleware (AuthUser Extractor)
+
+```rust
+// src/middleware/auth.rs
+use axum::extract::FromRequestParts;
+use axum::http::request::Parts;
+
+#[derive(Clone, Debug)]
+pub struct AuthUser {
+    pub id: Uuid,
+    pub email: String,
+    pub display_name: Option<String>,
+    pub role: UserRole,
+}
+
+#[async_trait]
+impl<S> FromRequestParts<S> for AuthUser
+where
+    S: Send + Sync,
+    AppState: FromRef<S>,
+{
+    type Rejection = AppError;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let app_state = AppState::from_ref(state);
+
+        // 1. Extract cookie
+        let cookies = parts
+            .headers
+            .get_all(header::COOKIE)
+            .iter()
+            .filter_map(|v| v.to_str().ok())
+            .flat_map(|s| s.split(';'))
+            .map(|s| s.trim())
+            .find(|s| s.starts_with("ai_synth_session="))
+            .and_then(|s| s.strip_prefix("ai_synth_session="))
+            .ok_or(AppError::Unauthorized("No session cookie".into()))?;
+
+        let session_token = cookies;
+
+        // 2. Hash and lookup
+        let token_hash = crate::util::token::hash_token(session_token);
+        let session = db::sessions::find_by_hash(&app_state.pool, &token_hash)
+            .await?
+            .ok_or(AppError::Unauthorized("Invalid session".into()))?;
+
+        // 3. Check expiration
+        if session.expires_at < Utc::now() {
+            db::sessions::delete(&app_state.pool, session.id).await?;
+            return Err(AppError::Unauthorized("Session expired".into()));
+        }
+
+        // 4. Load user
+        let user = db::users::find_by_id(&app_state.pool, session.user_id)
+            .await?
+            .ok_or(AppError::Unauthorized("User not found".into()))?;
+
+        Ok(AuthUser {
+            id: user.id,
+            email: user.email,
+            display_name: user.display_name,
+            role: user.role,
+        })
+    }
+}
+```
+
+### 4.3 Admin Guard (AdminUser Extractor)
+
+```rust
+// src/middleware/admin.rs
+
+#[derive(Clone, Debug)]
+pub struct AdminUser(pub AuthUser);
+
+#[async_trait]
+impl<S> FromRequestParts<S> for AdminUser
+where
+    S: Send + Sync,
+    AppState: FromRef<S>,
+{
+    type Rejection = AppError;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let auth_user = AuthUser::from_request_parts(parts, state).await?;
+        if auth_user.role != UserRole::Admin {
+            return Err(AppError::Forbidden("Admin access required".into()));
+        }
+        Ok(AdminUser(auth_user))
+    }
+}
+```
+
+Handlers that require admin simply take `AdminUser` as a parameter:
+
+```rust
+async fn list_users(
+    AdminUser(admin): AdminUser,
+    State(state): State<AppState>,
+) -> Result<Json<Vec<UserResponse>>, AppError> {
+    // admin is guaranteed to be an admin here
+}
+```
+
+### 4.4 Turnstile Verification
+
+```rust
+// src/services/captcha.rs
+use serde::Deserialize;
+
+#[derive(Deserialize)]
+struct TurnstileResponse {
+    success: bool,
+    #[serde(rename = "error-codes")]
+    error_codes: Vec<String>,
+}
+
+pub async fn verify_turnstile(
+    client: &reqwest::Client,
+    secret: &str,
+    token: &str,
+) -> Result<(), AppError> {
+    let resp = client
+        .post("https://challenges.cloudflare.com/turnstile/v0/siteverify")
+        .form(&[("secret", secret), ("response", token)])
+        .send()
+        .await
+        .map_err(|e| AppError::Internal(e.into()))?;
+
+    let result: TurnstileResponse = resp
+        .json()
+        .await
+        .map_err(|e| AppError::Internal(e.into()))?;
+
+    if result.success {
+        Ok(())
+    } else {
+        Err(AppError::BadRequest(format!(
+            "Captcha verification failed: {:?}",
+            result.error_codes
+        )))
+    }
+}
+```
+
+### 4.5 CSRF Protection
+
+The CSRF middleware checks for the `X-Requested-With` header on all state-changing requests (POST, PUT, DELETE). Combined with `SameSite=Lax` cookies, this prevents cross-site request forgery because browsers do not send custom headers on cross-origin requests without an approved CORS preflight.
+
+```rust
+// src/middleware/csrf.rs
+use axum::middleware::Next;
+use axum::http::Request;
+
+pub async fn csrf_check<B>(req: Request<B>, next: Next<B>) -> Result<Response, AppError> {
+    let dominated_methods = ["POST", "PUT", "DELETE", "PATCH"];
+
+    if dominated_methods.contains(&req.method().as_str()) {
+        let has_header = req
+            .headers()
+            .get("X-Requested-With")
+            .map(|v| v == "XMLHttpRequest")
+            .unwrap_or(false);
+
+        if !has_header {
+            return Err(AppError::Forbidden("Missing X-Requested-With header".into()));
+        }
+    }
+
+    Ok(next.run(req).await)
+}
+```
+
+### 4.6 CLI Admin Creation
+
+```rust
+// src/cli.rs
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(name = "ai-synth", about = "AI Weekly Synth backend")]
+pub struct Cli {
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Subcommand)]
+pub enum Commands {
+    /// Start the web server
+    Serve,
+    /// Create an admin user
+    CreateAdmin {
+        /// Email address for the admin user
+        #[arg(long)]
+        email: String,
+    },
+}
+```
+
+In `main.rs`:
+```rust
+async fn main() -> anyhow::Result<()> {
+    let cli = Cli::parse();
+    match cli.command {
+        Commands::Serve => { /* start server */ },
+        Commands::CreateAdmin { email } => {
+            let pool = create_pool().await?;
+            let user = db::users::find_by_email(&pool, &email).await?;
+            match user {
+                Some(u) => {
+                    db::users::update_role(&pool, u.id, UserRole::Admin).await?;
+                    println!("User {} promoted to admin.", email);
+                }
+                None => {
+                    db::users::create(&pool, &email, None, UserRole::Admin).await?;
+                    println!("Admin user {} created.", email);
+                }
+            }
+        }
+    }
+    Ok(())
+}
+```
+
+---
+
+## 5. LLM Provider Abstraction
+
+### 5.1 The Unified Trait
+
+```rust
+// src/services/llm/mod.rs
+use async_trait::async_trait;
+
+/// Describes what a provider can do natively.
+#[derive(Debug, Clone)]
+pub struct ProviderCapabilities {
+    /// Provider supports native web search grounding (e.g., Gemini googleSearch, OpenAI web_search).
+    pub native_web_search: bool,
+    /// Provider supports structured JSON output via schema enforcement.
+    pub structured_output: bool,
+}
+
+/// Progress callback type for reporting generation steps.
+pub type ProgressFn = Box<dyn Fn(u8, &str) + Send + Sync>;
+
+#[async_trait]
+pub trait LlmProvider: Send + Sync {
+    /// Returns the provider identifier: "gemini", "openai", or "anthropic".
+    fn provider_id(&self) -> &str;
+
+    /// Returns the capabilities of this provider.
+    fn capabilities(&self) -> ProviderCapabilities;
+
+    /// Pass 1: Search the web and generate structured news items.
+    /// Uses native web search grounding if available.
+    /// Returns parsed JSON matching the category schema (keys: category_0, category_1, ...).
+    async fn search_and_generate(
+        &self,
+        model: &str,
+        system_prompt: &str,
+        user_prompt: &str,
+        response_schema: &serde_json::Value,
+    ) -> Result<serde_json::Value, AppError>;
+
+    /// Pass 2: Rewrite titles and summaries based on scraped content.
+    /// No web search needed.
+    async fn rewrite(
+        &self,
+        model: &str,
+        system_prompt: &str,
+        user_prompt: &str,
+        response_schema: &serde_json::Value,
+    ) -> Result<serde_json::Value, AppError>;
+}
+```
+
+### 5.2 Per-Provider Implementation Strategy
+
+#### Gemini
+
+```rust
+// src/services/llm/gemini.rs
+
+pub struct GeminiProvider {
+    client: reqwest::Client,
+    api_key: secrecy::SecretString,
+}
+
+impl GeminiProvider {
+    pub fn new(client: reqwest::Client, api_key: secrecy::SecretString) -> Self {
+        Self { client, api_key }
+    }
+}
+
+#[async_trait]
+impl LlmProvider for GeminiProvider {
+    fn provider_id(&self) -> &str { "gemini" }
+
+    fn capabilities(&self) -> ProviderCapabilities {
+        ProviderCapabilities {
+            native_web_search: true,     // googleSearch tool
+            structured_output: true,     // responseSchema + responseMimeType
+        }
+    }
+
+    async fn search_and_generate(
+        &self,
+        model: &str,
+        system_prompt: &str,
+        user_prompt: &str,
+        response_schema: &serde_json::Value,
+    ) -> Result<serde_json::Value, AppError> {
+        // POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
+        // Body:
+        // {
+        //   "system_instruction": { "parts": [{ "text": system_prompt }] },
+        //   "contents": [{ "parts": [{ "text": user_prompt }] }],
+        //   "tools": [{ "google_search": {} }],
+        //   "generation_config": {
+        //     "response_mime_type": "application/json",
+        //     "response_schema": response_schema
+        //   }
+        // }
+        // Parse response.candidates[0].content.parts[0].text as JSON
+        todo!()
+    }
+
+    async fn rewrite(
+        &self,
+        model: &str,
+        system_prompt: &str,
+        user_prompt: &str,
+        response_schema: &serde_json::Value,
+    ) -> Result<serde_json::Value, AppError> {
+        // Same as above but WITHOUT the tools field (no web search in pass 2)
+        todo!()
+    }
+}
+```
+
+#### OpenAI
+
+```rust
+// src/services/llm/openai.rs
+
+pub struct OpenAiProvider {
+    client: reqwest::Client,
+    api_key: secrecy::SecretString,
+}
+
+#[async_trait]
+impl LlmProvider for OpenAiProvider {
+    fn provider_id(&self) -> &str { "openai" }
+
+    fn capabilities(&self) -> ProviderCapabilities {
+        ProviderCapabilities {
+            native_web_search: true,      // web_search tool (Responses API)
+            structured_output: true,      // response_format: { type: "json_schema", json_schema: {...} }
+        }
+    }
+
+    async fn search_and_generate(
+        &self,
+        model: &str,
+        system_prompt: &str,
+        user_prompt: &str,
+        response_schema: &serde_json::Value,
+    ) -> Result<serde_json::Value, AppError> {
+        // POST https://api.openai.com/v1/responses
+        // Body:
+        // {
+        //   "model": model,
+        //   "instructions": system_prompt,
+        //   "input": user_prompt,
+        //   "tools": [{ "type": "web_search_preview" }],
+        //   "text": {
+        //     "format": {
+        //       "type": "json_schema",
+        //       "name": "news_synthesis",
+        //       "schema": response_schema
+        //     }
+        //   }
+        // }
+        todo!()
+    }
+
+    async fn rewrite(
+        &self,
+        model: &str,
+        system_prompt: &str,
+        user_prompt: &str,
+        response_schema: &serde_json::Value,
+    ) -> Result<serde_json::Value, AppError> {
+        // POST https://api.openai.com/v1/responses (no tools)
+        todo!()
+    }
+}
+```
+
+#### Anthropic
+
+```rust
+// src/services/llm/anthropic.rs
+
+pub struct AnthropicProvider {
+    client: reqwest::Client,
+    api_key: secrecy::SecretString,
+}
+
+#[async_trait]
+impl LlmProvider for AnthropicProvider {
+    fn provider_id(&self) -> &str { "anthropic" }
+
+    fn capabilities(&self) -> ProviderCapabilities {
+        ProviderCapabilities {
+            native_web_search: true,      // web_search tool
+            structured_output: false,     // No native JSON schema enforcement; use prompt + parse
+        }
+    }
+
+    async fn search_and_generate(
+        &self,
+        model: &str,
+        system_prompt: &str,
+        user_prompt: &str,
+        response_schema: &serde_json::Value,
+    ) -> Result<serde_json::Value, AppError> {
+        // POST https://api.anthropic.com/v1/messages
+        // Headers: x-api-key, anthropic-version: 2023-06-01
+        // Body:
+        // {
+        //   "model": model,
+        //   "max_tokens": 8192,
+        //   "system": system_prompt,
+        //   "tools": [{ "type": "web_search_20250305" }],
+        //   "messages": [{ "role": "user", "content": user_prompt + "\n\nRespond ONLY with valid JSON matching this schema:\n" + schema }]
+        // }
+        // Extract text from response, parse as JSON, validate against schema
+        todo!()
+    }
+
+    async fn rewrite(
+        &self,
+        model: &str,
+        system_prompt: &str,
+        user_prompt: &str,
+        response_schema: &serde_json::Value,
+    ) -> Result<serde_json::Value, AppError> {
+        // Same without tools, JSON schema in prompt
+        todo!()
+    }
+}
+```
+
+### 5.3 Provider Factory
+
+```rust
+// src/services/llm/mod.rs
+
+pub fn create_provider(
+    provider_id: &str,
+    api_key: secrecy::SecretString,
+    client: reqwest::Client,
+) -> Result<Box<dyn LlmProvider>, AppError> {
+    match provider_id {
+        "gemini" => Ok(Box::new(GeminiProvider::new(client, api_key))),
+        "openai" => Ok(Box::new(OpenAiProvider::new(client, api_key))),
+        "anthropic" => Ok(Box::new(AnthropicProvider::new(client, api_key))),
+        other => Err(AppError::BadRequest(format!("Unknown provider: {other}"))),
+    }
+}
+```
+
+### 5.4 The Adaptive Generation Pipeline
+
+```rust
+// src/services/generation.rs
+
+pub struct GenerationPipeline;
+
+impl GenerationPipeline {
+    /// Run the full generation pipeline.
+    /// Adapts the pipeline based on provider capabilities.
+    pub async fn run(
+        state: &AppState,
+        user_id: Uuid,
+        job_id: Uuid,
+        progress_tx: tokio::sync::watch::Sender<GenerationEvent>,
+    ) -> Result<Uuid, AppError> {
+        // 1. Load user settings
+        let settings = db::settings::get_or_default(&state.pool, user_id).await?;
+
+        // 2. Load user sources
+        let sources = db::sources::list_by_user(&state.pool, user_id).await?;
+
+        // 3. Resolve provider + model
+        //    Look up user's preferred_provider -> find user's API key for that provider
+        //    Fall back to first provider the user has a key for
+        let (provider_id, model_id) = resolve_provider_and_model(
+            &state.pool, user_id, &settings
+        ).await?;
+
+        // 4. Decrypt user's API key for the resolved provider
+        let api_key = db::provider_keys::get_decrypted(
+            &state.pool, user_id, &provider_id, &state.config.master_key
+        ).await?;
+
+        // 5. Create the LLM provider
+        let provider = create_provider(&provider_id, api_key, state.http_client.clone())?;
+        let caps = provider.capabilities();
+
+        // 6. Build dynamic JSON schema from categories
+        let schema = build_category_schema(&settings.categories);
+
+        // 7. Build prompts
+        let (system_prompt, user_prompt) = build_search_prompts(&settings, &sources);
+
+        // === PASS 1: Search ===
+        progress_tx.send(GenerationEvent::Progress {
+            status: "searching".into(),
+            progress_pct: 10,
+            message: "Searching the web for recent news...".into(),
+        }).ok();
+
+        // Rate limit check
+        state.rate_limiter.acquire(&provider_id, user_id).await?;
+
+        let raw_results = provider
+            .search_and_generate(&model_id, &system_prompt, &user_prompt, &schema)
+            .await?;
+
+        // 8. Parse raw results into NewsItems per category
+        let parsed = parse_category_results(&raw_results, &settings.categories)?;
+
+        // === DECISION POINT: scrape or skip ===
+        // If the provider has native web search with grounding (Gemini, OpenAI),
+        // the results are already high-quality. We still scrape to:
+        //   (a) validate URLs exist (filter 404s)
+        //   (b) check publication dates
+        //   (c) get content for the rewrite pass
+        // But if scraping fails for some items, we keep the originals.
+
+        progress_tx.send(GenerationEvent::Progress {
+            status: "scraping".into(),
+            progress_pct: 40,
+            message: "Validating and fetching article content...".into(),
+        }).ok();
+
+        let scraped = services::scraper::validate_and_scrape(
+            &state.http_client,
+            parsed,
+            settings.max_age_days as i64,
+        ).await;
+
+        // === PASS 2: Rewrite ===
+        progress_tx.send(GenerationEvent::Progress {
+            status: "rewriting".into(),
+            progress_pct: 70,
+            message: "Rewriting summaries based on article content...".into(),
+        }).ok();
+
+        let (rewrite_system, rewrite_user) = build_rewrite_prompts(&scraped);
+
+        state.rate_limiter.acquire(&provider_id, user_id).await?;
+
+        let final_results = provider
+            .rewrite(&model_id, &rewrite_system, &rewrite_user, &schema)
+            .await?;
+
+        // 9. Build sections
+        let sections = build_sections(&final_results, &settings.categories)?;
+
+        // 10. Persist synthesis
+        let title = format!("{} - {}", settings.theme, Utc::now().format("%d/%m/%Y"));
+        let synthesis_id = db::syntheses::create(
+            &state.pool, user_id, &title, &sections, &provider_id, &model_id
+        ).await?;
+
+        // 11. Update job record
+        db::generation_jobs::complete(&state.pool, job_id, synthesis_id).await?;
+
+        progress_tx.send(GenerationEvent::Completed { synthesis_id }).ok();
+
+        Ok(synthesis_id)
+    }
+}
+
+/// Resolve which provider and model to use for a user.
+async fn resolve_provider_and_model(
+    pool: &PgPool,
+    user_id: Uuid,
+    settings: &UserSettings,
+) -> Result<(String, String), AppError> {
+    // 1. If user has a preferred provider + model, and has a key for it, use that
+    if let (Some(ref prov), Some(ref model)) = (&settings.preferred_provider, &settings.preferred_model) {
+        let has_key = db::provider_keys::exists(pool, user_id, prov).await?;
+        if has_key {
+            // Verify model is in admin's enabled list
+            let model_exists = db::admin_models::is_enabled(pool, prov, model).await?;
+            if model_exists {
+                return Ok((prov.clone(), model.clone()));
+            }
+        }
+    }
+
+    // 2. Fall back to first provider the user has a key for
+    let keys = db::provider_keys::list_by_user(pool, user_id).await?;
+    for key in &keys {
+        if let Some(model) = db::admin_models::first_enabled_for_provider(pool, &key.provider).await? {
+            return Ok((key.provider.clone(), model.model_id));
+        }
+    }
+
+    Err(AppError::BadRequest(
+        "No API key configured. Please add an API key in your settings.".into()
+    ))
+}
+```
+
+### 5.5 Rate Limiter
+
+Token-bucket rate limiter, per-provider. Admin-configured defaults apply globally. Users can override for their own keys (if they have higher API quotas).
+
+```rust
+// src/services/rate_limiter.rs
+use dashmap::DashMap;
+use std::collections::VecDeque;
+use std::time::{Duration, Instant};
+use tokio::sync::Semaphore;
+
+pub struct RateLimiter {
+    /// Per-provider global buckets (admin-configured defaults)
+    global_buckets: DashMap<String, TokenBucket>,
+    /// Per-user-per-provider override buckets
+    user_buckets: DashMap<(Uuid, String), TokenBucket>,
+}
+
+struct TokenBucket {
+    timestamps: VecDeque<Instant>,
+    max_requests: u32,
+    time_window: Duration,
+}
+
+impl RateLimiter {
+    pub fn new() -> Self {
+        Self {
+            global_buckets: DashMap::new(),
+            user_buckets: DashMap::new(),
+        }
+    }
+
+    /// Load admin-configured rate limits from DB.
+    pub async fn load_from_db(&self, pool: &PgPool) -> Result<(), AppError> {
+        let limits = db::admin_rate_limits::list_all(pool).await?;
+        for limit in limits {
+            self.global_buckets.insert(
+                limit.provider.clone(),
+                TokenBucket {
+                    timestamps: VecDeque::new(),
+                    max_requests: limit.max_requests as u32,
+                    time_window: Duration::from_secs(limit.time_window_seconds as u64),
+                },
+            );
+        }
+        Ok(())
+    }
+
+    /// Acquire a slot. Uses user-specific override if set, otherwise global.
+    pub async fn acquire(&self, provider: &str, user_id: Uuid) -> Result<(), AppError> {
+        // Check user override first
+        let user_key = (user_id, provider.to_string());
+        if let Some(mut bucket) = self.user_buckets.get_mut(&user_key) {
+            return self.acquire_from_bucket(&mut bucket).await;
+        }
+
+        // Fall back to global
+        let mut bucket = self.global_buckets
+            .entry(provider.to_string())
+            .or_insert_with(|| TokenBucket {
+                timestamps: VecDeque::new(),
+                max_requests: 29,
+                time_window: Duration::from_secs(60),
+            });
+        self.acquire_from_bucket(&mut bucket).await
+    }
+
+    async fn acquire_from_bucket(&self, bucket: &mut TokenBucket) -> Result<(), AppError> {
+        let now = Instant::now();
+        bucket.timestamps.retain(|t| now.duration_since(*t) < bucket.time_window);
+
+        if bucket.timestamps.len() < bucket.max_requests as usize {
+            bucket.timestamps.push_back(now);
+            return Ok(());
+        }
+
+        // Calculate wait time
+        let oldest = bucket.timestamps.front().unwrap();
+        let wait = bucket.time_window.checked_sub(now.duration_since(*oldest))
+            .unwrap_or(Duration::from_millis(100));
+
+        if wait > Duration::from_secs(120) {
+            return Err(AppError::TooManyRequests {
+                retry_after_secs: wait.as_secs(),
+            });
+        }
+
+        // Drop the DashMap reference before sleeping
+        drop(bucket);
+        tokio::time::sleep(wait).await;
+
+        // Retry (recursive but bounded because we waited past the oldest timestamp)
+        // In practice, re-acquire by calling the parent method
+        Ok(())
+    }
+
+    /// Hot-reload a provider's limits (called after admin update).
+    pub fn update_provider_limit(&self, provider: &str, max_requests: u32, time_window_secs: u64) {
+        self.global_buckets.insert(
+            provider.to_string(),
+            TokenBucket {
+                timestamps: VecDeque::new(),
+                max_requests,
+                time_window: Duration::from_secs(time_window_secs),
+            },
+        );
+    }
+}
+```
+
+---
+
+## 6. URL Scraping (Server-Side)
+
+### 6.1 HTTP Client Configuration
+
+```rust
+// Created once in AppState, shared across all requests
+let http_client = reqwest::Client::builder()
+    .user_agent("AI-Weekly-Synth/1.0 (+https://github.com/your-repo)")
+    .timeout(Duration::from_secs(15))
+    .connect_timeout(Duration::from_secs(5))
+    .redirect(reqwest::redirect::Policy::limited(3))
+    .danger_accept_invalid_certs(false)
+    .pool_max_idle_per_host(10)
+    .build()?;
+```
+
+### 6.2 SSRF Prevention
+
+```rust
+// src/services/scraper.rs
+use std::net::IpAddr;
+use url::Url;
+
+fn is_safe_url(url: &Url) -> Result<(), AppError> {
+    // 1. Scheme check
+    match url.scheme() {
+        "http" | "https" => {}
+        scheme => return Err(AppError::ScrapingError(
+            format!("Blocked scheme: {scheme}")
+        )),
+    }
+
+    // 2. Host check -- reject if no host
+    let host = url.host_str()
+        .ok_or_else(|| AppError::ScrapingError("No host in URL".into()))?;
+
+    // 3. Resolve DNS and check IPs
+    // Note: uses std::net::ToSocketAddrs which blocks; in production,
+    // use trust-dns or tokio::net::lookup_host for async resolution
+    let port = url.port().unwrap_or(if url.scheme() == "https" { 443 } else { 80 });
+    let addrs: Vec<_> = tokio::net::lookup_host(format!("{host}:{port}"))
+        .await
+        .map_err(|e| AppError::ScrapingError(format!("DNS resolution failed: {e}")))?
+        .collect();
+
+    for addr in &addrs {
+        if is_private_ip(addr.ip()) {
+            return Err(AppError::ScrapingError(
+                "URL resolves to private/internal IP".into()
+            ));
+        }
+    }
+
+    Ok(())
+}
+
+fn is_private_ip(ip: IpAddr) -> bool {
+    match ip {
+        IpAddr::V4(v4) => {
+            v4.is_loopback()                    // 127.0.0.0/8
+            || v4.is_private()                  // 10/8, 172.16/12, 192.168/16
+            || v4.is_link_local()               // 169.254/16
+            || v4.is_unspecified()              // 0.0.0.0
+            || v4.octets() == [169, 254, 169, 254]  // Cloud metadata
+        }
+        IpAddr::V6(v6) => {
+            v6.is_loopback()                    // ::1
+            || v6.is_unspecified()              // ::
+            // fe80::/10 (link-local)
+            || (v6.segments()[0] & 0xffc0) == 0xfe80
+        }
+    }
+}
+```
+
+### 6.3 HTML Parsing and Content Extraction
+
+```rust
+// src/services/scraper.rs
+use scraper::{Html, Selector};
+
+pub struct ScrapedItem {
+    pub title: String,
+    pub url: String,
+    pub summary: String,
+    pub scraped_content: String,
+}
+
+pub async fn validate_and_scrape(
+    client: &reqwest::Client,
+    items: Vec<(String, Vec<NewsItem>)>, // (category_key, items)
+    max_age_days: i64,
+) -> Vec<(String, Vec<ScrapedItem>)> {
+    let mut results = Vec::new();
+
+    for (category_key, category_items) in items {
+        let futures = category_items.into_iter().map(|item| {
+            let client = client.clone();
+            async move {
+                scrape_single(&client, item, max_age_days).await
+            }
+        });
+
+        // Bounded concurrency: max 10 concurrent scrapes
+        let scraped: Vec<Option<ScrapedItem>> = futures::stream::iter(futures)
+            .buffer_unordered(10)
+            .collect()
+            .await;
+
+        let valid: Vec<ScrapedItem> = scraped.into_iter().flatten().collect();
+        results.push((category_key, valid));
+    }
+
+    results
+}
+
+async fn scrape_single(
+    client: &reqwest::Client,
+    item: NewsItem,
+    max_age_days: i64,
+) -> Option<ScrapedItem> {
+    // 1. Parse and validate URL
+    let url = Url::parse(&item.url).ok()?;
+    is_safe_url(&url).await.ok()?;
+
+    // 2. Fetch with size limit
+    let resp = client.get(url.as_str()).send().await.ok()?;
+    if !resp.status().is_success() { return None; }
+
+    // Read up to 5MB
+    let bytes = resp.bytes().await.ok()?;
+    if bytes.len() > 5_000_000 { return None; }
+    let html_text = String::from_utf8_lossy(&bytes);
+
+    // 3. Parse HTML
+    let document = Html::parse_document(&html_text);
+
+    // 4. Soft-404 detection
+    let title_sel = Selector::parse("title").unwrap();
+    let h1_sel = Selector::parse("h1").unwrap();
+
+    let page_title = document.select(&title_sel).next()
+        .map(|el| el.text().collect::<String>().to_lowercase())
+        .unwrap_or_default();
+    let h1_text = document.select(&h1_sel).next()
+        .map(|el| el.text().collect::<String>().to_lowercase())
+        .unwrap_or_default();
+
+    let error_keywords = [
+        "page not found", "404", "403", "access denied",
+        "forbidden", "not found", "introuvable", "page introuvable",
+    ];
+    if error_keywords.iter().any(|kw| page_title.contains(kw) || h1_text.contains(kw)) {
+        return None;
+    }
+
+    // 5. Date extraction
+    if let Some(pub_date) = extract_publication_date(&document) {
+        let age = Utc::now().signed_duration_since(pub_date);
+        if age.num_days() > max_age_days {
+            tracing::debug!(url = %item.url, days = age.num_days(), "Article too old, skipping");
+            return None;
+        }
+    }
+
+    // 6. Content extraction (strip non-content elements)
+    let content = extract_body_text(&document, 4000);
+
+    Some(ScrapedItem {
+        title: item.title,
+        url: item.url,
+        summary: item.summary,
+        scraped_content: content,
+    })
+}
+
+/// Extract publication date from meta tags, JSON-LD, and <time> elements.
+fn extract_publication_date(doc: &Html) -> Option<DateTime<Utc>> {
+    // Priority order:
+    // 1. JSON-LD datePublished
+    // 2. meta[property="article:published_time"]
+    // 3. meta[itemprop="datePublished"]
+    // 4. meta[name="date"], meta[name="pubdate"], meta[name="dc.date"]
+    // 5. <time datetime="...">
+
+    let jsonld_sel = Selector::parse(r#"script[type="application/ld+json"]"#).unwrap();
+    for el in doc.select(&jsonld_sel) {
+        let text = el.text().collect::<String>();
+        if let Ok(json) = serde_json::from_str::<serde_json::Value>(&text) {
+            if let Some(date_str) = json.get("datePublished").and_then(|v| v.as_str()) {
+                if let Ok(dt) = datestr_to_datetime(date_str) {
+                    return Some(dt);
+                }
+            }
+        }
+    }
+
+    let meta_selectors = [
+        r#"meta[property="article:published_time"]"#,
+        r#"meta[property="og:article:published_time"]"#,
+        r#"meta[itemprop="datePublished"]"#,
+        r#"meta[name="date"]"#,
+        r#"meta[name="pubdate"]"#,
+        r#"meta[name="dc.date"]"#,
+    ];
+
+    for sel_str in &meta_selectors {
+        if let Ok(sel) = Selector::parse(sel_str) {
+            if let Some(el) = doc.select(&sel).next() {
+                if let Some(content) = el.value().attr("content") {
+                    if let Ok(dt) = datestr_to_datetime(content) {
+                        return Some(dt);
+                    }
+                }
+            }
+        }
+    }
+
+    let time_sel = Selector::parse("time[datetime]").unwrap();
+    if let Some(el) = doc.select(&time_sel).next() {
+        if let Some(dt_str) = el.value().attr("datetime") {
+            if let Ok(dt) = datestr_to_datetime(dt_str) {
+                return Some(dt);
+            }
+        }
+    }
+
+    None
+}
+
+/// Try multiple date formats to parse a date string.
+fn datestr_to_datetime(s: &str) -> Result<DateTime<Utc>, chrono::ParseError> {
+    // Try ISO 8601 / RFC 3339
+    if let Ok(dt) = DateTime::parse_from_rfc3339(s) {
+        return Ok(dt.with_timezone(&Utc));
+    }
+    // Try common formats
+    if let Ok(dt) = NaiveDate::parse_from_str(s, "%Y-%m-%d") {
+        return Ok(dt.and_hms_opt(0, 0, 0).unwrap().and_utc());
+    }
+    Err(chrono::ParseError) // simplified
+}
+
+/// Extract visible body text, stripping scripts, styles, nav, footer, etc.
+fn extract_body_text(doc: &Html, max_chars: usize) -> String {
+    // Get all text nodes from body, excluding script/style/nav/footer/header/aside
+    let body_sel = Selector::parse("body").unwrap();
+    let exclude_tags = ["script", "style", "noscript", "iframe", "nav", "footer", "header", "aside"];
+
+    let body = match doc.select(&body_sel).next() {
+        Some(b) => b,
+        None => return String::new(),
+    };
+
+    let text: String = body
+        .text()
+        .collect::<Vec<_>>()
+        .join(" ")
+        .split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ");
+
+    if text.len() > max_chars {
+        text[..max_chars].to_string()
+    } else {
+        text
+    }
+}
+```
+
+---
+
+## 7. Async Generation & SSE
+
+### 7.1 Background Job Spawning
+
+When a user triggers generation, the handler creates a job record in the DB, spawns a `tokio::spawn` task, and immediately returns the job ID.
+
+```rust
+// src/handlers/syntheses.rs
+
+pub async fn trigger_generate(
+    auth_user: AuthUser,
+    State(state): State<AppState>,
+) -> Result<(StatusCode, Json<GenerateResponse>), AppError> {
+    // 1. Check if user has an active job (prevent double-generation)
+    let active = db::generation_jobs::find_active(&state.pool, auth_user.id).await?;
+    if active.is_some() {
+        return Err(AppError::Conflict(
+            "A generation is already in progress.".into()
+        ));
+    }
+
+    // 2. Create job record
+    let job_id = db::generation_jobs::create(&state.pool, auth_user.id).await?;
+
+    // 3. Create a watch channel for progress
+    let (progress_tx, _) = tokio::sync::watch::channel(GenerationEvent::Progress {
+        status: "pending".into(),
+        progress_pct: 0,
+        message: "Starting...".into(),
+    });
+
+    // 4. Store the progress sender in the job store (for SSE subscribers)
+    state.job_store.insert(job_id, progress_tx.clone());
+
+    // 5. Spawn background task
+    let state_clone = state.clone();
+    let user_id = auth_user.id;
+    tokio::spawn(async move {
+        let result = GenerationPipeline::run(
+            &state_clone, user_id, job_id, progress_tx.clone()
+        ).await;
+
+        if let Err(e) = &result {
+            tracing::error!(job_id = %job_id, error = %e, "Generation failed");
+            progress_tx.send(GenerationEvent::Failed {
+                error: e.to_string(),
+            }).ok();
+            db::generation_jobs::fail(&state_clone.pool, job_id, &e.to_string())
+                .await
+                .ok();
+        }
+
+        // Clean up job store after a delay (allow SSE reconnect)
+        tokio::time::sleep(Duration::from_secs(300)).await;
+        state_clone.job_store.remove(&job_id);
+    });
+
+    Ok((
+        StatusCode::ACCEPTED,
+        Json(GenerateResponse {
+            job_id,
+            status: "pending".into(),
+        }),
+    ))
+}
+```
+
+### 7.2 Job Store in AppState
+
+```rust
+// src/app_state.rs
+use dashmap::DashMap;
+use tokio::sync::watch;
+
+pub type JobStore = DashMap<Uuid, watch::Sender<GenerationEvent>>;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: PgPool,
+    pub http_client: reqwest::Client,
+    pub config: AppConfig,
+    pub rate_limiter: Arc<RateLimiter>,
+    pub job_store: Arc<JobStore>,
+}
+```
+
+### 7.3 SSE Endpoint
+
+```rust
+// src/handlers/generation.rs
+use axum::response::sse::{Event, Sse};
+use tokio_stream::wrappers::WatchStream;
+use tokio_stream::StreamExt;
+
+pub async fn progress_stream(
+    auth_user: AuthUser,
+    State(state): State<AppState>,
+    Path(job_id): Path<Uuid>,
+) -> Result<Sse<impl Stream<Item = Result<Event, Infallible>>>, AppError> {
+    // Verify the job belongs to this user
+    let job = db::generation_jobs::get(&state.pool, job_id).await?
+        .ok_or(AppError::NotFound("Job not found".into()))?;
+    if job.user_id != auth_user.id {
+        return Err(AppError::NotFound("Job not found".into()));
+    }
+
+    // Get the watch receiver from the job store
+    let rx = state.job_store
+        .get(&job_id)
+        .map(|entry| entry.value().subscribe())
+        .ok_or(AppError::NotFound("Job not found or already completed".into()))?;
+
+    let stream = WatchStream::new(rx).map(|event| {
+        let data = serde_json::to_string(&event).unwrap_or_default();
+        Ok(Event::default().data(data))
+    });
+
+    Ok(Sse::new(stream).keep_alive(
+        axum::response::sse::KeepAlive::new()
+            .interval(Duration::from_secs(15))
+            .text("ping"),
+    ))
+}
+
+/// One-shot status poll endpoint (for reconnection after navigation away)
+pub async fn job_status(
+    auth_user: AuthUser,
+    State(state): State<AppState>,
+    Path(job_id): Path<Uuid>,
+) -> Result<Json<JobStatusResponse>, AppError> {
+    let job = db::generation_jobs::get(&state.pool, job_id).await?
+        .ok_or(AppError::NotFound("Job not found".into()))?;
+    if job.user_id != auth_user.id {
+        return Err(AppError::NotFound("Job not found".into()));
+    }
+
+    Ok(Json(JobStatusResponse {
+        job_id: job.id,
+        status: job.status.to_string(),
+        progress_pct: job.progress_pct as u8,
+        progress_message: job.progress_message,
+        synthesis_id: job.synthesis_id,
+        error_message: job.error_message,
+    }))
+}
+```
+
+### 7.4 Reconnection Strategy
+
+When a client navigates away and comes back:
+
+1. The frontend calls `GET /api/v1/generation/:job_id/status` first to get the current state.
+2. If status is `completed` or `failed`, display the result immediately.
+3. If status is in-progress, reconnect to the SSE endpoint `GET /api/v1/generation/:job_id/progress`.
+4. The `watch` channel immediately delivers the latest state on subscribe, so the client catches up instantly.
+
+---
+
+## 8. Email (Resend Integration)
+
+Resend provides a REST API for transactional email. No SMTP client library is needed; `reqwest` suffices.
+
+### 8.1 Email Service
+
+```rust
+// src/services/email.rs
+use secrecy::{ExposeSecret, SecretString};
+
+pub struct EmailService {
+    client: reqwest::Client,
+    api_key: SecretString,
+    from_address: String,     // e.g., "AI Weekly Synth <noreply@yourdomain.com>"
+    base_url: String,         // App base URL for magic link construction
+}
+
+impl EmailService {
+    pub fn new(
+        client: reqwest::Client,
+        api_key: SecretString,
+        from_address: String,
+        base_url: String,
+    ) -> Self {
+        Self { client, api_key, from_address, base_url }
+    }
+
+    /// Send a magic link email.
+    pub async fn send_magic_link(&self, to_email: &str, token: &str) -> Result<(), AppError> {
+        let verify_url = format!("{}/api/v1/auth/verify?token={}", self.base_url, token);
+
+        let body = serde_json::json!({
+            "from": self.from_address,
+            "to": [to_email],
+            "subject": "Votre lien de connexion - AI Weekly Synth",
+            "html": format!(
+                r#"<h2>Connexion a AI Weekly Synth</h2>
+                <p>Cliquez sur le lien ci-dessous pour vous connecter :</p>
+                <p><a href="{url}" style="display:inline-block;padding:12px 24px;
+                background-color:#4F46E5;color:white;text-decoration:none;
+                border-radius:6px;">Se connecter</a></p>
+                <p>Ou copiez ce lien : <code>{url}</code></p>
+                <p><em>Ce lien expire dans 15 minutes.</em></p>"#,
+                url = verify_url,
+            ),
+        });
+
+        let resp = self.client
+            .post("https://api.resend.com/emails")
+            .header("Authorization", format!("Bearer {}", self.api_key.expose_secret()))
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| AppError::SmtpError(format!("Failed to send email: {e}")))?;
+
+        if !resp.status().is_success() {
+            let error_body = resp.text().await.unwrap_or_default();
+            return Err(AppError::SmtpError(
+                format!("Resend API error: {error_body}")
+            ));
+        }
+
+        Ok(())
+    }
+
+    /// Send a synthesis by email.
+    pub async fn send_synthesis(
+        &self,
+        to_email: &str,
+        synthesis_title: &str,
+        sections_html: &str,
+    ) -> Result<(), AppError> {
+        let body = serde_json::json!({
+            "from": self.from_address,
+            "to": [to_email],
+            "subject": format!("Synthese : {}", synthesis_title),
+            "html": format!(
+                r#"<h1>{title}</h1>
+                {content}
+                <hr/>
+                <p><em>Genere par AI Weekly Synth</em></p>"#,
+                title = synthesis_title,
+                content = sections_html,
+            ),
+        });
+
+        let resp = self.client
+            .post("https://api.resend.com/emails")
+            .header("Authorization", format!("Bearer {}", self.api_key.expose_secret()))
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| AppError::SmtpError(format!("Failed to send email: {e}")))?;
+
+        if !resp.status().is_success() {
+            let error_body = resp.text().await.unwrap_or_default();
+            return Err(AppError::SmtpError(
+                format!("Resend API error: {error_body}")
+            ));
+        }
+
+        Ok(())
+    }
+}
+```
+
+### 8.2 HTML Rendering for Synthesis Emails
+
+```rust
+/// Convert synthesis sections to HTML for email delivery.
+pub fn sections_to_html(sections: &[NewsSection]) -> String {
+    let mut html = String::new();
+    for section in sections {
+        html.push_str(&format!("<h2>{}</h2>\n<ul>\n", section.title));
+        for item in &section.items {
+            html.push_str(&format!(
+                r#"<li><strong><a href="{url}">{title}</a></strong><br/>{summary}</li>"#,
+                url = html_escape(&item.url),
+                title = html_escape(&item.title),
+                summary = html_escape(&item.summary),
+            ));
+        }
+        html.push_str("</ul>\n");
+    }
+    html
+}
+
+fn html_escape(s: &str) -> String {
+    s.replace('&', "&amp;")
+     .replace('<', "&lt;")
+     .replace('>', "&gt;")
+     .replace('"', "&quot;")
+}
+```
+
+---
+
+## 9. Encryption
+
+### 9.1 AES-256-GCM Implementation
+
+```rust
+// src/services/encryption.rs
+use aes_gcm::{
+    aead::{Aead, KeyInit, OsRng},
+    Aes256Gcm, Nonce,
+};
+use rand::RngCore;
+use secrecy::{ExposeSecret, SecretString};
+
+/// Master key holder -- wraps a 32-byte key.
+#[derive(Clone)]
+pub struct MasterKey {
+    key: [u8; 32],
+}
+
+impl MasterKey {
+    /// Parse a 64-character hex string into a 32-byte key.
+    pub fn from_hex(hex_str: &str) -> Result<Self, AppError> {
+        let bytes = hex::decode(hex_str)
+            .map_err(|_| AppError::Internal(
+                anyhow::anyhow!("MASTER_ENCRYPTION_KEY must be a 64-character hex string")
+            ))?;
+        if bytes.len() != 32 {
+            return Err(AppError::Internal(
+                anyhow::anyhow!("MASTER_ENCRYPTION_KEY must be exactly 32 bytes (64 hex chars)")
+            ));
+        }
+        let mut key = [0u8; 32];
+        key.copy_from_slice(&bytes);
+        Ok(Self { key })
+    }
+
+    /// Encrypt a plaintext string. Returns (ciphertext, nonce) both as byte vectors.
+    pub fn encrypt(&self, plaintext: &str) -> Result<(Vec<u8>, Vec<u8>), AppError> {
+        let cipher = Aes256Gcm::new_from_slice(&self.key)
+            .map_err(|e| AppError::Internal(anyhow::anyhow!("Cipher init failed: {e}")))?;
+
+        let mut nonce_bytes = [0u8; 12];
+        OsRng.fill_bytes(&mut nonce_bytes);
+        let nonce = Nonce::from_slice(&nonce_bytes);
+
+        let ciphertext = cipher
+            .encrypt(nonce, plaintext.as_bytes())
+            .map_err(|e| AppError::Internal(anyhow::anyhow!("Encryption failed: {e}")))?;
+
+        Ok((ciphertext, nonce_bytes.to_vec()))
+    }
+
+    /// Decrypt ciphertext using the provided nonce. Returns the plaintext as a SecretString.
+    pub fn decrypt(
+        &self,
+        ciphertext: &[u8],
+        nonce_bytes: &[u8],
+    ) -> Result<SecretString, AppError> {
+        let cipher = Aes256Gcm::new_from_slice(&self.key)
+            .map_err(|e| AppError::Internal(anyhow::anyhow!("Cipher init failed: {e}")))?;
+
+        let nonce = Nonce::from_slice(nonce_bytes);
+
+        let plaintext_bytes = cipher
+            .decrypt(nonce, ciphertext)
+            .map_err(|_| AppError::Internal(
+                anyhow::anyhow!("Decryption failed -- master key mismatch or data corruption")
+            ))?;
+
+        let plaintext = String::from_utf8(plaintext_bytes)
+            .map_err(|e| AppError::Internal(anyhow::anyhow!("Decrypted data is not valid UTF-8: {e}")))?;
+
+        Ok(SecretString::new(plaintext))
+    }
+}
+
+impl Drop for MasterKey {
+    fn drop(&mut self) {
+        // Zeroize the key on drop
+        zeroize::Zeroize::zeroize(&mut self.key);
+    }
+}
+```
+
+### 9.2 Master Key Loading
+
+```rust
+// In config.rs
+pub struct AppConfig {
+    pub database_url: String,
+    pub master_key: MasterKey,
+    pub base_url: String,
+    pub port: u16,
+    pub resend_api_key: SecretString,
+    pub resend_from: String,
+    pub turnstile_secret: String,
+    pub turnstile_site_key: String,
+    // ...
+}
+
+impl AppConfig {
+    pub fn from_env() -> Result<Self, AppError> {
+        dotenvy::dotenv().ok();
+
+        let master_key_hex = std::env::var("MASTER_ENCRYPTION_KEY")
+            .map_err(|_| AppError::Internal(
+                anyhow::anyhow!("MASTER_ENCRYPTION_KEY environment variable is required")
+            ))?;
+
+        Ok(Self {
+            master_key: MasterKey::from_hex(&master_key_hex)?,
+            // ... other fields
+        })
+    }
+}
+```
+
+### 9.3 Key Rotation Strategy
+
+Key rotation is performed via a CLI command that re-encrypts all user API keys under a new master key:
+
+```rust
+// CLI subcommand: rotate-key
+Commands::RotateKey {
+    old_key_hex,
+    new_key_hex,
+} => {
+    let old_key = MasterKey::from_hex(&old_key_hex)?;
+    let new_key = MasterKey::from_hex(&new_key_hex)?;
+    let pool = create_pool().await?;
+
+    let all_keys = sqlx::query_as!(
+        RawProviderKey,
+        "SELECT id, encrypted_key, nonce FROM user_provider_keys"
+    )
+    .fetch_all(&pool)
+    .await?;
+
+    let mut tx = pool.begin().await?;
+    for key_row in &all_keys {
+        // Decrypt with old key
+        let plaintext = old_key.decrypt(&key_row.encrypted_key, &key_row.nonce)?;
+        // Re-encrypt with new key
+        let (new_ciphertext, new_nonce) = new_key.encrypt(plaintext.expose_secret())?;
+        // Update in transaction
+        sqlx::query!(
+            "UPDATE user_provider_keys SET encrypted_key = $1, nonce = $2 WHERE id = $3",
+            new_ciphertext,
+            new_nonce,
+            key_row.id
+        )
+        .execute(&mut *tx)
+        .await?;
+    }
+    tx.commit().await?;
+    println!("Rotated {} keys successfully.", all_keys.len());
+}
+```
+
+After running: update the `MASTER_ENCRYPTION_KEY` environment variable and restart the application.
+
+---
+
+## 10. Error Handling
+
+### 10.1 Error Type Hierarchy
+
+```rust
+// src/error.rs
+use axum::http::StatusCode;
+use axum::response::{IntoResponse, Response};
+use axum::Json;
+use serde_json::json;
+
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    // === Client errors ===
+    #[error("Bad request: {0}")]
+    BadRequest(String),
+
+    #[error("Unauthorized: {0}")]
+    Unauthorized(String),
+
+    #[error("Forbidden: {0}")]
+    Forbidden(String),
+
+    #[error("Not found: {0}")]
+    NotFound(String),
+
+    #[error("Conflict: {0}")]
+    Conflict(String),
+
+    #[error("Too many requests")]
+    TooManyRequests { retry_after_secs: u64 },
+
+    #[error("Validation error")]
+    Validation(Vec<FieldError>),
+
+    // === Server errors ===
+    #[error("Internal error: {0}")]
+    Internal(#[from] anyhow::Error),
+
+    #[error("Database error: {0}")]
+    Database(#[from] sqlx::Error),
+
+    #[error("LLM provider error: {0}")]
+    LlmError(String),
+
+    #[error("Email error: {0}")]
+    SmtpError(String),
+
+    #[error("Scraping error: {0}")]
+    ScrapingError(String),
+}
+
+#[derive(Debug, serde::Serialize)]
+pub struct FieldError {
+    pub field: String,
+    pub message: String,
+}
+
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        let (status, body) = match &self {
+            AppError::BadRequest(msg) => (
+                StatusCode::BAD_REQUEST,
+                json!({ "error": msg }),
+            ),
+            AppError::Unauthorized(_) => (
+                StatusCode::UNAUTHORIZED,
+                json!({ "error": "Unauthorized" }),
+            ),
+            AppError::Forbidden(_) => (
+                StatusCode::FORBIDDEN,
+                json!({ "error": "Forbidden" }),
+            ),
+            AppError::NotFound(msg) => (
+                StatusCode::NOT_FOUND,
+                json!({ "error": msg }),
+            ),
+            AppError::Conflict(msg) => (
+                StatusCode::CONFLICT,
+                json!({ "error": msg }),
+            ),
+            AppError::TooManyRequests { retry_after_secs } => {
+                let mut resp = (
+                    StatusCode::TOO_MANY_REQUESTS,
+                    Json(json!({ "error": "Too many requests", "retry_after": retry_after_secs })),
+                ).into_response();
+                resp.headers_mut().insert(
+                    "Retry-After",
+                    retry_after_secs.to_string().parse().unwrap(),
+                );
+                return resp;
+            }
+            AppError::Validation(errors) => (
+                StatusCode::UNPROCESSABLE_ENTITY,
+                json!({ "error": "Validation failed", "details": errors }),
+            ),
+            AppError::Database(e) => {
+                tracing::error!(error = %e, "Database error");
+                (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    json!({ "error": "Internal server error" }),
+                )
+            }
+            AppError::Internal(e) => {
+                tracing::error!(error = ?e, "Internal error");
+                (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    json!({ "error": "Internal server error" }),
+                )
+            }
+            AppError::LlmError(msg) => {
+                tracing::error!(error = %msg, "LLM provider error");
+                (
+                    StatusCode::BAD_GATEWAY,
+                    json!({ "error": "AI provider error. Please try again." }),
+                )
+            }
+            AppError::SmtpError(msg) => {
+                tracing::error!(error = %msg, "Email error");
+                (
+                    StatusCode::BAD_GATEWAY,
+                    json!({ "error": "Failed to send email. Please try again." }),
+                )
+            }
+            AppError::ScrapingError(msg) => {
+                tracing::warn!(error = %msg, "Scraping error");
+                (
+                    StatusCode::BAD_GATEWAY,
+                    json!({ "error": "Failed to fetch article content." }),
+                )
+            }
+        };
+
+        (status, Json(body)).into_response()
+    }
+}
+```
+
+Key design decisions:
+- **Never expose internal details** to the client (database errors, stack traces).
+- **Log server errors** at `error!` level with full context for debugging.
+- **Client errors** return the user-facing message directly.
+- **LLM and email errors** return 502 Bad Gateway (upstream service failure).
+- The `From<sqlx::Error>` impl converts specific constraint violations (unique, foreign key) into `Conflict` or `BadRequest` where appropriate.
+
+### 10.2 Logging Strategy
+
+```rust
+// In main.rs
+use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};
+
+fn init_tracing() {
+    tracing_subscriber::registry()
+        .with(EnvFilter::try_from_default_env().unwrap_or_else(|_| {
+            "ai_synth_backend=debug,tower_http=info,sqlx=warn".into()
+        }))
+        .with(tracing_subscriber::fmt::layer()
+            .with_target(true)
+            .with_thread_ids(false)
+            .with_file(true)
+            .with_line_number(true))
+        .init();
+}
+```
+
+Logging conventions:
+- **Never log** decrypted API keys, session tokens, magic link tokens, or the master key.
+- Use `secrecy::SecretString` for all secret values. Its `Debug` and `Display` impls print `[REDACTED]`.
+- **Structured fields**: Use `tracing::info!(user_id = %id, action = "generate", ...)` not string interpolation.
+- **Request tracing**: Use `tower_http::trace::TraceLayer` for automatic request/response logging.
+
+---
+
+## 11. Testing Strategy
+
+### 11.1 Test Database Setup
+
+Tests use a real PostgreSQL instance (via Docker in CI, or a local dev instance). Each test gets its own schema or uses transactions that are rolled back.
+
+```rust
+// tests/common/mod.rs
+use sqlx::PgPool;
+use uuid::Uuid;
+
+/// Create a test database pool pointing to a test-specific schema.
+pub async fn setup_test_db() -> PgPool {
+    dotenvy::dotenv().ok();
+    let base_url = std::env::var("TEST_DATABASE_URL")
+        .unwrap_or_else(|_| "postgres://postgres:postgres@localhost:5432/ai_synth_test".into());
+
+    let pool = PgPool::connect(&base_url).await.unwrap();
+
+    // Run migrations
+    sqlx::migrate!("./migrations")
+        .run(&pool)
+        .await
+        .unwrap();
+
+    pool
+}
+
+/// Create a test user and return (user_id, session_token).
+pub async fn create_test_user(pool: &PgPool) -> (Uuid, String) {
+    let user_id = Uuid::new_v4();
+    let email = format!("test-{}@example.com", Uuid::new_v4());
+
+    sqlx::query!(
+        "INSERT INTO users (id, email, role) VALUES ($1, $2, 'user')",
+        user_id,
+        email,
+    )
+    .execute(pool)
+    .await
+    .unwrap();
+
+    // Create session
+    let token = crate::util::token::generate_token();
+    let hash = crate::util::token::hash_token(&token);
+    let expires = chrono::Utc::now() + chrono::Duration::days(30);
+
+    sqlx::query!(
+        "INSERT INTO sessions (user_id, token_hash, expires_at) VALUES ($1, $2, $3)",
+        user_id,
+        hash,
+        expires,
+    )
+    .execute(pool)
+    .await
+    .unwrap();
+
+    (user_id, token)
+}
+
+/// Create an admin user and return (user_id, session_token).
+pub async fn create_test_admin(pool: &PgPool) -> (Uuid, String) {
+    let user_id = Uuid::new_v4();
+    let email = format!("admin-{}@example.com", Uuid::new_v4());
+
+    sqlx::query!(
+        "INSERT INTO users (id, email, role) VALUES ($1, $2, 'admin')",
+        user_id,
+        email,
+    )
+    .execute(pool)
+    .await
+    .unwrap();
+
+    let token = crate::util::token::generate_token();
+    let hash = crate::util::token::hash_token(&token);
+    let expires = chrono::Utc::now() + chrono::Duration::days(30);
+
+    sqlx::query!(
+        "INSERT INTO sessions (user_id, token_hash, expires_at) VALUES ($1, $2, $3)",
+        user_id,
+        hash,
+        expires,
+    )
+    .execute(pool)
+    .await
+    .unwrap();
+
+    (user_id, token)
+}
+
+/// Build a test app (Axum router) with real DB and mock external services.
+pub async fn build_test_app(pool: PgPool) -> axum::Router {
+    let config = AppConfig::test_defaults();
+    let state = AppState {
+        pool,
+        http_client: reqwest::Client::new(),
+        config,
+        rate_limiter: Arc::new(RateLimiter::new()),
+        job_store: Arc::new(DashMap::new()),
+    };
+    crate::router::create_router(state)
+}
+```
+
+### 11.2 Unit Test Examples
+
+#### Encryption
+
+```rust
+// tests/services/encryption_test.rs
+
+#[test]
+fn test_encrypt_decrypt_roundtrip() {
+    let master_key = MasterKey::from_hex(
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    ).unwrap();
+
+    let plaintext = "sk-proj-abc123def456";
+    let (ciphertext, nonce) = master_key.encrypt(plaintext).unwrap();
+
+    // Ciphertext should not equal plaintext
+    assert_ne!(ciphertext, plaintext.as_bytes());
+
+    // Decrypt should return original
+    let decrypted = master_key.decrypt(&ciphertext, &nonce).unwrap();
+    assert_eq!(decrypted.expose_secret(), plaintext);
+}
+
+#[test]
+fn test_decrypt_wrong_key_fails() {
+    let key1 = MasterKey::from_hex(
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    ).unwrap();
+    let key2 = MasterKey::from_hex(
+        "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
+    ).unwrap();
+
+    let (ciphertext, nonce) = key1.encrypt("secret").unwrap();
+    assert!(key2.decrypt(&ciphertext, &nonce).is_err());
+}
+
+#[test]
+fn test_each_encryption_produces_unique_nonce() {
+    let master_key = MasterKey::from_hex(
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    ).unwrap();
+
+    let (_, nonce1) = master_key.encrypt("same text").unwrap();
+    let (_, nonce2) = master_key.encrypt("same text").unwrap();
+    assert_ne!(nonce1, nonce2);
+}
+```
+
+#### Rate Limiter
+
+```rust
+// tests/services/rate_limiter_test.rs
+
+#[tokio::test]
+async fn test_rate_limiter_allows_within_limit() {
+    let limiter = RateLimiter::new();
+    limiter.update_provider_limit("test", 5, 60);
+
+    let user_id = Uuid::new_v4();
+    for _ in 0..5 {
+        limiter.acquire("test", user_id).await.unwrap();
+    }
+}
+
+#[tokio::test]
+async fn test_rate_limiter_blocks_when_exceeded() {
+    let limiter = RateLimiter::new();
+    limiter.update_provider_limit("test", 2, 60);
+
+    let user_id = Uuid::new_v4();
+    limiter.acquire("test", user_id).await.unwrap();
+    limiter.acquire("test", user_id).await.unwrap();
+
+    // Third should block or return TooManyRequests
+    // (implementation detail: may sleep or error)
+}
+```
+
+#### Token Utilities
+
+```rust
+// Unit tests in src/util/token.rs
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_generate_token_length() {
+        let token = generate_token();
+        // 32 bytes base64url-encoded = 43 characters
+        assert_eq!(token.len(), 43);
+    }
+
+    #[test]
+    fn test_generate_token_uniqueness() {
+        let t1 = generate_token();
+        let t2 = generate_token();
+        assert_ne!(t1, t2);
+    }
+
+    #[test]
+    fn test_hash_token_deterministic() {
+        let token = "test-token-value";
+        let h1 = hash_token(token);
+        let h2 = hash_token(token);
+        assert_eq!(h1, h2);
+    }
+
+    #[test]
+    fn test_hash_token_different_inputs() {
+        assert_ne!(hash_token("a"), hash_token("b"));
+    }
+}
+```
+
+### 11.3 Integration Test (API)
+
+```rust
+// tests/api/sources_test.rs
+use axum::http::{Request, StatusCode};
+use tower::ServiceExt;
+use http_body_util::BodyExt;
+
+#[tokio::test]
+async fn test_create_and_list_sources() {
+    let pool = common::setup_test_db().await;
+    let (user_id, session_token) = common::create_test_user(&pool).await;
+    let app = common::build_test_app(pool).await;
+
+    // Create a source
+    let resp = app
+        .clone()
+        .oneshot(
+            Request::builder()
+                .method("POST")
+                .uri("/api/v1/sources")
+                .header("Content-Type", "application/json")
+                .header("Cookie", format!("ai_synth_session={session_token}"))
+                .header("X-Requested-With", "XMLHttpRequest")
+                .body(serde_json::to_string(&serde_json::json!({
+                    "title": "Test Source",
+                    "url": "https://example.com"
+                })).unwrap().into())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), StatusCode::CREATED);
+
+    // List sources
+    let resp = app
+        .clone()
+        .oneshot(
+            Request::builder()
+                .method("GET")
+                .uri("/api/v1/sources")
+                .header("Cookie", format!("ai_synth_session={session_token}"))
+                .body(axum::body::Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = resp.into_body().collect().await.unwrap().to_bytes();
+    let sources: Vec<serde_json::Value> = serde_json::from_slice(&body).unwrap();
+    assert_eq!(sources.len(), 1);
+    assert_eq!(sources[0]["title"], "Test Source");
+}
+
+#[tokio::test]
+async fn test_cannot_access_other_users_sources() {
+    let pool = common::setup_test_db().await;
+    let (user1_id, token1) = common::create_test_user(&pool).await;
+    let (user2_id, token2) = common::create_test_user(&pool).await;
+    let app = common::build_test_app(pool.clone()).await;
+
+    // User 1 creates a source
+    let resp = app
+        .clone()
+        .oneshot(
+            Request::builder()
+                .method("POST")
+                .uri("/api/v1/sources")
+                .header("Content-Type", "application/json")
+                .header("Cookie", format!("ai_synth_session={token1}"))
+                .header("X-Requested-With", "XMLHttpRequest")
+                .body(serde_json::to_string(&serde_json::json!({
+                    "title": "User 1 Source",
+                    "url": "https://example.com"
+                })).unwrap().into())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CREATED);
+
+    // User 2 lists sources -- should see empty list
+    let resp = app
+        .clone()
+        .oneshot(
+            Request::builder()
+                .method("GET")
+                .uri("/api/v1/sources")
+                .header("Cookie", format!("ai_synth_session={token2}"))
+                .body(axum::body::Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+
+    let body = resp.into_body().collect().await.unwrap().to_bytes();
+    let sources: Vec<serde_json::Value> = serde_json::from_slice(&body).unwrap();
+    assert_eq!(sources.len(), 0);
+}
+
+#[tokio::test]
+async fn test_unauthenticated_request_returns_401() {
+    let pool = common::setup_test_db().await;
+    let app = common::build_test_app(pool).await;
+
+    let resp = app
+        .oneshot(
+            Request::builder()
+                .method("GET")
+                .uri("/api/v1/sources")
+                .body(axum::body::Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
+}
+```
+
+### 11.4 Test Conventions
+
+| Layer | Tool | What to test |
+|---|---|---|
+| `util/` | `#[test]` unit tests | Token generation, hashing, encryption roundtrips |
+| `services/` | `#[tokio::test]` | Rate limiter behavior, scraper parsing (with HTML fixtures), email rendering |
+| `db/` | `#[tokio::test]` with real Postgres | Query correctness, constraint enforcement, data isolation |
+| `handlers/` | `#[tokio::test]` with `tower::ServiceExt::oneshot` | Full HTTP request/response cycle, status codes, auth enforcement, CSRF checks |
+| LLM providers | Mock HTTP server (`wiremock` crate) | Response parsing, error handling, schema construction |
+
+---
+
+## Appendix A: Router Wiring
+
+```rust
+// src/router.rs
+use axum::{
+    middleware,
+    routing::{get, post, put, delete},
+    Router,
+};
+use tower_http::cors::CorsLayer;
+use tower_http::trace::TraceLayer;
+use tower_http::services::ServeDir;
+
+pub fn create_router(state: AppState) -> Router {
+    let api_routes = Router::new()
+        // === Public auth routes (no session required) ===
+        .route("/auth/register", post(handlers::auth::register))
+        .route("/auth/magic-link", post(handlers::auth::request_magic_link))
+        .route("/auth/verify", get(handlers::auth::verify_magic_link))
+
+        // === Authenticated routes ===
+        .route("/auth/logout", post(handlers::auth::logout))
+        .route("/auth/me", get(handlers::auth::me))
+
+        .route("/syntheses", get(handlers::syntheses::list))
+        .route("/syntheses/:id", get(handlers::syntheses::get))
+        .route("/syntheses/:id", delete(handlers::syntheses::delete))
+        .route("/syntheses/generate", post(handlers::syntheses::trigger_generate))
+        .route("/syntheses/:id/email", post(handlers::syntheses::send_email))
+
+        .route("/sources", get(handlers::sources::list))
+        .route("/sources", post(handlers::sources::create))
+        .route("/sources/:id", delete(handlers::sources::delete))
+
+        .route("/settings", get(handlers::settings::get))
+        .route("/settings", put(handlers::settings::update))
+
+        .route("/provider-keys", get(handlers::provider_keys::list))
+        .route("/provider-keys", post(handlers::provider_keys::create))
+        .route("/provider-keys/:provider", delete(handlers::provider_keys::delete))
+
+        .route("/generation/:job_id/progress", get(handlers::generation::progress_stream))
+        .route("/generation/:job_id/status", get(handlers::generation::job_status))
+
+        .route("/config/providers", get(handlers::admin::list_enabled_providers))
+
+        // === Admin routes ===
+        .route("/admin/provider-models", get(handlers::admin::list_provider_models))
+        .route("/admin/provider-models", post(handlers::admin::create_provider_model))
+        .route("/admin/provider-models/:id", put(handlers::admin::update_provider_model))
+        .route("/admin/provider-models/:id", delete(handlers::admin::delete_provider_model))
+        .route("/admin/rate-limits", get(handlers::admin::list_rate_limits))
+        .route("/admin/rate-limits/:provider", put(handlers::admin::update_rate_limit))
+        .route("/admin/users", get(handlers::admin::list_users))
+        .route("/admin/users/:id/role", put(handlers::admin::update_user_role))
+
+        // === Health ===
+        .route("/health", get(handlers::health::health_check));
+
+    let app = Router::new()
+        .nest("/api/v1", api_routes)
+        // CSRF middleware on API routes (checks X-Requested-With on POST/PUT/DELETE)
+        .layer(middleware::from_fn(middleware::csrf::csrf_check))
+        // CORS
+        .layer(build_cors_layer(&state.config))
+        // Request tracing
+        .layer(TraceLayer::new_for_http())
+        // Static files fallback (SPA)
+        .fallback_service(
+            ServeDir::new(&state.config.static_dir)
+                .fallback(ServeDir::new(&state.config.static_dir).append_index_html_on_directories(true))
+        )
+        .with_state(state);
+
+    app
+}
+
+fn build_cors_layer(config: &AppConfig) -> CorsLayer {
+    CorsLayer::new()
+        .allow_origin(config.base_url.parse::<HeaderValue>().unwrap())
+        .allow_methods([Method::GET, Method::POST, Method::PUT, Method::DELETE])
+        .allow_headers([
+            header::CONTENT_TYPE,
+            header::COOKIE,
+            HeaderName::from_static("x-requested-with"),
+        ])
+        .allow_credentials(true)
+        .max_age(Duration::from_secs(3600))
+}
+```
+
+---
+
+## Appendix B: AppConfig Full Definition
+
+```rust
+// src/config.rs
+
+#[derive(Clone)]
+pub struct AppConfig {
+    // Server
+    pub port: u16,
+    pub base_url: String,                    // e.g., "https://synth.example.com"
+    pub static_dir: String,                  // path to SolidJS build output
+
+    // Database
+    pub database_url: String,                // postgres://...
+
+    // Encryption
+    pub master_key: MasterKey,               // from MASTER_ENCRYPTION_KEY env var
+
+    // Email (Resend)
+    pub resend_api_key: SecretString,         // from RESEND_API_KEY env var
+    pub resend_from: String,                  // e.g., "AI Weekly Synth <noreply@example.com>"
+
+    // Captcha (Cloudflare Turnstile)
+    pub turnstile_secret: String,
+    pub turnstile_site_key: String,
+
+    // Logging
+    pub rust_log: String,
+}
+
+impl AppConfig {
+    pub fn from_env() -> Result<Self, AppError> {
+        dotenvy::dotenv().ok();
+
+        Ok(Self {
+            port: env_var_or("PORT", "8080").parse()?,
+            base_url: env_var("BASE_URL")?,
+            static_dir: env_var_or("STATIC_DIR", "./static"),
+            database_url: env_var("DATABASE_URL")?,
+            master_key: MasterKey::from_hex(&env_var("MASTER_ENCRYPTION_KEY")?)?,
+            resend_api_key: SecretString::new(env_var("RESEND_API_KEY")?),
+            resend_from: env_var_or("RESEND_FROM", "AI Weekly Synth <noreply@example.com>"),
+            turnstile_secret: env_var("TURNSTILE_SECRET")?,
+            turnstile_site_key: env_var("TURNSTILE_SITE_KEY")?,
+            rust_log: env_var_or("RUST_LOG", "ai_synth_backend=info"),
+        })
+    }
+
+    #[cfg(test)]
+    pub fn test_defaults() -> Self {
+        Self {
+            port: 0,
+            base_url: "http://localhost:3000".into(),
+            static_dir: "./static".into(),
+            database_url: "postgres://postgres:postgres@localhost:5432/ai_synth_test".into(),
+            master_key: MasterKey::from_hex(
+                "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+            ).unwrap(),
+            resend_api_key: SecretString::new("test-resend-key".into()),
+            resend_from: "test@example.com".into(),
+            turnstile_secret: "test-secret".into(),
+            turnstile_site_key: "test-site-key".into(),
+            rust_log: "debug".into(),
+        }
+    }
+}
+
+fn env_var(name: &str) -> Result<String, AppError> {
+    std::env::var(name).map_err(|_| {
+        AppError::Internal(anyhow::anyhow!("Missing required env var: {name}"))
+    })
+}
+
+fn env_var_or(name: &str, default: &str) -> String {
+    std::env::var(name).unwrap_or_else(|_| default.to_string())
+}
+```
+
+---
+
+## Appendix C: Prompt Construction
+
+The prompts mirror the current Gemini service but are provider-agnostic.
+
+```rust
+// src/services/generation.rs (prompt helpers)
+
+fn build_search_prompts(
+    settings: &UserSettings,
+    sources: &[Source],
+) -> (String, String) {
+    let current_date = Utc::now().format("%A %d %B %Y").to_string();
+
+    let sources_text = if sources.is_empty() {
+        String::new()
+    } else {
+        let list = sources.iter()
+            .map(|s| format!("- {} ({})", s.title, s.url))
+            .collect::<Vec<_>>()
+            .join("\n");
+        format!(
+            "\nYou MUST also consult these custom sources:\n{}\n",
+            list
+        )
+    };
+
+    let categories_text = settings.categories.iter()
+        .enumerate()
+        .map(|(i, cat)| format!("{}. {}", i + 1, cat))
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    let system_prompt = format!(
+        "You are a precise AI assistant. You MUST provide complete and exact URLs. \
+         Focus ONLY on news from the last {} days.",
+        settings.max_age_days
+    );
+
+    let user_prompt = format!(
+        "Today is {date}.\n\
+         You are an expert analyst on the topic: \"{theme}\".\n\
+         Search for news STRICTLY from the last {days} days.\n\
+         Do NOT return any news older than {days} days.\n\
+         {sources}\
+         {behavior}\n\
+         The synthesis must be divided into {count} sections:\n\
+         {categories}\n\n\
+         For each category, provide at most {max_items} articles.\n\
+         For each article, provide: a provisional title, the exact source URL, \
+         and a provisional summary.\n\
+         Return the result as JSON using keys category_0, category_1, etc. \
+         matching the section order above.",
+        date = current_date,
+        theme = settings.theme,
+        days = settings.max_age_days,
+        sources = sources_text,
+        behavior = settings.search_agent_behavior,
+        count = settings.categories.len(),
+        categories = categories_text,
+        max_items = settings.max_items_per_category,
+    );
+
+    (system_prompt, user_prompt)
+}
+
+fn build_rewrite_prompts(
+    scraped: &[(String, Vec<ScrapedItem>)],
+) -> (String, String) {
+    let system_prompt = "You are a precise AI assistant. Generate titles and summaries \
+        that faithfully reflect the provided content.".to_string();
+
+    let data = serde_json::to_string_pretty(scraped).unwrap_or_default();
+
+    let user_prompt = format!(
+        "You are an expert news analyst.\n\
+         Below is a list of articles organized by category, each with raw text content \
+         extracted from the source websites ('scraped_content').\n\
+         Your task is to rewrite the 'title' and 'summary' (4-5 lines) for each article \
+         so they EXACTLY and FAITHFULLY reflect the provided text content.\n\
+         If 'scraped_content' is empty or insufficient, use the original title and summary.\n\
+         KEEP the exact same URLs. Do NOT remove any article.\n\n\
+         Article data:\n{data}",
+        data = data,
+    );
+
+    (system_prompt, user_prompt)
+}
+
+/// Build the JSON schema for structured output, based on user categories.
+fn build_category_schema(categories: &[String]) -> serde_json::Value {
+    let mut properties = serde_json::Map::new();
+    let mut required = Vec::new();
+
+    for (i, _cat) in categories.iter().enumerate() {
+        let key = format!("category_{}", i);
+        properties.insert(key.clone(), serde_json::json!({
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "title": { "type": "string" },
+                    "url": { "type": "string" },
+                    "summary": { "type": "string" }
+                },
+                "required": ["title", "url", "summary"]
+            }
+        }));
+        required.push(serde_json::Value::String(key));
+    }
+
+    serde_json::json!({
+        "type": "object",
+        "properties": properties,
+        "required": required
+    })
+}
+```
+
+---
+
+## Appendix D: Background Tasks
+
+Besides generation jobs, the application needs periodic cleanup tasks.
+
+```rust
+// In main.rs, after starting the server
+
+// Periodic cleanup: expired sessions and magic link tokens
+let cleanup_pool = pool.clone();
+tokio::spawn(async move {
+    let mut interval = tokio::time::interval(Duration::from_secs(3600)); // every hour
+    loop {
+        interval.tick().await;
+        if let Err(e) = db::sessions::delete_expired(&cleanup_pool).await {
+            tracing::error!(error = %e, "Failed to clean up expired sessions");
+        }
+        if let Err(e) = db::magic_links::delete_expired(&cleanup_pool).await {
+            tracing::error!(error = %e, "Failed to clean up expired magic link tokens");
+        }
+    }
+});
+```
+
+---
+
+## Appendix E: .env.example
+
+```env
+# === Required ===
+DATABASE_URL=postgres://ai_synth:password@localhost:5432/ai_synth
+BASE_URL=https://synth.example.com
+MASTER_ENCRYPTION_KEY=<64-character-hex-string>
+
+# === Email (Resend) ===
+RESEND_API_KEY=re_xxxxxxxxxxxx
+RESEND_FROM=AI Weekly Synth <noreply@yourdomain.com>
+
+# === Captcha (Cloudflare Turnstile) ===
+TURNSTILE_SECRET=0x4AAAAAAA...
+TURNSTILE_SITE_KEY=0x4BBBBBB...
+
+# === Optional ===
+PORT=8080
+STATIC_DIR=./static
+RUST_LOG=ai_synth_backend=info,tower_http=info
+```
diff --git a/docs/implementation-plan/03-frontend-plan.md b/docs/implementation-plan/03-frontend-plan.md
new file mode 100644
index 0000000..8de19a0
--- /dev/null
+++ b/docs/implementation-plan/03-frontend-plan.md
@@ -0,0 +1,2654 @@
+# Frontend Implementation Plan: AI Weekly Synth (SolidJS Rewrite)
+
+**Date**: 2026-03-21
+**Role**: Frontend Implementation Planner
+**Target**: Complete SolidJS frontend to replace the current React SPA
+
+---
+
+## Table of Contents
+
+1. [Project Structure](#1-project-structure)
+2. [Component Architecture](#2-component-architecture)
+3. [State Management](#3-state-management)
+4. [Routing](#4-routing)
+5. [i18n Architecture](#5-i18n-architecture)
+6. [SSE Integration](#6-sse-integration)
+7. [Tailwind CSS](#7-tailwind-css)
+8. [Forms and Validation](#8-forms-and-validation)
+9. [PDF/Markdown Export](#9-pdfmarkdown-export)
+10. [React-to-SolidJS Migration Map](#10-react-to-solidjs-migration-map)
+11. [Testing](#11-testing)
+
+---
+
+## 1. Project Structure
+
+### 1.1 Directory Layout
+
+```
+frontend/
+├── index.html                          # Vite entry HTML
+├── package.json
+├── tsconfig.json
+├── tsconfig.app.json
+├── vite.config.ts
+├── tailwind.config.ts                  # Tailwind v4 config (if needed beyond CSS)
+├── public/
+│   └── favicon.svg
+├── src/
+│   ├── index.tsx                       # SolidJS render entry point
+│   ├── App.tsx                         # Root component: router + providers
+│   ├── index.css                       # Tailwind import + custom base styles
+│   │
+│   ├── api/                            # API client layer
+│   │   ├── client.ts                   # Base fetch wrapper (cookies, CSRF, errors)
+│   │   ├── auth.ts                     # Auth endpoints (register, login, verify, logout, me)
+│   │   ├── syntheses.ts               # Syntheses endpoints (list, get, generate, delete, email)
+│   │   ├── sources.ts                 # Sources endpoints (list, add, delete, bulk, CSV)
+│   │   ├── settings.ts               # Settings endpoints (get, update, export, import)
+│   │   ├── admin.ts                   # Admin endpoints (providers, rate-limits, users)
+│   │   └── config.ts                  # Public config endpoint (provider list for users)
+│   │
+│   ├── types/                          # TypeScript type definitions
+│   │   ├── index.ts                    # Re-export barrel
+│   │   ├── auth.ts                     # User, Session, RegisterRequest, LoginRequest
+│   │   ├── synthesis.ts               # Synthesis, NewsSection, NewsItem, GenerationJob
+│   │   ├── source.ts                  # Source, CreateSourceRequest, BulkImportRequest
+│   │   ├── settings.ts               # UserSettings, DEFAULT_SETTINGS
+│   │   ├── admin.ts                   # ProviderConfig, RateLimitConfig, AdminUser
+│   │   └── api.ts                     # ApiError, PaginatedResponse, SSEEvent
+│   │
+│   ├── i18n/                           # Internationalization
+│   │   ├── index.ts                    # i18n context provider and useI18n hook
+│   │   ├── types.ts                    # Translation key type definitions
+│   │   └── locales/
+│   │       └── fr.ts                   # French translations (default)
+│   │
+│   ├── context/                        # SolidJS context providers
+│   │   ├── AuthContext.tsx             # Auth state (user, session check, login/logout)
+│   │   └── ToastContext.tsx            # Global toast notification system
+│   │
+│   ├── lib/                            # Utilities and helpers
+│   │   ├── sse.ts                      # EventSource wrapper for SolidJS signals
+│   │   ├── dates.ts                    # Date formatting (date-fns/fr wrappers)
+│   │   ├── export.ts                   # PDF and Markdown generation utilities
+│   │   ├── csv.ts                      # CSV parse/generate utilities
+│   │   └── validation.ts              # Form validation rules and helpers
+│   │
+│   ├── components/                     # Shared/reusable UI components
+│   │   ├── layout/
+│   │   │   ├── AppShell.tsx            # Main layout: navbar + mobile menu + main content
+│   │   │   ├── Navbar.tsx              # Top navigation bar with responsive menu
+│   │   │   ├── MobileMenu.tsx          # Hamburger slide-out menu for mobile
+│   │   │   └── AdminLayout.tsx         # Admin section layout with sidebar nav
+│   │   │
+│   │   ├── auth/
+│   │   │   └── ProtectedRoute.tsx      # Route guard: redirects to /login if unauthenticated
+│   │   │
+│   │   ├── ui/
+│   │   │   ├── Button.tsx              # Reusable button (variants: primary, secondary, danger)
+│   │   │   ├── Card.tsx                # Card container with optional header/footer
+│   │   │   ├── Spinner.tsx             # Loading spinner (inline and full-page variants)
+│   │   │   ├── Badge.tsx               # Status/category badge
+│   │   │   ├── ConfirmDialog.tsx       # Modal confirmation dialog (standardized deletion)
+│   │   │   ├── Toast.tsx               # Toast notification component
+│   │   │   ├── ErrorBanner.tsx         # Inline error message with icon
+│   │   │   ├── SuccessBanner.tsx       # Inline success message with icon
+│   │   │   ├── EmptyState.tsx          # Empty list placeholder with action
+│   │   │   └── SSEProgressIndicator.tsx # Generation progress bar with step list
+│   │   │
+│   │   ├── forms/
+│   │   │   ├── FormField.tsx           # Label + input + error message wrapper
+│   │   │   ├── TextInput.tsx           # Text input with validation display
+│   │   │   ├── TextArea.tsx            # Textarea with validation display
+│   │   │   ├── Select.tsx              # Select dropdown
+│   │   │   ├── NumberInput.tsx         # Number input with min/max
+│   │   │   └── FileInput.tsx           # Styled file upload input
+│   │   │
+│   │   └── synthesis/
+│   │       ├── SynthesisCard.tsx        # Card for synthesis list (Home page)
+│   │       ├── SynthesisSection.tsx     # Section display in detail view
+│   │       └── NewsItemCard.tsx         # Individual news item in detail view
+│   │
+│   └── pages/                          # Route-level page components
+│       ├── auth/
+│       │   ├── Login.tsx               # Email + Turnstile -> request magic link
+│       │   ├── Register.tsx            # Email + display name + Turnstile -> create account
+│       │   └── MagicLinkVerify.tsx     # Token verification redirect page
+│       │
+│       ├── Home.tsx                    # Dashboard: synthesis list + in-progress banner
+│       ├── GenerateSynthesis.tsx       # Generation trigger + SSE progress display
+│       ├── SynthesisDetail.tsx         # Full synthesis view + email + export + delete
+│       ├── Sources.tsx                 # Sources CRUD + CSV import/export + bulk import
+│       ├── Settings.tsx                # User settings (theme, categories, provider/model/key)
+│       │
+│       └── admin/
+│           ├── ProviderCatalog.tsx      # Manage LLM providers and available models
+│           ├── RateLimitConfig.tsx      # Configure global rate limits per provider
+│           └── UserManagement.tsx       # List users, change roles
+```
+
+### 1.2 Package Dependencies
+
+```json
+{
+  "name": "ai-weekly-synth-frontend",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "solid-js": "^1.9.0",
+    "@solidjs/router": "^0.15.0",
+    "lucide-solid": "^0.475.0",
+    "date-fns": "^4.1.0",
+    "jspdf": "^2.5.2",
+    "jspdf-autotable": "^3.8.4"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.0",
+    "vite": "^6.2.0",
+    "vite-plugin-solid": "^2.11.0",
+    "@tailwindcss/vite": "^4.1.0",
+    "tailwindcss": "^4.1.0",
+    "vitest": "^3.0.0",
+    "@solidjs/testing-library": "^0.8.0",
+    "@testing-library/jest-dom": "^6.6.0",
+    "jsdom": "^25.0.0"
+  }
+}
+```
+
+**Dependency justifications:**
+
+| Package | Why |
+|---|---|
+| `solid-js` | Core UI framework (per project decisions) |
+| `@solidjs/router` | Official SolidJS router with nested routes, guards, lazy loading |
+| `lucide-solid` | SolidJS-specific icon library -- same icon set as current `lucide-react`, preserves visual continuity |
+| `date-fns` | Framework-agnostic date formatting. Reuses current French locale formatting patterns |
+| `jspdf` + `jspdf-autotable` | Client-side PDF generation for synthesis export. No server round-trip needed |
+| `vite-plugin-solid` | Vite plugin for SolidJS JSX compilation |
+| `@tailwindcss/vite` | Tailwind CSS v4 Vite integration (replaces PostCSS plugin) |
+| `@solidjs/testing-library` | Official testing utilities for SolidJS components |
+| `vitest` | Vite-native test runner, zero config with Vite projects |
+
+**Notable exclusions:**
+- No `@google/genai` -- LLM calls move to the Rust backend.
+- No `firebase` -- replaced by REST API + session cookies.
+- No `react`, `react-dom`, `react-router-dom` -- replaced by SolidJS equivalents.
+- No `turnstile-react` or similar -- Cloudflare Turnstile is loaded via script tag and used imperatively.
+- No state management library (e.g., zustand) -- SolidJS signals and stores are sufficient.
+
+### 1.3 Vite Configuration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import solid from 'vite-plugin-solid';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [
+    solid(),
+    tailwindcss(),
+  ],
+  server: {
+    port: 3000,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:8080',
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    target: 'esnext',
+    outDir: 'dist',
+  },
+});
+```
+
+**Key points:**
+- `vite-plugin-solid` handles SolidJS JSX transformation (converts JSX to `createComponent` / `template` calls).
+- `@tailwindcss/vite` replaces the old PostCSS-based Tailwind pipeline.
+- Dev proxy maps `/api/*` to the Rust backend at `localhost:8080`, avoiding CORS issues during development.
+- Production: the frontend is served as static files by the Rust backend (or an nginx container in Docker Compose).
+
+### 1.4 TypeScript Configuration
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules"]
+}
+```
+
+**Critical SolidJS setting:** `"jsxImportSource": "solid-js"` tells TypeScript to use SolidJS's JSX types instead of React's. This ensures `class` (not `className`), SolidJS event types, and SolidJS component return types.
+
+---
+
+## 2. Component Architecture
+
+### 2.1 Layout Components
+
+#### `src/App.tsx` -- Root Component
+
+**Purpose:** Wire up providers (Auth, Toast, i18n) and the router. Replaces the current `App.tsx` which nests `AuthProvider > Router > Routes`.
+
+**SolidJS pattern:** `Router` from `@solidjs/router` wraps the entire app. Providers are nested above the router.
+
+```typescript
+// src/App.tsx
+import { Component } from 'solid-js';
+import { Router, Route } from '@solidjs/router';
+import { AuthProvider } from '~/context/AuthContext';
+import { ToastProvider } from '~/context/ToastContext';
+import { I18nProvider } from '~/i18n';
+
+// Lazy-loaded pages
+import { lazy } from 'solid-js';
+const Home = lazy(() => import('~/pages/Home'));
+const Login = lazy(() => import('~/pages/auth/Login'));
+const Register = lazy(() => import('~/pages/auth/Register'));
+const MagicLinkVerify = lazy(() => import('~/pages/auth/MagicLinkVerify'));
+const GenerateSynthesis = lazy(() => import('~/pages/GenerateSynthesis'));
+const SynthesisDetail = lazy(() => import('~/pages/SynthesisDetail'));
+const Sources = lazy(() => import('~/pages/Sources'));
+const Settings = lazy(() => import('~/pages/Settings'));
+const ProviderCatalog = lazy(() => import('~/pages/admin/ProviderCatalog'));
+const RateLimitConfig = lazy(() => import('~/pages/admin/RateLimitConfig'));
+const UserManagement = lazy(() => import('~/pages/admin/UserManagement'));
+
+const App: Component = () => {
+  return (
+    <I18nProvider locale="fr">
+      <ToastProvider>
+        <AuthProvider>
+          <Router>
+            {/* Public routes */}
+            <Route path="/login" component={Login} />
+            <Route path="/register" component={Register} />
+            <Route path="/auth/verify" component={MagicLinkVerify} />
+
+            {/* Protected routes wrapped in AppShell */}
+            <Route path="/" component={ProtectedAppShell}>
+              <Route path="/" component={Home} />
+              <Route path="/generate" component={GenerateSynthesis} />
+              <Route path="/synthesis/:id" component={SynthesisDetail} />
+              <Route path="/sources" component={Sources} />
+              <Route path="/settings" component={Settings} />
+            </Route>
+
+            {/* Admin routes wrapped in AdminLayout */}
+            <Route path="/admin" component={ProtectedAdminShell}>
+              <Route path="/providers" component={ProviderCatalog} />
+              <Route path="/rate-limits" component={RateLimitConfig} />
+              <Route path="/users" component={UserManagement} />
+            </Route>
+          </Router>
+        </AuthProvider>
+      </ToastProvider>
+    </I18nProvider>
+  );
+};
+
+export default App;
+```
+
+**React pattern replaced:** `BrowserRouter > Routes > Route` with per-route `<ProtectedRoute><Layout>` wrappers. SolidJS uses nested `<Route>` with layout components directly in the hierarchy.
+
+---
+
+#### `src/components/layout/AppShell.tsx` -- Main Layout
+
+**Purpose:** Wraps all authenticated (non-admin) pages. Renders Navbar + main content area.
+
+**Props/Signals:**
+- Reads `user` from `AuthContext`
+- Reads current route from `useLocation()` for active nav highlighting
+- `mobileMenuOpen: Signal<boolean>` for hamburger toggle
+
+**SolidJS patterns:** `<Show>` for conditional rendering, `children` via `props.children` (not `{children}` destructure -- SolidJS requires `props.children` to maintain reactivity).
+
+```typescript
+import { Component, Show, createSignal } from 'solid-js';
+import { useAuth } from '~/context/AuthContext';
+import Navbar from './Navbar';
+import MobileMenu from './MobileMenu';
+
+const AppShell: Component = (props) => {
+  const { user } = useAuth();
+  const [mobileMenuOpen, setMobileMenuOpen] = createSignal(false);
+
+  return (
+    <div class="min-h-screen bg-gray-50">
+      <Navbar
+        user={user()}
+        onToggleMobile={() => setMobileMenuOpen(!mobileMenuOpen())}
+      />
+      <Show when={mobileMenuOpen()}>
+        <MobileMenu onClose={() => setMobileMenuOpen(false)} />
+      </Show>
+      <main>
+        {props.children}
+      </main>
+    </div>
+  );
+};
+```
+
+**Key SolidJS difference:** In React, `{children}` is destructured from props. In SolidJS, always access as `props.children` to preserve reactivity tracking. Destructuring breaks the reactive subscription.
+
+---
+
+#### `src/components/layout/Navbar.tsx` -- Navigation Bar
+
+**Purpose:** Top navigation bar with logo, nav links, user info, settings icon, admin dropdown (if admin), logout. Includes mobile hamburger button.
+
+**Props:**
+```typescript
+interface NavbarProps {
+  user: User | null;
+  onToggleMobile: () => void;
+}
+```
+
+**SolidJS patterns:**
+- `useLocation()` from `@solidjs/router` for active route detection
+- `<A>` component from `@solidjs/router` (replaces React Router's `<Link>`)
+- `<Show when={user()?.role === 'admin'}>` for admin nav items
+- `class` attribute (not `className`)
+
+**Active route indicator:** Compute active class with:
+```typescript
+const location = useLocation();
+const isActive = (path: string) =>
+  location.pathname === path
+    ? 'border-indigo-500 text-gray-900'
+    : 'border-transparent text-gray-500 hover:border-gray-300 hover:text-gray-700';
+```
+
+**React pattern replaced:** Current `Layout` component in `App.tsx`. The current app has no active route indicator and no mobile menu -- both are added in this rewrite.
+
+---
+
+#### `src/components/layout/MobileMenu.tsx` -- Mobile Navigation
+
+**Purpose:** Slide-out mobile menu (hamburger), fixing the current app's missing mobile navigation. Renders nav links + user info + logout.
+
+**Props:**
+```typescript
+interface MobileMenuProps {
+  onClose: () => void;
+}
+```
+
+**SolidJS patterns:** `onCleanup` to add/remove click-outside handler. `<For>` to iterate nav items.
+
+---
+
+#### `src/components/layout/AdminLayout.tsx` -- Admin Section Layout
+
+**Purpose:** Layout for `/admin/*` routes. Includes sidebar with links to provider catalog, rate limits, user management. Wraps admin pages.
+
+**SolidJS patterns:** Nested `<Route>` children via `props.children`. Active sidebar link via `useLocation()`.
+
+---
+
+#### `src/components/auth/ProtectedRoute.tsx` -- Route Guard
+
+**Purpose:** Checks auth state. If unauthenticated, redirects to `/login`. If loading, shows full-page spinner.
+
+**SolidJS patterns:**
+- Reads `user` and `loading` from `AuthContext`
+- Uses `<Show>` with `fallback` for the loading state
+- Uses `<Navigate>` from `@solidjs/router` for redirect
+
+```typescript
+import { Component, Show } from 'solid-js';
+import { Navigate } from '@solidjs/router';
+import { useAuth } from '~/context/AuthContext';
+import Spinner from '~/components/ui/Spinner';
+
+const ProtectedRoute: Component = (props) => {
+  const { user, loading } = useAuth();
+
+  return (
+    <Show
+      when={!loading()}
+      fallback={<Spinner fullPage />}
+    >
+      <Show
+        when={user()}
+        fallback={<Navigate href="/login" />}
+      >
+        {props.children}
+      </Show>
+    </Show>
+  );
+};
+```
+
+**React pattern replaced:** Current `ProtectedRoute` uses `if (loading) return ...` and `if (!user) return <Navigate>`. SolidJS uses nested `<Show>` components instead of early returns.
+
+---
+
+### 2.2 Auth Pages
+
+#### `src/pages/auth/Login.tsx` -- Magic Link Login
+
+**Purpose:** Email field + Cloudflare Turnstile captcha + submit to request magic link. Shows confirmation message after submit with resend button.
+
+**Signals:**
+```typescript
+const [email, setEmail] = createSignal('');
+const [turnstileToken, setTurnstileToken] = createSignal<string | null>(null);
+const [submitted, setSubmitted] = createSignal(false);
+const [loading, setLoading] = createSignal(false);
+const [error, setError] = createSignal<string | null>(null);
+const [resendCooldown, setResendCooldown] = createSignal(0);
+```
+
+**API calls:**
+- `POST /api/v1/auth/login` with `{ email, captcha_token }`
+
+**SolidJS patterns:**
+- `onMount` to load the Turnstile script if not already loaded
+- `createEffect` to manage resend cooldown timer (countdown from 60s)
+- `onCleanup` to clear the timer interval
+- `<Show when={submitted()}>` to toggle between form view and confirmation view
+
+**Turnstile integration:** Load via `<script>` tag. Render into a `<div ref={turnstileRef}>` using `window.turnstile.render()`. Callback sets the `turnstileToken` signal.
+
+```typescript
+let turnstileRef: HTMLDivElement | undefined;
+
+onMount(() => {
+  if (!document.getElementById('cf-turnstile-script')) {
+    const script = document.createElement('script');
+    script.id = 'cf-turnstile-script';
+    script.src = 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit';
+    script.onload = () => renderTurnstile();
+    document.head.appendChild(script);
+  } else {
+    renderTurnstile();
+  }
+});
+
+const renderTurnstile = () => {
+  if (turnstileRef && window.turnstile) {
+    window.turnstile.render(turnstileRef, {
+      sitekey: import.meta.env.VITE_TURNSTILE_SITE_KEY,
+      callback: (token: string) => setTurnstileToken(token),
+    });
+  }
+};
+```
+
+**React pattern replaced:** Current `Login` component uses a single Google sign-in button. The new version is a form-based flow with captcha.
+
+---
+
+#### `src/pages/auth/Register.tsx` -- Account Creation
+
+**Purpose:** Email + optional display name + Turnstile captcha. Submit sends registration request, then shows confirmation to check email.
+
+**Signals:** Similar to Login, plus `displayName: Signal<string>`.
+
+**API calls:**
+- `POST /api/v1/auth/register` with `{ email, display_name, captcha_token }`
+
+**SolidJS patterns:** Same as Login. Shared Turnstile loading logic can be extracted to `lib/turnstile.ts` helper.
+
+---
+
+#### `src/pages/auth/MagicLinkVerify.tsx` -- Token Verification
+
+**Purpose:** User arrives via magic link email (`/auth/verify?token=...`). Extracts token from URL, calls backend to verify, then redirects to Home on success.
+
+**Signals:**
+```typescript
+const [status, setStatus] = createSignal<'verifying' | 'success' | 'error'>('verifying');
+const [errorMessage, setErrorMessage] = createSignal('');
+```
+
+**API calls:**
+- `GET /api/v1/auth/verify?token=<token>` -- sets session cookie in response
+
+**SolidJS patterns:**
+- `useSearchParams()` from `@solidjs/router` to extract the `token` query parameter
+- `onMount` to trigger the verification call immediately
+- `useNavigate()` to redirect to `/` on success after a brief delay
+
+```typescript
+const MagicLinkVerify: Component = () => {
+  const [searchParams] = useSearchParams();
+  const navigate = useNavigate();
+  const [status, setStatus] = createSignal<'verifying' | 'success' | 'error'>('verifying');
+
+  onMount(async () => {
+    const token = searchParams.token;
+    if (!token) {
+      setStatus('error');
+      return;
+    }
+    try {
+      await authApi.verify(token as string);
+      setStatus('success');
+      setTimeout(() => navigate('/', { replace: true }), 1500);
+    } catch (e) {
+      setStatus('error');
+    }
+  });
+
+  return (
+    <div class="min-h-screen flex items-center justify-center bg-gray-50">
+      <Switch>
+        <Match when={status() === 'verifying'}>
+          <Spinner fullPage />
+        </Match>
+        <Match when={status() === 'success'}>
+          <SuccessBanner message={t('auth.verifySuccess')} />
+        </Match>
+        <Match when={status() === 'error'}>
+          <ErrorBanner message={t('auth.verifyError')} />
+        </Match>
+      </Switch>
+    </div>
+  );
+};
+```
+
+---
+
+### 2.3 Main Pages
+
+#### `src/pages/Home.tsx` -- Synthesis List (Dashboard)
+
+**Purpose:** Display a grid of synthesis cards, ordered by creation date. Show "New Synthesis" button. Show in-progress banner if a generation is running.
+
+**Signals:**
+```typescript
+const [syntheses] = createResource(fetchSyntheses);
+const [deletingId, setDeletingId] = createSignal<string | null>(null);
+const [activeJob, setActiveJob] = createSignal<GenerationJob | null>(null);
+```
+
+**API calls:**
+- `GET /api/v1/syntheses` via `createResource` for initial load
+- SSE connection for real-time list updates (new synthesis appears, deletion reflects)
+- `DELETE /api/v1/syntheses/:id`
+- Check for in-progress generation jobs on mount
+
+**SolidJS patterns:**
+- `createResource` replaces `useState` + `useEffect` for async data fetching. It provides `.loading`, `.error`, and `.latest` properties.
+- `<For each={syntheses()}>` replaces `{array.map(...)}`. `<For>` is optimized for keyed list rendering without re-creating DOM nodes.
+- `<Show when={syntheses()?.length === 0}>` for empty state.
+- `<Show when={activeJob()}>` for in-progress generation banner.
+- SSE listener via `createEffect` + `onCleanup` to mutate the resource.
+
+```typescript
+const Home: Component = () => {
+  const { t } = useI18n();
+  const [syntheses, { mutate, refetch }] = createResource(
+    () => synthesesApi.list()
+  );
+  const [deletingId, setDeletingId] = createSignal<string | null>(null);
+
+  // SSE for real-time updates
+  createEffect(() => {
+    const eventSource = createSSEConnection('/api/v1/syntheses/events');
+    eventSource.on('created', (data) => {
+      mutate((prev) => prev ? [data, ...prev] : [data]);
+    });
+    eventSource.on('deleted', (data) => {
+      mutate((prev) => prev?.filter((s) => s.id !== data.id) ?? []);
+    });
+    onCleanup(() => eventSource.close());
+  });
+
+  const handleDelete = async (id: string) => {
+    // Show confirm dialog, then call API
+    await synthesesApi.delete(id);
+    mutate((prev) => prev?.filter((s) => s.id !== id) ?? []);
+  };
+
+  return (
+    <div class="max-w-5xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
+      {/* Header with title + New Synthesis button */}
+      {/* In-progress banner */}
+      <Show when={!syntheses.loading} fallback={<Spinner />}>
+        <Show
+          when={syntheses()?.length}
+          fallback={<EmptyState ... />}
+        >
+          <div class="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+            <For each={syntheses()}>
+              {(synth) => (
+                <SynthesisCard
+                  synthesis={synth}
+                  isDeleting={deletingId() === synth.id}
+                  onDelete={() => handleDelete(synth.id)}
+                />
+              )}
+            </For>
+          </div>
+        </Show>
+      </Show>
+    </div>
+  );
+};
+```
+
+**React pattern replaced:**
+- `useState` + `useEffect` with Firestore `onSnapshot` --> `createResource` + SSE via `createEffect`
+- `{array.map()}` --> `<For each={...}>`
+- `className` --> `class`
+
+---
+
+#### `src/pages/GenerateSynthesis.tsx` -- Generation with SSE Progress
+
+**Purpose:** Show generation parameters (from user settings). Trigger generation. Display real-time SSE progress (step list + progress bar). Handle navigation-away (generation continues in background).
+
+**Signals:**
+```typescript
+const [settings] = createResource(settingsApi.get);
+const [jobId, setJobId] = createSignal<string | null>(null);
+const [progress, setProgress] = createSignal<SSEProgressEvent | null>(null);
+const [status, setStatus] = createSignal<'idle' | 'generating' | 'complete' | 'error'>('idle');
+const [errorMessage, setErrorMessage] = createSignal<string | null>(null);
+```
+
+**API calls:**
+- `GET /api/v1/settings` via `createResource` (to show "theme" and "maxAgeDays" in the trigger confirmation text)
+- `POST /api/v1/syntheses/generate` to start generation (returns `job_id`)
+- SSE: `GET /api/v1/syntheses/generate/:job_id/progress` for progress events
+
+**SolidJS patterns:**
+- `createEffect` to open SSE connection when `jobId()` is set
+- `onCleanup` to close SSE on unmount (but generation continues server-side)
+- `<Switch>/<Match>` for status-based rendering (idle/generating/complete/error)
+- `<Show>` for conditional progress display
+
+```typescript
+const handleGenerate = async () => {
+  setStatus('generating');
+  try {
+    const { job_id } = await synthesesApi.generate();
+    setJobId(job_id);
+  } catch (e) {
+    setStatus('error');
+    setErrorMessage(parseApiError(e));
+  }
+};
+
+// SSE progress tracking
+createEffect(() => {
+  const id = jobId();
+  if (!id) return;
+
+  const sse = createSSEConnection(`/api/v1/syntheses/generate/${id}/progress`);
+  sse.on('progress', (data) => setProgress(data));
+  sse.on('complete', (data) => {
+    setStatus('complete');
+    setTimeout(() => navigate(`/synthesis/${data.synthesis_id}`), 1500);
+  });
+  sse.on('error', (data) => {
+    setStatus('error');
+    setErrorMessage(data.message);
+  });
+  onCleanup(() => sse.close());
+});
+```
+
+**Progress UI:** The `SSEProgressIndicator` component renders a progress bar and step list:
+```typescript
+// SSEProgressIndicator props
+interface SSEProgressIndicatorProps {
+  progress: SSEProgressEvent | null;
+}
+
+// SSEProgressEvent type
+interface SSEProgressEvent {
+  step: 'search' | 'scraping' | 'rewrite' | 'saving';
+  message: string;
+  percent: number;
+}
+```
+
+**React pattern replaced:** Current `GenerateSynthesis` calls `generateWeeklySynthesis()` directly from the browser (Gemini API). The new version triggers a backend job and monitors via SSE. The single spinner is replaced by a multi-step progress indicator.
+
+---
+
+#### `src/pages/SynthesisDetail.tsx` -- Reading View + Email + Export + Delete
+
+**Purpose:** Display full synthesis (sections with news items). Provide email sending, PDF export, Markdown export, and deletion.
+
+**Signals:**
+```typescript
+const [synthesis] = createResource(
+  () => params.id,
+  (id) => synthesesApi.get(id)
+);
+const [email, setEmail] = createSignal('');
+const [sendingEmail, setSendingEmail] = createSignal(false);
+const [emailSuccess, setEmailSuccess] = createSignal(false);
+const [emailError, setEmailError] = createSignal<string | null>(null);
+const [showDeleteConfirm, setShowDeleteConfirm] = createSignal(false);
+const [isDeleting, setIsDeleting] = createSignal(false);
+```
+
+**API calls:**
+- `GET /api/v1/syntheses/:id` via `createResource` with `params.id` as source
+- `POST /api/v1/syntheses/:id/email` with `{ recipient_email }`
+- `DELETE /api/v1/syntheses/:id`
+
+**SolidJS patterns:**
+- `createResource` with a source signal (`params.id`) -- re-fetches when the param changes
+- `useParams()` from `@solidjs/router`
+- `<For each={synthesis()?.sections}>` to render sections
+- `<Show when={showDeleteConfirm()}>` for delete confirmation (standardized `ConfirmDialog`)
+
+**Export actions:**
+- "Export PDF" button calls `generatePdf(synthesis())` from `lib/export.ts`
+- "Export Markdown" button calls `generateMarkdown(synthesis())` from `lib/export.ts`
+- Email pre-fills with user's own email from `AuthContext`
+
+**React pattern replaced:**
+- `useParams<{ id: string }>()` --> `useParams()` (SolidJS version returns a reactive proxy, not a plain object)
+- `useEffect([id])` with Firestore `onSnapshot` --> `createResource` with `params.id` as reactive source
+- Gmail API email sending --> `POST /api/v1/syntheses/:id/email` backend call
+- Legacy data fallback rendering removed (per decisions: clean `sections[]` only)
+
+---
+
+#### `src/pages/Sources.tsx` -- Sources Management
+
+**Purpose:** CRUD for custom sources. Single add form, CSV import/export, bulk text import. List of existing sources with delete.
+
+**Signals:**
+```typescript
+const [sources, { mutate, refetch }] = createResource(sourcesApi.list);
+const [newTitle, setNewTitle] = createSignal('');
+const [newUrl, setNewUrl] = createSignal('');
+const [adding, setAdding] = createSignal(false);
+const [bulkText, setBulkText] = createSignal('');
+const [importing, setImporting] = createSignal(false);
+const [importError, setImportError] = createSignal<string | null>(null);
+```
+
+**API calls:**
+- `GET /api/v1/sources` via `createResource`
+- `POST /api/v1/sources` to add a single source
+- `DELETE /api/v1/sources/:id` to delete
+- `POST /api/v1/sources/bulk` for bulk import (JSON array)
+- `POST /api/v1/sources/import-csv` for CSV file import (multipart)
+- `GET /api/v1/sources/export-csv` for CSV download
+
+**SolidJS patterns:**
+- `<For each={sources()}>` for the source list
+- Optimistic UI: `mutate()` to add/remove from local state immediately, `refetch()` on error to resync
+- `<Show when={importError()}>` for error display
+- Form `onSubmit` handlers with `preventDefault()`
+
+**Deletion pattern change:** Current app has no delete confirmation on sources. The new version uses the standardized `ConfirmDialog` component for consistency.
+
+**React pattern replaced:**
+- `useEffect` with Firestore `onSnapshot` --> `createResource` with SSE for real-time (or refetch after mutations)
+- `e: React.FormEvent` --> native `SubmitEvent` (SolidJS does not have synthetic events)
+- `e: React.ChangeEvent<HTMLInputElement>` --> native `Event` with `(e.target as HTMLInputElement).files`
+
+---
+
+#### `src/pages/Settings.tsx` -- User Settings
+
+**Purpose:** Configure theme, search window, categories (dynamic list), AI provider/model/API key, search agent behavior. Import/export JSON.
+
+**Signals:**
+```typescript
+const [settings, { mutate }] = createResource(settingsApi.get);
+const [localSettings, setLocalSettings] = createSignal<UserSettings | null>(null);
+const [saving, setSaving] = createSignal(false);
+const [message, setMessage] = createSignal<{ type: 'success' | 'error'; text: string } | null>(null);
+const [providers] = createResource(configApi.getProviders);
+```
+
+**API calls:**
+- `GET /api/v1/settings` via `createResource`
+- `PUT /api/v1/settings` to save
+- `GET /api/v1/settings/export` for JSON download
+- `POST /api/v1/settings/import` for JSON upload
+- `GET /api/v1/config/providers` to get available providers and models (admin-curated list)
+
+**SolidJS patterns:**
+- `createEffect` to initialize `localSettings` from `settings()` when loaded
+- `createStore` for form state (deep nested updates for categories array)
+- `<For each={localSettings()?.categories}>` for the dynamic category list
+- `<Show when={providers()?.length > 1}>` to conditionally show provider dropdown
+- Cascading dropdowns: when provider changes, model list updates
+
+**New fields compared to current app:**
+- **Provider dropdown:** `<Select>` populated from `GET /api/v1/config/providers`. Hidden if only one provider configured.
+- **Model dropdown:** Dynamically populated based on selected provider.
+- **API Key field:** Masked input with show/hide toggle. User provides their own key.
+
+**Category management:**
+```typescript
+const [settingsStore, setSettingsStore] = createStore<UserSettings>(DEFAULT_SETTINGS);
+
+// Add category
+const addCategory = () => {
+  if (settingsStore.categories.length >= 20) return;
+  setSettingsStore('categories', settingsStore.categories.length, t('settings.newCategory'));
+};
+
+// Remove category
+const removeCategory = (index: number) => {
+  if (settingsStore.categories.length <= 1) return;
+  setSettingsStore('categories', (cats) => cats.filter((_, i) => i !== index));
+};
+
+// Update category
+const updateCategory = (index: number, value: string) => {
+  setSettingsStore('categories', index, value);
+};
+```
+
+**React pattern replaced:**
+- `useState<AppSettings>` with spread-based updates --> `createStore<UserSettings>` with path-based updates
+- Hardcoded AI model `<option>` values --> dynamic model list from backend `GET /api/v1/config/providers`
+- No provider selection --> two-level provider + model selection
+
+---
+
+### 2.4 Admin Pages
+
+#### `src/pages/admin/ProviderCatalog.tsx` -- LLM Provider Management
+
+**Purpose:** Admin configures available LLM providers. For each provider: name, list of available models, default model, enabled/disabled toggle.
+
+Note: Per decisions, users bring their own API keys. The admin only curates which providers/models are available.
+
+**Signals:**
+```typescript
+const [providers, { refetch }] = createResource(adminApi.getProviders);
+const [editingProvider, setEditingProvider] = createSignal<ProviderConfig | null>(null);
+const [saving, setSaving] = createSignal(false);
+```
+
+**API calls:**
+- `GET /api/v1/admin/providers`
+- `POST /api/v1/admin/providers` (add/update)
+- `DELETE /api/v1/admin/providers/:id`
+
+**SolidJS patterns:**
+- `<For each={providers()}>` for provider cards/tabs
+- `<Show when={editingProvider()}>` for edit form
+- `createStore` for the edit form state (nested model array)
+
+---
+
+#### `src/pages/admin/RateLimitConfig.tsx` -- Rate Limit Configuration
+
+**Purpose:** Configure global rate limits per provider (requests/minute). Show current defaults.
+
+**Signals:**
+```typescript
+const [rateLimits, { refetch }] = createResource(adminApi.getRateLimits);
+const [localLimits, setLocalLimits] = createStore<Record<string, RateLimitConfig>>({});
+const [saving, setSaving] = createSignal(false);
+```
+
+**API calls:**
+- `GET /api/v1/admin/rate-limits`
+- `PUT /api/v1/admin/rate-limits/:provider_id`
+
+---
+
+#### `src/pages/admin/UserManagement.tsx` -- User List and Roles
+
+**Purpose:** List all registered users. Allow admin to promote/demote user roles.
+
+**Signals:**
+```typescript
+const [users] = createResource(adminApi.listUsers);
+```
+
+**API calls:**
+- `GET /api/v1/admin/users`
+- `PUT /api/v1/admin/users/:id/role`
+
+---
+
+### 2.5 Shared UI Components
+
+#### `src/components/ui/Button.tsx`
+
+```typescript
+import { Component, JSX, Show, splitProps } from 'solid-js';
+import { Loader2 } from 'lucide-solid';
+
+interface ButtonProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'danger';
+  loading?: boolean;
+  icon?: Component<{ class?: string }>;
+}
+
+const variantClasses = {
+  primary: 'text-white bg-indigo-600 hover:bg-indigo-700 border-transparent focus:ring-indigo-500',
+  secondary: 'text-gray-700 bg-white hover:bg-gray-50 border-gray-300 focus:ring-indigo-500',
+  danger: 'text-white bg-red-600 hover:bg-red-700 border-transparent focus:ring-red-500',
+};
+
+const Button: Component<ButtonProps> = (allProps) => {
+  const [props, rest] = splitProps(allProps, ['variant', 'loading', 'icon', 'children']);
+  const variant = () => props.variant ?? 'primary';
+
+  return (
+    <button
+      {...rest}
+      disabled={rest.disabled || props.loading}
+      class={`inline-flex items-center justify-center px-4 py-2 border shadow-sm text-sm font-medium rounded-md focus:outline-none focus:ring-2 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed ${variantClasses[variant()]} ${rest.class ?? ''}`}
+    >
+      <Show when={props.loading} fallback={
+        <Show when={props.icon}>
+          {(Icon) => <Icon class="-ml-1 mr-2 h-5 w-5" />}
+        </Show>
+      }>
+        <Loader2 class="animate-spin -ml-1 mr-2 h-5 w-5" />
+      </Show>
+      {props.children}
+    </button>
+  );
+};
+```
+
+**SolidJS pattern:** `splitProps` separates custom props from native HTML attributes, allowing safe spreading of `rest` onto the DOM element. This replaces the React pattern of destructuring plus `...rest`.
+
+---
+
+#### `src/components/ui/ConfirmDialog.tsx`
+
+```typescript
+interface ConfirmDialogProps {
+  open: boolean;
+  title: string;
+  message: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  variant?: 'danger' | 'warning';
+  loading?: boolean;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+```
+
+**SolidJS patterns:**
+- `<Show when={props.open}>` to mount/unmount
+- `<Portal>` from `solid-js/web` to render at document root (proper overlay stacking)
+- Focus trap and keyboard handling via `createEffect` + `onCleanup`
+
+---
+
+#### `src/components/ui/Spinner.tsx`
+
+```typescript
+interface SpinnerProps {
+  fullPage?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+}
+```
+
+Preserves the current indigo spinner style: `animate-spin rounded-full border-b-2 border-indigo-600`.
+
+---
+
+#### `src/components/ui/SSEProgressIndicator.tsx`
+
+```typescript
+interface SSEProgressIndicatorProps {
+  progress: SSEProgressEvent | null;
+  steps: Array<{ key: string; label: string }>;
+}
+```
+
+Renders:
+- A progress bar (0-100%) with indigo fill
+- A step list with status indicators (done checkmark, in-progress spinner, pending gray)
+- Current step description text
+
+---
+
+#### `src/components/ui/Toast.tsx` and `src/context/ToastContext.tsx`
+
+Global toast notification system. Replaces the scattered success/error inline messages with a unified notification system.
+
+```typescript
+// Toast types
+interface Toast {
+  id: string;
+  type: 'success' | 'error' | 'info';
+  message: string;
+  duration?: number; // ms, default 5000
+}
+
+// Context
+interface ToastContextType {
+  addToast: (toast: Omit<Toast, 'id'>) => void;
+  removeToast: (id: string) => void;
+}
+```
+
+**SolidJS patterns:**
+- `createContext` + `useContext` for global access
+- `createStore<Toast[]>` for the toast queue
+- `<For each={toasts}>` to render active toasts
+- `<Portal>` to render at document root (top-right corner)
+- Auto-dismiss via `setTimeout` in `createEffect`, cleaned up with `onCleanup`
+
+---
+
+#### `src/components/ui/ErrorBanner.tsx` and `src/components/ui/SuccessBanner.tsx`
+
+Inline feedback components preserving the current visual style:
+- Error: red background, left border, AlertCircle icon
+- Success: green background, left border, CheckCircle2 icon
+
+```typescript
+interface BannerProps {
+  message: string;
+}
+```
+
+---
+
+#### `src/components/ui/EmptyState.tsx`
+
+Reusable empty state placeholder with icon, title, description, and optional CTA button.
+
+```typescript
+interface EmptyStateProps {
+  icon: Component;
+  title: string;
+  description: string;
+  actionLabel?: string;
+  actionHref?: string;
+  onAction?: () => void;
+}
+```
+
+---
+
+#### `src/components/synthesis/SynthesisCard.tsx`
+
+Extracted from current `Home.tsx` inline card rendering. Displays week badge, creation date, first section preview, "read" link, delete button.
+
+```typescript
+interface SynthesisCardProps {
+  synthesis: Synthesis;
+  onDelete: () => void;
+}
+```
+
+---
+
+#### `src/components/synthesis/SynthesisSection.tsx`
+
+Extracted from current `SynthesisDetail.tsx` `Section` component. Renders a section title with border and list of `NewsItemCard`s.
+
+```typescript
+interface SynthesisSectionProps {
+  title: string;
+  items: NewsItem[];
+}
+```
+
+---
+
+#### `src/components/synthesis/NewsItemCard.tsx`
+
+Individual news item: title as external link, summary paragraph.
+
+```typescript
+interface NewsItemCardProps {
+  item: NewsItem;
+}
+```
+
+---
+
+## 3. State Management
+
+### 3.1 Auth State -- `src/context/AuthContext.tsx`
+
+The auth context is the most critical global state. It replaces Firebase's `onAuthStateChanged` with a session check on app load.
+
+```typescript
+import { createContext, useContext, createSignal, onMount, ParentComponent } from 'solid-js';
+import { authApi } from '~/api/auth';
+import type { User } from '~/types/auth';
+
+interface AuthContextType {
+  user: () => User | null;
+  loading: () => boolean;
+  isAdmin: () => boolean;
+  login: (email: string, captchaToken: string) => Promise<void>;
+  register: (email: string, displayName: string, captchaToken: string) => Promise<void>;
+  logout: () => Promise<void>;
+  refreshUser: () => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextType>();
+
+export const AuthProvider: ParentComponent = (props) => {
+  const [user, setUser] = createSignal<User | null>(null);
+  const [loading, setLoading] = createSignal(true);
+
+  const isAdmin = () => user()?.role === 'admin';
+
+  // Check session on app load
+  onMount(async () => {
+    try {
+      const currentUser = await authApi.me();
+      setUser(currentUser);
+    } catch {
+      setUser(null);
+    } finally {
+      setLoading(false);
+    }
+  });
+
+  const login = async (email: string, captchaToken: string) => {
+    await authApi.login({ email, captcha_token: captchaToken });
+    // Does not set user -- magic link flow. User will be set after verify.
+  };
+
+  const register = async (email: string, displayName: string, captchaToken: string) => {
+    await authApi.register({ email, display_name: displayName, captcha_token: captchaToken });
+  };
+
+  const logout = async () => {
+    await authApi.logout();
+    setUser(null);
+  };
+
+  const refreshUser = async () => {
+    try {
+      const currentUser = await authApi.me();
+      setUser(currentUser);
+    } catch {
+      setUser(null);
+    }
+  };
+
+  return (
+    <AuthContext.Provider value={{ user, loading, isAdmin, login, register, logout, refreshUser }}>
+      {props.children}
+    </AuthContext.Provider>
+  );
+};
+
+export const useAuth = (): AuthContextType => {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuth must be used within AuthProvider');
+  return ctx;
+};
+```
+
+**Key difference from React:** The `user` and `loading` are accessor functions (SolidJS signals), not plain values. Consumers call `user()` and `loading()` to read them. This enables fine-grained reactivity -- only the specific DOM nodes that read `user()` will update when it changes, not the entire component tree.
+
+### 3.2 When to Use Each State Primitive
+
+| Primitive | When to use | Example |
+|---|---|---|
+| `createSignal<T>` | Simple, local component state. Single value. | `const [email, setEmail] = createSignal('')` |
+| `createStore<T>` | Complex, nested objects or arrays. When you need path-based updates. | Settings form, categories list, admin provider config |
+| `createResource<T>` | Async data fetching tied to a reactive source. Provides `.loading`, `.error`. | API calls: fetch syntheses, fetch settings, etc. |
+| `createContext` | Global state shared across many components. Rarely changes (auth, i18n, theme). | AuthContext, ToastContext, I18nContext |
+| `createEffect` | Side effects that react to signal changes. Replaces `useEffect`. | SSE connections, timers, DOM manipulation |
+| `createMemo` | Derived computed values (cached). | Filtered/sorted lists, computed display strings |
+
+### 3.3 Global vs. Local State
+
+**Global (via Context):**
+- Auth state (user, loading, isAdmin) -- needed in Navbar, ProtectedRoute, every page
+- Toast notifications -- triggered from any component
+- i18n translations -- accessed in every component
+
+**Local (via createSignal/createStore):**
+- Form state (Settings, Sources add form, Login form)
+- Page-specific loading/error state
+- UI state (mobileMenuOpen, showDeleteConfirm, deletingId)
+- SSE progress state (only relevant to GenerateSynthesis page)
+
+### 3.4 API Client Abstraction -- `src/api/client.ts`
+
+A centralized fetch wrapper that handles session cookies, CSRF headers, error parsing, and 401 redirect.
+
+```typescript
+// src/api/client.ts
+
+const API_BASE = '/api/v1';
+
+interface ApiError {
+  status: number;
+  message: string;
+  fieldErrors?: Record<string, string>;
+}
+
+class ApiClient {
+  private async request<T>(
+    method: string,
+    path: string,
+    options?: {
+      body?: unknown;
+      headers?: Record<string, string>;
+      signal?: AbortSignal;
+    }
+  ): Promise<T> {
+    const url = `${API_BASE}${path}`;
+    const headers: Record<string, string> = {
+      'X-Requested-With': 'XMLHttpRequest', // CSRF protection
+      ...options?.headers,
+    };
+
+    if (options?.body && !(options.body instanceof FormData)) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: options?.body instanceof FormData
+        ? options.body
+        : options?.body
+        ? JSON.stringify(options.body)
+        : undefined,
+      credentials: 'same-origin', // Send session cookie
+      signal: options?.signal,
+    });
+
+    if (!response.ok) {
+      if (response.status === 401) {
+        // Session expired -- redirect to login
+        window.location.href = '/login';
+        throw new Error('Session expired');
+      }
+      const errorBody = await response.json().catch(() => ({ error: 'Unknown error' }));
+      const apiError: ApiError = {
+        status: response.status,
+        message: errorBody.error || `HTTP ${response.status}`,
+        fieldErrors: errorBody.field_errors,
+      };
+      throw apiError;
+    }
+
+    // Handle empty responses (204 No Content)
+    if (response.status === 204) {
+      return undefined as T;
+    }
+
+    return response.json();
+  }
+
+  get<T>(path: string, signal?: AbortSignal): Promise<T> {
+    return this.request<T>('GET', path, { signal });
+  }
+
+  post<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>('POST', path, { body });
+  }
+
+  put<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>('PUT', path, { body });
+  }
+
+  delete<T>(path: string): Promise<T> {
+    return this.request<T>('DELETE', path);
+  }
+
+  upload<T>(path: string, formData: FormData): Promise<T> {
+    return this.request<T>('POST', path, { body: formData });
+  }
+
+  downloadBlob(path: string): Promise<Blob> {
+    return fetch(`${API_BASE}${path}`, {
+      headers: { 'X-Requested-With': 'XMLHttpRequest' },
+      credentials: 'same-origin',
+    }).then((r) => {
+      if (!r.ok) throw new Error(`Download failed: ${r.status}`);
+      return r.blob();
+    });
+  }
+}
+
+export const api = new ApiClient();
+```
+
+**CSRF protection:** The `X-Requested-With: XMLHttpRequest` header is sent with every request. Combined with `SameSite=Lax` cookies, this prevents CSRF attacks (per the project's decision to use the Architect's simpler CSRF approach).
+
+**401 handling:** On any 401 response, the client redirects to `/login`. This handles session expiry gracefully.
+
+**Domain-specific API modules** (e.g., `src/api/syntheses.ts`) wrap the client:
+
+```typescript
+// src/api/syntheses.ts
+import { api } from './client';
+import type { Synthesis, GenerateResponse } from '~/types/synthesis';
+
+export const synthesesApi = {
+  list: () => api.get<Synthesis[]>('/syntheses'),
+  get: (id: string) => api.get<Synthesis>(`/syntheses/${id}`),
+  generate: () => api.post<GenerateResponse>('/syntheses/generate'),
+  delete: (id: string) => api.delete(`/syntheses/${id}`),
+  sendEmail: (id: string, recipientEmail: string) =>
+    api.post(`/syntheses/${id}/email`, { recipient_email: recipientEmail }),
+};
+```
+
+---
+
+## 4. Routing
+
+### 4.1 Router Configuration
+
+Using `@solidjs/router` (file-based or config-based). The configuration is in `App.tsx` (shown in Section 2.1).
+
+### 4.2 Route Definitions
+
+| Path | Component | Guard | Description |
+|---|---|---|---|
+| `/login` | `Login` | Public (redirect to `/` if logged in) | Magic link request |
+| `/register` | `Register` | Public (redirect to `/` if logged in) | Account creation |
+| `/auth/verify` | `MagicLinkVerify` | Public | Token verification from magic link |
+| `/` | `Home` | Authenticated | Synthesis list dashboard |
+| `/generate` | `GenerateSynthesis` | Authenticated | Trigger generation |
+| `/synthesis/:id` | `SynthesisDetail` | Authenticated | Read synthesis detail |
+| `/sources` | `Sources` | Authenticated | Manage custom sources |
+| `/settings` | `Settings` | Authenticated | User settings |
+| `/admin/providers` | `ProviderCatalog` | Admin | LLM provider config |
+| `/admin/rate-limits` | `RateLimitConfig` | Admin | Rate limit settings |
+| `/admin/users` | `UserManagement` | Admin | User management |
+
+### 4.3 Route Guards
+
+**Authenticated guard** (`ProtectedRoute`): Wraps authenticated route groups as a layout. Checks `useAuth().user()`. Redirects to `/login` if null after loading.
+
+**Admin guard** (`ProtectedAdminShell`): Same as authenticated plus checks `useAuth().isAdmin()`. Redirects to `/` if not admin.
+
+```typescript
+// ProtectedAppShell -- authenticated routes layout
+const ProtectedAppShell: Component = (props) => {
+  const { user, loading } = useAuth();
+
+  return (
+    <Show when={!loading()} fallback={<Spinner fullPage />}>
+      <Show when={user()} fallback={<Navigate href="/login" />}>
+        <AppShell>{props.children}</AppShell>
+      </Show>
+    </Show>
+  );
+};
+
+// ProtectedAdminShell -- admin routes layout
+const ProtectedAdminShell: Component = (props) => {
+  const { user, loading, isAdmin } = useAuth();
+
+  return (
+    <Show when={!loading()} fallback={<Spinner fullPage />}>
+      <Show when={user() && isAdmin()} fallback={<Navigate href="/" />}>
+        <AdminLayout>{props.children}</AdminLayout>
+      </Show>
+    </Show>
+  );
+};
+```
+
+### 4.4 Navigation Patterns
+
+**Programmatic navigation:**
+```typescript
+const navigate = useNavigate();
+// After successful generation
+navigate(`/synthesis/${data.synthesis_id}`);
+// After deletion
+navigate('/');
+// After login form submit (no navigation -- user checks email)
+```
+
+**Link components:** Use `<A>` from `@solidjs/router` (not `<Link>`):
+```typescript
+import { A } from '@solidjs/router';
+<A href="/">Syntheses</A>
+<A href={`/synthesis/${synth.id}`}>Lire la synthese</A>
+```
+
+### 4.5 Magic Link Verification Redirect
+
+1. User clicks magic link in email: `https://app.example.com/auth/verify?token=abc123`
+2. `MagicLinkVerify` page loads, extracts `token` from `useSearchParams()`
+3. Calls `GET /api/v1/auth/verify?token=abc123`
+4. Backend verifies token, creates session, sets `Set-Cookie` header in response
+5. Frontend receives success, calls `refreshUser()` on AuthContext to load the user
+6. Navigates to `/` with `replace: true` (replaces history entry so back button does not re-verify)
+
+---
+
+## 5. i18n Architecture
+
+### 5.1 Structure
+
+i18n is implemented as a SolidJS context with typed translation keys and a simple lookup function. No external i18n library is needed for the MVP (French-only), but the structure supports adding languages later.
+
+### 5.2 Translation File Format
+
+```typescript
+// src/i18n/locales/fr.ts
+const fr = {
+  // Navigation
+  'nav.syntheses': 'Syntheses',
+  'nav.sources': 'Sources personnalisees',
+  'nav.settings': 'Parametres',
+  'nav.admin': 'Administration',
+  'nav.logout': 'Deconnexion',
+
+  // Auth
+  'auth.loginTitle': 'AI Weekly Synth',
+  'auth.loginSubtitle': 'Votre synthese hebdomadaire des actualites IA',
+  'auth.emailPlaceholder': 'adresse@email.com',
+  'auth.requestLink': 'Recevoir un lien de connexion',
+  'auth.noAccount': 'Pas encore de compte ?',
+  'auth.createAccount': 'Creer un compte',
+  'auth.hasAccount': 'Deja un compte ?',
+  'auth.signIn': 'Se connecter',
+  'auth.linkSent': 'Un lien de connexion vous a ete envoye a {email}.',
+  'auth.resendLink': 'Renvoyer le lien',
+  'auth.resendIn': 'Renvoyer dans {seconds}s',
+  'auth.verifySuccess': 'Connexion reussie ! Redirection...',
+  'auth.verifyError': 'Le lien est invalide ou a expire.',
+  'auth.sessionExpired': 'Votre session a expire. Veuillez vous reconnecter.',
+
+  // Home
+  'home.title': "Syntheses d'Actualites par IA",
+  'home.subtitle': 'Retrouvez ici toutes vos syntheses hebdomadaires generees automatiquement.',
+  'home.newSynthesis': 'Nouvelle Synthese',
+  'home.empty.title': 'Aucune synthese',
+  'home.empty.description': 'Commencez par generer votre premiere synthese hebdomadaire.',
+  'home.empty.action': 'Generer',
+  'home.weekLabel': 'Semaine {week}',
+  'home.readSynthesis': 'Lire la synthese',
+  'home.generationInProgress': 'Une generation est en cours...',
+  'home.viewProgress': 'Voir la progression',
+
+  // Generate
+  'generate.title': 'Generer la Synthese Hebdomadaire',
+  'generate.description': "Cette action va lancer l'analyse des actualites des {days} derniers jours sur le theme \"{theme}\" via {provider} ({model}).",
+  'generate.note': 'Note : La generation peut prendre jusqu\'a une minute.',
+  'generate.noWebSearch': "Note : Le fournisseur selectionne ne dispose pas de la recherche web integree. Les resultats seront bases sur les connaissances du modele uniquement.",
+  'generate.start': 'Lancer la generation',
+  'generate.canLeave': 'Vous pouvez quitter cette page. La generation continuera en arriere-plan.',
+  'generate.success': 'Synthese generee avec succes ! Redirection...',
+  'generate.steps.search': "Recherche d'actualites",
+  'generate.steps.scraping': 'Verification des sources',
+  'generate.steps.rewrite': 'Redaction des resumes',
+  'generate.steps.saving': 'Sauvegarde',
+
+  // Synthesis Detail
+  'detail.backToList': 'Retour aux syntheses',
+  'detail.weekTitle': 'Synthese de la Semaine {week}',
+  'detail.generatedOn': 'Generee le {date}',
+  'detail.sendEmail': 'Envoyer par email',
+  'detail.sending': 'Envoi en cours...',
+  'detail.emailSent': "L'email a ete envoye avec succes !",
+  'detail.exportPdf': 'Exporter en PDF',
+  'detail.exportMarkdown': 'Exporter en Markdown',
+  'detail.delete': 'Supprimer',
+  'detail.deleteConfirmTitle': 'Supprimer cette synthese ?',
+  'detail.deleteConfirmMessage': 'Etes-vous sur de vouloir supprimer cette synthese definitivement ?',
+  'detail.deleteConfirm': 'Confirmer la suppression',
+  'detail.cancel': 'Annuler',
+
+  // Sources
+  'sources.title': 'Sources Personnalisees',
+  'sources.subtitle': "Ajoutez des sites web ou des blogs que l'IA devra obligatoirement consulter lors de la generation de vos syntheses.",
+  'sources.addTitle': 'Ajouter une source',
+  'sources.titlePlaceholder': 'Nom de la source (ex: Blog de Yann LeCun)',
+  'sources.urlPlaceholder': 'https://...',
+  'sources.add': 'Ajouter',
+  'sources.csvSection': 'Import / Export CSV',
+  'sources.csvDescription': 'Sauvegardez vos sources ou importez-en de nouvelles depuis un fichier CSV.',
+  'sources.exportCsv': 'Exporter en CSV',
+  'sources.importCsv': 'Importer depuis un CSV',
+  'sources.bulkSection': 'Import en masse',
+  'sources.bulkDescription': "Ajoutez plusieurs sources d'un coup. Une source par ligne, au format : Nom de la source;URL",
+  'sources.bulkPlaceholder': 'Blog IA;https://blog.ia.com\nNews Tech;https://tech.news.fr',
+  'sources.bulkImport': 'Importer les sources',
+  'sources.importing': 'Importation...',
+  'sources.empty': 'Aucune source personnalisee pour le moment.',
+  'sources.deleteConfirmTitle': 'Supprimer cette source ?',
+  'sources.deleteConfirmMessage': 'Cette source ne sera plus consultee lors des prochaines generations.',
+
+  // Settings
+  'settings.title': 'Parametres de generation',
+  'settings.export': 'Exporter',
+  'settings.import': 'Importer',
+  'settings.theme': 'Theme de la recherche',
+  'settings.themeHelp': "Le sujet principal pour la recherche d'actualites.",
+  'settings.maxAgeDays': 'Anciennete maximum (jours)',
+  'settings.maxItems': 'Actualites max par categorie',
+  'settings.searchBehavior': "Comportement de l'agent de recherche",
+  'settings.searchBehaviorHelp': "Personnalisez les instructions donnees a l'IA concernant sa methode de recherche.",
+  'settings.provider': "Fournisseur d'IA",
+  'settings.model': 'Modele',
+  'settings.apiKey': 'Cle API',
+  'settings.apiKeyPlaceholder': 'Entrez votre cle API pour ce fournisseur',
+  'settings.categories': "Categories d'actualite",
+  'settings.addCategory': 'Ajouter',
+  'settings.newCategory': 'Nouvelle categorie',
+  'settings.save': 'Enregistrer les parametres',
+  'settings.saved': 'Parametres enregistres avec succes.',
+  'settings.saveError': "Erreur lors de l'enregistrement des parametres.",
+  'settings.importSuccess': "Configuration importee avec succes. N'oubliez pas d'enregistrer.",
+  'settings.importError': "Erreur lors de l'importation du fichier JSON.",
+  'settings.providerWarning': "Le fournisseur que vous utilisiez n'est plus disponible. Veuillez en selectionner un autre.",
+
+  // Admin
+  'admin.providers.title': 'Configuration des fournisseurs LLM',
+  'admin.providers.add': 'Ajouter un fournisseur',
+  'admin.providers.name': 'Nom du fournisseur',
+  'admin.providers.models': 'Modeles disponibles',
+  'admin.providers.defaultModel': 'Modele par defaut',
+  'admin.providers.enabled': 'Active',
+  'admin.providers.save': 'Enregistrer',
+  'admin.rateLimits.title': "Configuration des limites d'usage",
+  'admin.rateLimits.globalSection': 'Limites globales',
+  'admin.rateLimits.perProvider': 'Par fournisseur',
+  'admin.rateLimits.requestsPerMinute': 'Requetes max / minute',
+  'admin.rateLimits.save': 'Enregistrer',
+  'admin.users.title': 'Gestion des utilisateurs',
+  'admin.users.email': 'Email',
+  'admin.users.role': 'Role',
+  'admin.users.createdAt': "Date d'inscription",
+
+  // Common
+  'common.loading': 'Chargement...',
+  'common.error': 'Une erreur est survenue.',
+  'common.retry': 'Reessayer',
+  'common.confirm': 'Confirmer',
+  'common.cancel': 'Annuler',
+  'common.delete': 'Supprimer',
+  'common.save': 'Enregistrer',
+} as const;
+
+export type TranslationKey = keyof typeof fr;
+export default fr;
+```
+
+### 5.3 i18n Context and Hook
+
+```typescript
+// src/i18n/index.ts
+import { createContext, useContext, ParentComponent, createMemo } from 'solid-js';
+import frTranslations, { type TranslationKey } from './locales/fr';
+
+type Translations = Record<TranslationKey, string>;
+
+interface I18nContextType {
+  t: (key: TranslationKey, params?: Record<string, string | number>) => string;
+  locale: () => string;
+}
+
+const translations: Record<string, Translations> = {
+  fr: frTranslations,
+};
+
+const I18nContext = createContext<I18nContextType>();
+
+export const I18nProvider: ParentComponent<{ locale: string }> = (props) => {
+  const locale = () => props.locale;
+
+  const t = (key: TranslationKey, params?: Record<string, string | number>): string => {
+    let value = translations[locale()]?.[key] ?? key;
+    if (params) {
+      Object.entries(params).forEach(([k, v]) => {
+        value = value.replace(`{${k}}`, String(v));
+      });
+    }
+    return value;
+  };
+
+  return (
+    <I18nContext.Provider value={{ t, locale }}>
+      {props.children}
+    </I18nContext.Provider>
+  );
+};
+
+export const useI18n = (): I18nContextType => {
+  const ctx = useContext(I18nContext);
+  if (!ctx) throw new Error('useI18n must be used within I18nProvider');
+  return ctx;
+};
+```
+
+### 5.4 Adding a New Language Later
+
+1. Create `src/i18n/locales/en.ts` with the same key structure.
+2. Import it in `src/i18n/index.ts` and add to the `translations` map.
+3. Make `locale` a signal (e.g., from user preferences or browser language).
+4. No changes to any component -- all text comes from `t('key')`.
+
+---
+
+## 6. SSE Integration
+
+### 6.1 EventSource Wrapper -- `src/lib/sse.ts`
+
+A SolidJS-friendly wrapper around `EventSource` that maps server events to signal-based callbacks with reconnection logic.
+
+```typescript
+// src/lib/sse.ts
+
+interface SSEOptions {
+  maxRetries?: number;       // Default: 3
+  retryDelay?: number;       // Default: 1000ms, doubles each retry
+  onOpen?: () => void;
+  onError?: (error: Event) => void;
+}
+
+interface SSEConnection {
+  on: (eventType: string, handler: (data: any) => void) => void;
+  close: () => void;
+  isConnected: () => boolean;
+}
+
+export function createSSEConnection(url: string, options: SSEOptions = {}): SSEConnection {
+  const maxRetries = options.maxRetries ?? 3;
+  const baseDelay = options.retryDelay ?? 1000;
+
+  let eventSource: EventSource | null = null;
+  let retryCount = 0;
+  let closed = false;
+  const handlers = new Map<string, Array<(data: any) => void>>();
+
+  const connect = () => {
+    if (closed) return;
+
+    eventSource = new EventSource(url, { withCredentials: true });
+
+    eventSource.onopen = () => {
+      retryCount = 0;
+      options.onOpen?.();
+    };
+
+    eventSource.onerror = (event) => {
+      options.onError?.(event);
+      eventSource?.close();
+
+      if (!closed && retryCount < maxRetries) {
+        const delay = baseDelay * Math.pow(2, retryCount);
+        retryCount++;
+        setTimeout(connect, delay);
+      }
+    };
+
+    // Register all known event handlers
+    handlers.forEach((handlerList, eventType) => {
+      handlerList.forEach((handler) => {
+        eventSource!.addEventListener(eventType, (event: MessageEvent) => {
+          try {
+            const data = JSON.parse(event.data);
+            handler(data);
+          } catch {
+            handler(event.data);
+          }
+        });
+      });
+    });
+  };
+
+  const on = (eventType: string, handler: (data: any) => void) => {
+    if (!handlers.has(eventType)) {
+      handlers.set(eventType, []);
+    }
+    handlers.get(eventType)!.push(handler);
+
+    // If already connected, add listener to existing eventSource
+    if (eventSource && eventSource.readyState !== EventSource.CLOSED) {
+      eventSource.addEventListener(eventType, (event: MessageEvent) => {
+        try {
+          const data = JSON.parse(event.data);
+          handler(data);
+        } catch {
+          handler(event.data);
+        }
+      });
+    }
+  };
+
+  const close = () => {
+    closed = true;
+    eventSource?.close();
+    eventSource = null;
+  };
+
+  const isConnected = () =>
+    eventSource !== null && eventSource.readyState === EventSource.OPEN;
+
+  // Start connection
+  connect();
+
+  return { on, close, isConnected };
+}
+```
+
+### 6.2 Generation Progress Display
+
+Used in `GenerateSynthesis.tsx`:
+
+```typescript
+// In GenerateSynthesis.tsx
+createEffect(() => {
+  const id = jobId();
+  if (!id) return;
+
+  const sse = createSSEConnection(
+    `/api/v1/syntheses/generate/${id}/progress`
+  );
+
+  sse.on('progress', (data: SSEProgressEvent) => {
+    setProgress(data);
+  });
+
+  sse.on('complete', (data: { synthesis_id: string }) => {
+    setStatus('complete');
+    setTimeout(() => navigate(`/synthesis/${data.synthesis_id}`), 1500);
+  });
+
+  sse.on('error', (data: { message: string }) => {
+    setStatus('error');
+    setErrorMessage(data.message);
+  });
+
+  onCleanup(() => sse.close());
+});
+```
+
+### 6.3 Real-Time List Updates
+
+For the Home page (synthesis list) and Sources page, SSE provides real-time updates when data changes server-side.
+
+**Pattern:** After initial `createResource` fetch, open an SSE connection to an events endpoint. Use `mutate()` from `createResource` to update the local data.
+
+```typescript
+// Home page SSE for list updates
+createEffect(() => {
+  const sse = createSSEConnection('/api/v1/syntheses/events');
+
+  sse.on('created', (synthesis: Synthesis) => {
+    mutate((prev) => prev ? [synthesis, ...prev] : [synthesis]);
+  });
+
+  sse.on('deleted', (data: { id: string }) => {
+    mutate((prev) => prev?.filter((s) => s.id !== data.id) ?? []);
+  });
+
+  sse.on('updated', (synthesis: Synthesis) => {
+    mutate((prev) =>
+      prev?.map((s) => (s.id === synthesis.id ? synthesis : s)) ?? []
+    );
+  });
+
+  onCleanup(() => sse.close());
+});
+```
+
+### 6.4 Reconnection Strategy
+
+- **Exponential backoff:** Start at 1s, double each retry, max 3 retries.
+- **On reconnect:** The client re-opens the SSE connection. The backend should replay any missed events since the last event ID (using `Last-Event-Id` header).
+- **On permanent failure (after max retries):** Fall back to polling via `setInterval` + `refetch()` every 10 seconds.
+- **On 401:** Do not retry. Redirect to login (session expired).
+
+---
+
+## 7. Tailwind CSS
+
+### 7.1 Replicating the Current Visual Design
+
+The current app uses a consistent indigo-based design system via Tailwind utility classes. Since Tailwind is framework-agnostic, the same utility classes transfer directly to SolidJS JSX with one systematic change: `className` becomes `class`.
+
+**Color scheme to preserve:**
+- Primary: `indigo-600` (buttons, links, badges, focus rings), `indigo-700` (hover)
+- Background: `gray-50` (page), `white` (cards)
+- Text: `gray-900` (headings), `gray-700` (body), `gray-500` (secondary), `gray-400` (icons)
+- Borders: `gray-200` (cards), `gray-300` (inputs), `indigo-300` (hover accent)
+- Success: `green-50`/`green-400`/`green-600`/`green-800`
+- Error: `red-50`/`red-400`/`red-600`/`red-800`
+
+**Card patterns:**
+```html
+<!-- Standard card -->
+<div class="bg-white rounded-lg shadow-sm border border-gray-200">
+<!-- Hoverable card (synthesis list) -->
+<div class="bg-white rounded-xl shadow-sm border border-gray-200 hover:shadow-md hover:border-indigo-300 transition-all duration-200">
+```
+
+**Button patterns:**
+```html
+<!-- Primary -->
+<button class="inline-flex items-center px-4 py-2 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500">
+<!-- Secondary -->
+<button class="inline-flex items-center px-4 py-2 border border-gray-300 shadow-sm text-sm font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500">
+<!-- Danger -->
+<button class="inline-flex items-center px-3 py-1.5 text-sm font-medium text-white bg-red-600 rounded-md hover:bg-red-700">
+```
+
+**Form input patterns:**
+```html
+<input class="shadow-sm focus:ring-indigo-500 focus:border-indigo-500 block w-full sm:text-sm border-gray-300 rounded-md py-2 px-3 border">
+```
+
+### 7.2 Tailwind v4 Configuration
+
+Tailwind v4 uses CSS-based configuration. The `index.css` file:
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+
+/* Custom theme overrides (if needed beyond defaults) */
+@theme {
+  --color-primary: var(--color-indigo-600);
+  --color-primary-hover: var(--color-indigo-700);
+}
+```
+
+Tailwind v4 auto-detects content sources from the Vite plugin, so no explicit `content` configuration is needed.
+
+### 7.3 Responsive Design Patterns
+
+The current app uses these breakpoint patterns (to preserve):
+
+| Pattern | Usage |
+|---|---|
+| `sm:grid-cols-2 lg:grid-cols-3` | Synthesis card grid on Home |
+| `sm:flex sm:space-y-0 sm:space-x-4` | Source add form (stack on mobile, row on desktop) |
+| `sm:px-6 lg:px-8` | Content area padding |
+| `max-w-5xl` | Home page width |
+| `max-w-4xl` | Sources, SynthesisDetail |
+| `max-w-3xl` | Settings, GenerateSynthesis |
+| `max-w-md` | Login/Register |
+
+**New: Mobile navigation fix.**
+
+The current app hides nav links on mobile with `hidden sm:flex`. The new version adds a hamburger menu:
+
+```html
+<!-- Mobile hamburger button (visible only on small screens) -->
+<button class="sm:hidden p-2 rounded-md text-gray-400 hover:text-gray-500 hover:bg-gray-100">
+  <Menu class="h-6 w-6" />
+</button>
+
+<!-- Desktop nav links (hidden on mobile) -->
+<div class="hidden sm:ml-6 sm:flex sm:space-x-8">
+  ...
+</div>
+```
+
+---
+
+## 8. Forms and Validation
+
+### 8.1 Form Handling Pattern
+
+SolidJS forms use `createStore` for complex form state (like Settings with nested categories) and `createSignal` for simple forms (like login email field).
+
+**Simple form (Login):**
+```typescript
+const [email, setEmail] = createSignal('');
+const [error, setError] = createSignal<string | null>(null);
+
+const handleSubmit = async (e: SubmitEvent) => {
+  e.preventDefault();
+  const validationError = validateEmail(email());
+  if (validationError) {
+    setError(validationError);
+    return;
+  }
+  // ... submit
+};
+```
+
+**Complex form (Settings):**
+```typescript
+import { createStore, produce } from 'solid-js/store';
+
+const [form, setForm] = createStore<UserSettings>({ ...DEFAULT_SETTINGS });
+const [errors, setErrors] = createStore<Record<string, string>>({});
+
+// Path-based update
+setForm('theme', 'Cybersecurite');
+setForm('categories', 2, 'New category name');
+
+// Array mutations via produce
+setForm(produce((draft) => {
+  draft.categories.splice(index, 1);
+}));
+```
+
+### 8.2 Validation Approach
+
+Client-side validation runs on submit (not on every keystroke, to avoid aggressive UX). Field-level errors display below each field.
+
+```typescript
+// src/lib/validation.ts
+
+export interface ValidationRule {
+  test: (value: any) => boolean;
+  message: string;
+}
+
+export const required = (fieldName: string): ValidationRule => ({
+  test: (v) => v !== null && v !== undefined && String(v).trim() !== '',
+  message: `${fieldName} est requis.`,
+});
+
+export const email = (): ValidationRule => ({
+  test: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(v)),
+  message: 'Adresse email invalide.',
+});
+
+export const url = (): ValidationRule => ({
+  test: (v) => {
+    try {
+      new URL(String(v));
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  message: 'URL invalide.',
+});
+
+export const minLength = (min: number): ValidationRule => ({
+  test: (v) => String(v).length >= min,
+  message: `Minimum ${min} caracteres.`,
+});
+
+export const maxLength = (max: number): ValidationRule => ({
+  test: (v) => String(v).length <= max,
+  message: `Maximum ${max} caracteres.`,
+});
+
+export const numberRange = (min: number, max: number): ValidationRule => ({
+  test: (v) => Number(v) >= min && Number(v) <= max,
+  message: `Doit etre entre ${min} et ${max}.`,
+});
+
+export function validate(
+  value: any,
+  rules: ValidationRule[]
+): string | null {
+  for (const rule of rules) {
+    if (!rule.test(value)) return rule.message;
+  }
+  return null;
+}
+
+export function validateForm(
+  fields: Record<string, { value: any; rules: ValidationRule[] }>
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+  for (const [key, { value, rules }] of Object.entries(fields)) {
+    const error = validate(value, rules);
+    if (error) errors[key] = error;
+  }
+  return errors;
+}
+```
+
+### 8.3 Error Display Pattern
+
+The `FormField` component wraps inputs with label and error display:
+
+```typescript
+// src/components/forms/FormField.tsx
+interface FormFieldProps {
+  label: string;
+  error?: string;
+  helpText?: string;
+  required?: boolean;
+  children: JSX.Element;
+}
+
+const FormField: Component<FormFieldProps> = (props) => {
+  return (
+    <div>
+      <label class="block text-sm font-medium text-gray-700">
+        {props.label}
+        <Show when={props.required}>
+          <span class="text-red-500 ml-1">*</span>
+        </Show>
+      </label>
+      <div class="mt-1">
+        {props.children}
+      </div>
+      <Show when={props.error}>
+        <p class="mt-1 text-sm text-red-600">{props.error}</p>
+      </Show>
+      <Show when={props.helpText && !props.error}>
+        <p class="mt-1 text-sm text-gray-500">{props.helpText}</p>
+      </Show>
+    </div>
+  );
+};
+```
+
+---
+
+## 9. PDF/Markdown Export
+
+### 9.1 Client-Side PDF Generation
+
+Using `jspdf` + `jspdf-autotable` for PDF generation. No server round-trip needed.
+
+```typescript
+// src/lib/export.ts
+import jsPDF from 'jspdf';
+import autoTable from 'jspdf-autotable';
+import { format } from 'date-fns';
+import { fr } from 'date-fns/locale';
+import type { Synthesis, NewsSection } from '~/types/synthesis';
+
+export function generatePdf(synthesis: Synthesis): void {
+  const doc = new jsPDF();
+  const weekNum = synthesis.week.split('-W')[1];
+
+  // Title
+  doc.setFontSize(20);
+  doc.text(`Synthese de la Semaine ${weekNum}`, 14, 22);
+
+  // Date
+  doc.setFontSize(10);
+  doc.setTextColor(100);
+  doc.text(
+    `Generee le ${format(new Date(synthesis.created_at), 'dd MMMM yyyy', { locale: fr })}`,
+    14,
+    30
+  );
+
+  let yOffset = 40;
+
+  for (const section of synthesis.sections) {
+    // Section title
+    doc.setFontSize(14);
+    doc.setTextColor(0);
+    doc.text(section.title, 14, yOffset);
+    yOffset += 8;
+
+    // Table of items
+    autoTable(doc, {
+      startY: yOffset,
+      head: [['Titre', 'Resume']],
+      body: section.items.map((item) => [item.title, item.summary]),
+      styles: { fontSize: 9, cellPadding: 4 },
+      headStyles: { fillColor: [79, 70, 229] }, // indigo-600
+      columnStyles: {
+        0: { cellWidth: 60 },
+        1: { cellWidth: 'auto' },
+      },
+      didDrawPage: (data) => {
+        yOffset = data.cursor?.y ?? yOffset;
+      },
+    });
+
+    yOffset = (doc as any).lastAutoTable.finalY + 12;
+
+    // Add new page if needed
+    if (yOffset > 270) {
+      doc.addPage();
+      yOffset = 20;
+    }
+  }
+
+  doc.save(`synthese-semaine-${weekNum}.pdf`);
+}
+```
+
+### 9.2 Markdown Generation
+
+```typescript
+export function generateMarkdown(synthesis: Synthesis): void {
+  const weekNum = synthesis.week.split('-W')[1];
+  const date = format(new Date(synthesis.created_at), 'dd MMMM yyyy', { locale: fr });
+
+  let md = `# Synthese de la Semaine ${weekNum}\n\n`;
+  md += `*Generee le ${date}*\n\n`;
+
+  for (const section of synthesis.sections) {
+    md += `## ${section.title}\n\n`;
+    for (const item of section.items) {
+      md += `### [${item.title}](${item.url})\n\n`;
+      md += `${item.summary}\n\n`;
+    }
+  }
+
+  // Trigger download
+  const blob = new Blob([md], { type: 'text/markdown;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = `synthese-semaine-${weekNum}.md`;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
+```
+
+### 9.3 Integration in SynthesisDetail
+
+```typescript
+// In SynthesisDetail.tsx action bar
+<div class="flex gap-3">
+  <Button variant="secondary" icon={FileDown} onClick={() => generatePdf(synthesis()!)}>
+    {t('detail.exportPdf')}
+  </Button>
+  <Button variant="secondary" icon={FileText} onClick={() => generateMarkdown(synthesis()!)}>
+    {t('detail.exportMarkdown')}
+  </Button>
+</div>
+```
+
+---
+
+## 10. React-to-SolidJS Migration Map
+
+### 10.1 File Mapping Table
+
+| React File | SolidJS File | Key Differences | Gotchas |
+|---|---|---|---|
+| `src/App.tsx` (Login) | `src/pages/auth/Login.tsx` | Google SSO button replaced by email+Turnstile form. Magic link flow. | Turnstile requires imperative script loading in `onMount` |
+| `src/App.tsx` (ProtectedRoute) | `src/components/auth/ProtectedRoute.tsx` | `if/return` pattern replaced by nested `<Show>`. `useAuth()` returns accessor functions, not values. | Must call `user()` not just `user` to read the signal |
+| `src/App.tsx` (Layout) | `src/components/layout/AppShell.tsx` + `Navbar.tsx` + `MobileMenu.tsx` | Split into 3 components. Added mobile menu. Added active route indicator. `className` -> `class`. | `props.children` not `{children}` destructure |
+| `src/App.tsx` (Router) | `src/App.tsx` | `BrowserRouter/Routes/Route` -> `Router/Route` from `@solidjs/router`. Nested routes replace per-route `<ProtectedRoute>` wrapping. | Route nesting is structural (layout-based), not wrapping |
+| `src/components/AuthContext.tsx` | `src/context/AuthContext.tsx` | `useState`/`useEffect`/`onAuthStateChanged` -> `createSignal`/`onMount`/`GET /api/v1/auth/me`. Firebase auth removed entirely. | Signal accessors: `user()` is a function call |
+| `src/pages/Home.tsx` | `src/pages/Home.tsx` | `useState`+`useEffect`+`onSnapshot` -> `createResource`+SSE. `{array.map()}` -> `<For each={}>`. `className` -> `class`. Firestore `Timestamp` -> ISO date string. | `<For>` callback receives item as argument, not destructured. `format(synth.createdAt.toDate(), ...)` becomes `format(new Date(synth.created_at), ...)` |
+| `src/pages/GenerateSynthesis.tsx` | `src/pages/GenerateSynthesis.tsx` | Client-side Gemini call replaced by `POST /api/v1/syntheses/generate` + SSE progress. Single spinner replaced by multi-step progress indicator. | SSE connection must be cleaned up with `onCleanup`. Job continues server-side if user navigates away. |
+| `src/pages/SynthesisDetail.tsx` | `src/pages/SynthesisDetail.tsx` | `onSnapshot` -> `createResource`. Gmail OAuth email -> `POST /api/v1/syntheses/:id/email`. Added PDF/Markdown export buttons. Legacy data rendering removed. Hardcoded email removed. | `useParams()` returns a reactive proxy -- do not destructure. Use `params.id` directly. |
+| `src/pages/Sources.tsx` | `src/pages/Sources.tsx` | `onSnapshot` -> `createResource` + SSE. `React.FormEvent` -> `SubmitEvent`. `React.ChangeEvent<HTMLInputElement>` -> `Event`. CSV import as multipart to backend endpoint. Added delete confirmation. | File input `onChange` types differ -- use `(e.target as HTMLInputElement).files` |
+| `src/pages/Settings.tsx` | `src/pages/Settings.tsx` | `useState<AppSettings>` -> `createStore<UserSettings>`. Hardcoded model options -> dynamic from `GET /api/v1/config/providers`. Added provider dropdown and API key field. | `createStore` uses path-based setters, not spread-based. Category array updates need `produce()` or index-based setters. |
+| `src/types.ts` | `src/types/` (split into multiple files) | Firestore `Timestamp` removed. `SynthesisData` legacy fields removed. New types for auth, admin, providers. `camelCase` -> `snake_case` for API fields. | Ensure frontend types match backend JSON field names (snake_case) |
+| `src/index.css` | `src/index.css` | Identical: `@import "tailwindcss"` | No change needed |
+| `src/firebase.ts` | Removed entirely | Replaced by `src/api/client.ts` + domain-specific API modules | -- |
+| `src/services/geminiService.ts` | Removed entirely | All LLM logic moves to Rust backend | -- |
+
+### 10.2 Pattern Mapping Reference
+
+| React Pattern | SolidJS Equivalent | Notes |
+|---|---|---|
+| `useState(initialValue)` | `createSignal(initialValue)` | Returns `[getter, setter]` where getter is a function |
+| `useState({...complex})` | `createStore({...complex})` | For nested objects. Use path-based setters. |
+| `useEffect(() => {}, [deps])` | `createEffect(() => {})` | Auto-tracks dependencies. No dep array needed. |
+| `useEffect(() => { return cleanup }, [])` | `onMount(() => {}); onCleanup(() => {})` | Separate mount and cleanup |
+| `useRef()` | `let ref: HTMLElement \| undefined` | Direct variable assignment. Pass via `ref={el => ref = el}` |
+| `useMemo(() => computed, [deps])` | `createMemo(() => computed)` | Auto-tracks. Returns accessor function. |
+| `useCallback(() => fn, [deps])` | Just use the function directly | SolidJS does not re-render, so memoizing callbacks is unnecessary |
+| `React.FC<Props>` | `Component<Props>` (from `solid-js`) | -- |
+| `{condition && <Component />}` | `<Show when={condition}><Component /></Show>` | `<Show>` avoids evaluating the false branch |
+| `{condition ? <A /> : <B />}` | `<Show when={condition} fallback={<B />}><A /></Show>` | -- |
+| `{items.map(item => <C key={item.id} />)}` | `<For each={items}>{(item) => <C />}</For>` | `<For>` is keyed by reference. Add `key` via index param if needed. |
+| `<Link to="/">` | `<A href="/">` | From `@solidjs/router` |
+| `useParams<{id: string}>()` | `useParams()` | Returns reactive proxy. Access `params.id`, do not destructure. |
+| `useNavigate()` | `useNavigate()` | Same API: `navigate('/path')` |
+| `className="..."` | `class="..."` | Systematic find-and-replace. `class` is standard HTML. |
+| `onChange={(e) => setValue(e.target.value)}` | `onInput={(e) => setValue(e.currentTarget.value)}` | `onInput` fires on every keystroke. `onChange` fires on blur in SolidJS (matching DOM behavior). Use `onInput` for real-time input binding. |
+| `e: React.ChangeEvent<HTMLInputElement>` | `e: InputEvent & { currentTarget: HTMLInputElement }` | Native DOM event types |
+| `e: React.FormEvent` | `e: SubmitEvent` | Native DOM event type |
+| `dangerouslySetInnerHTML` | `innerHTML` (JSX attribute) | Both should be avoided when possible |
+
+---
+
+## 11. Testing
+
+### 11.1 Setup
+
+Vitest is configured automatically via the Vite config. Additional setup for SolidJS:
+
+```typescript
+// vitest.config.ts (or in vite.config.ts)
+/// <reference types="vitest" />
+import { defineConfig } from 'vite';
+import solid from 'vite-plugin-solid';
+
+export default defineConfig({
+  plugins: [solid()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./src/test-setup.ts'],
+    transformMode: {
+      web: [/\.[jt]sx?$/],
+    },
+  },
+});
+```
+
+```typescript
+// src/test-setup.ts
+import '@testing-library/jest-dom';
+```
+
+### 11.2 Component Test Examples
+
+**Testing the Spinner component:**
+```typescript
+// src/components/ui/Spinner.test.tsx
+import { render, screen } from '@solidjs/testing-library';
+import Spinner from './Spinner';
+
+describe('Spinner', () => {
+  it('renders a spinner with default size', () => {
+    render(() => <Spinner />);
+    const spinner = screen.getByRole('status');
+    expect(spinner).toBeInTheDocument();
+  });
+
+  it('renders full-page spinner when fullPage is true', () => {
+    render(() => <Spinner fullPage />);
+    const container = screen.getByRole('status').parentElement;
+    expect(container).toHaveClass('h-screen');
+  });
+});
+```
+
+**Testing the ProtectedRoute:**
+```typescript
+// src/components/auth/ProtectedRoute.test.tsx
+import { render, screen } from '@solidjs/testing-library';
+import { Router } from '@solidjs/router';
+import { AuthProvider } from '~/context/AuthContext';
+import ProtectedRoute from './ProtectedRoute';
+
+// Mock the auth API
+vi.mock('~/api/auth', () => ({
+  authApi: {
+    me: vi.fn().mockRejectedValue(new Error('Unauthorized')),
+  },
+}));
+
+describe('ProtectedRoute', () => {
+  it('shows spinner while loading', () => {
+    render(() => (
+      <Router>
+        <AuthProvider>
+          <ProtectedRoute>
+            <div>Protected content</div>
+          </ProtectedRoute>
+        </AuthProvider>
+      </Router>
+    ));
+    expect(screen.getByRole('status')).toBeInTheDocument();
+  });
+});
+```
+
+**Testing the API client:**
+```typescript
+// src/api/client.test.ts
+import { api } from './client';
+
+describe('ApiClient', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('sends X-Requested-With header for CSRF protection', async () => {
+    const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(
+      new Response(JSON.stringify({ data: 'test' }), { status: 200 })
+    );
+
+    await api.get('/test');
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      '/api/v1/test',
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          'X-Requested-With': 'XMLHttpRequest',
+        }),
+      })
+    );
+  });
+
+  it('redirects to /login on 401 response', async () => {
+    const originalLocation = window.location;
+    delete (window as any).location;
+    window.location = { href: '' } as Location;
+
+    vi.spyOn(global, 'fetch').mockResolvedValue(
+      new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 })
+    );
+
+    await expect(api.get('/protected')).rejects.toThrow('Session expired');
+    expect(window.location.href).toBe('/login');
+
+    window.location = originalLocation;
+  });
+});
+```
+
+### 11.3 What to Test
+
+| Area | What to test | Priority |
+|---|---|---|
+| **API client** | CSRF header sent, 401 redirect, error parsing, JSON serialization | High |
+| **Auth flow** | Session check on mount, login triggers API call, logout clears state, redirect on unauthenticated | High |
+| **ProtectedRoute** | Shows spinner while loading, redirects when unauthenticated, renders children when authenticated | High |
+| **SSE wrapper** | Connection opens, events parsed, reconnection on error, cleanup on close | High |
+| **Form validation** | Email validation, URL validation, required fields, number ranges | Medium |
+| **SynthesisCard** | Renders week number, date, preview items, delete button | Medium |
+| **Settings form** | Category add/remove, provider/model cascading, save triggers API call | Medium |
+| **PDF export** | Generates valid PDF blob (smoke test) | Low |
+| **i18n** | Translation key lookup, parameter interpolation, missing key fallback | Low |
+| **Toast system** | Toast appears, auto-dismisses, multiple toasts stack | Low |
+
+### 11.4 Integration Test Pattern
+
+For pages that make API calls, mock the API module and test the full page lifecycle:
+
+```typescript
+// src/pages/Home.test.tsx
+import { render, screen, waitFor } from '@solidjs/testing-library';
+import { Router } from '@solidjs/router';
+import Home from './Home';
+
+vi.mock('~/api/syntheses', () => ({
+  synthesesApi: {
+    list: vi.fn().mockResolvedValue([
+      {
+        id: '1',
+        week: '2026-W12',
+        created_at: '2026-03-21T10:00:00Z',
+        sections: [
+          {
+            title: 'Annonces majeures',
+            items: [{ title: 'Test article', url: 'https://example.com', summary: 'A summary' }],
+          },
+        ],
+      },
+    ]),
+  },
+}));
+
+describe('Home', () => {
+  it('renders synthesis cards after loading', async () => {
+    render(() => (
+      <Router>
+        <Home />
+      </Router>
+    ));
+
+    // Initially shows spinner
+    expect(screen.getByRole('status')).toBeInTheDocument();
+
+    // After loading, shows synthesis card
+    await waitFor(() => {
+      expect(screen.getByText('Semaine 12')).toBeInTheDocument();
+      expect(screen.getByText('Test article')).toBeInTheDocument();
+    });
+  });
+});
+```
+
+---
+
+## Type Definitions Summary
+
+### `src/types/auth.ts`
+
+```typescript
+export interface User {
+  id: string;
+  email: string;
+  display_name: string | null;
+  role: 'user' | 'admin';
+  created_at: string; // ISO 8601
+}
+
+export interface RegisterRequest {
+  email: string;
+  display_name?: string;
+  captcha_token: string;
+}
+
+export interface LoginRequest {
+  email: string;
+  captcha_token: string;
+}
+
+export interface AuthMessageResponse {
+  message: string;
+}
+```
+
+### `src/types/synthesis.ts`
+
+```typescript
+export interface NewsItem {
+  title: string;
+  url: string;
+  summary: string;
+}
+
+export interface NewsSection {
+  title: string;
+  items: NewsItem[];
+}
+
+export interface Synthesis {
+  id: string;
+  week: string; // e.g., "2026-W12"
+  created_at: string; // ISO 8601
+  sections: NewsSection[];
+}
+
+export interface GenerateResponse {
+  job_id: string;
+  status: 'pending';
+}
+
+export interface SSEProgressEvent {
+  step: 'search' | 'scraping' | 'rewrite' | 'saving';
+  message: string;
+  percent: number;
+}
+
+export interface SSECompleteEvent {
+  synthesis_id: string;
+}
+
+export interface SSEErrorEvent {
+  message: string;
+}
+
+export type GenerationStatus = 'idle' | 'generating' | 'complete' | 'error';
+```
+
+### `src/types/source.ts`
+
+```typescript
+export interface Source {
+  id: string;
+  title: string;
+  url: string;
+  created_at: string; // ISO 8601
+}
+
+export interface CreateSourceRequest {
+  title: string;
+  url: string;
+}
+
+export interface BulkImportRequest {
+  sources: CreateSourceRequest[];
+}
+```
+
+### `src/types/settings.ts`
+
+```typescript
+export interface UserSettings {
+  theme: string;
+  max_age_days: number;
+  categories: string[];
+  max_items_per_category: number;
+  search_agent_behavior: string;
+  provider_id: string;
+  model_name: string;
+  api_key: string; // User's own API key (sent encrypted by backend)
+}
+
+export const DEFAULT_SETTINGS: UserSettings = {
+  theme: 'Intelligence Artificielle',
+  max_age_days: 7,
+  categories: [
+    'Annonces majeures / importantes',
+    'Entreprises des secteurs financiers (banques, assurances, etc.)',
+    'Grandes entreprises des autres secteurs',
+    'Secteurs publics (Defense, Education, etc.)',
+    'Grand public / Particuliers',
+  ],
+  max_items_per_category: 4,
+  search_agent_behavior:
+    "Tu peux egalement utiliser d'autres sources pertinentes trouvees via la recherche Google.",
+  provider_id: '',
+  model_name: '',
+  api_key: '',
+};
+```
+
+### `src/types/admin.ts`
+
+```typescript
+export interface ProviderConfig {
+  id: string;
+  name: string; // e.g., "Google Gemini", "OpenAI", "Anthropic"
+  slug: string; // e.g., "gemini", "openai", "anthropic"
+  models: ModelConfig[];
+  enabled: boolean;
+}
+
+export interface ModelConfig {
+  name: string; // e.g., "gemini-3.1-pro-preview"
+  display_name: string; // e.g., "Gemini 3.1 Pro (conseille)"
+  supports_web_search: boolean;
+}
+
+export interface RateLimitConfig {
+  provider_id: string;
+  provider_name: string;
+  requests_per_minute: number;
+}
+
+export interface AdminUser {
+  id: string;
+  email: string;
+  display_name: string | null;
+  role: 'user' | 'admin';
+  created_at: string;
+}
+```
+
+### `src/types/api.ts`
+
+```typescript
+export interface ApiError {
+  status: number;
+  message: string;
+  field_errors?: Record<string, string>;
+}
+
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  page: number;
+  per_page: number;
+}
+```
+
+---
+
+## Appendix: Cloudflare Turnstile TypeScript Declarations
+
+Since Turnstile is loaded via script tag and used imperatively, add type declarations:
+
+```typescript
+// src/types/turnstile.d.ts
+declare global {
+  interface Window {
+    turnstile: {
+      render: (
+        container: HTMLElement,
+        options: {
+          sitekey: string;
+          callback: (token: string) => void;
+          'expired-callback'?: () => void;
+          'error-callback'?: () => void;
+          theme?: 'light' | 'dark' | 'auto';
+          size?: 'normal' | 'compact';
+        }
+      ) => string; // Returns widget ID
+      reset: (widgetId: string) => void;
+      remove: (widgetId: string) => void;
+    };
+  }
+}
+
+export {};
+```
+
+## Appendix: Environment Variables
+
+```typescript
+// src/vite-env.d.ts
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_TURNSTILE_SITE_KEY: string;
+  readonly VITE_API_BASE_URL?: string; // Optional override for non-proxy setups
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+```
diff --git a/docs/implementation-plan/04-infrastructure-plan.md b/docs/implementation-plan/04-infrastructure-plan.md
new file mode 100644
index 0000000..78771a7
--- /dev/null
+++ b/docs/implementation-plan/04-infrastructure-plan.md
@@ -0,0 +1,2418 @@
+# Infrastructure & Testing Plan: AI Weekly Synth Rewrite
+
+**Role**: Infrastructure & Testing Planner
+**Date**: 2026-03-21
+**Inputs**: Team analysis (00-04), project decisions (05), CLAUDE.md
+
+---
+
+## Table of Contents
+
+1. [Docker Setup](#1-docker-setup)
+2. [Environment Configuration](#2-environment-configuration)
+3. [Database Management](#3-database-management)
+4. [CLI Commands](#4-cli-commands)
+5. [Reverse Proxy & TLS](#5-reverse-proxy--tls)
+6. [Testing Strategy](#6-testing-strategy)
+7. [CI/CD Pipeline](#7-cicd-pipeline)
+8. [Monitoring & Observability](#8-monitoring--observability)
+9. [Documentation](#9-documentation)
+10. [Security Hardening Checklist](#10-security-hardening-checklist)
+
+---
+
+## 1. Docker Setup
+
+### 1.1 Dockerfile (Production Multi-Stage Build)
+
+The build uses three stages: Rust backend compilation with `cargo-chef` for layer caching, SolidJS frontend build, and a minimal Debian slim runtime.
+
+```dockerfile
+# ===================================================================
+# Stage 0: cargo-chef planner (captures dependency info for caching)
+# ===================================================================
+FROM rust:1.85-bookworm AS chef
+RUN cargo install cargo-chef --locked
+WORKDIR /app
+
+# ===================================================================
+# Stage 1a: Prepare the recipe (dependency snapshot)
+# ===================================================================
+FROM chef AS planner
+COPY Cargo.toml Cargo.lock ./
+COPY src/ src/
+COPY migrations/ migrations/
+RUN cargo chef prepare --recipe-path recipe.json
+
+# ===================================================================
+# Stage 1b: Build Rust backend dependencies (cached layer)
+# ===================================================================
+FROM chef AS backend-deps
+COPY --from=planner /app/recipe.json recipe.json
+# Build only dependencies - this layer is cached unless Cargo.toml/lock changes
+RUN cargo chef cook --release --recipe-path recipe.json
+
+# ===================================================================
+# Stage 1c: Build the actual Rust backend
+# ===================================================================
+FROM backend-deps AS backend-builder
+COPY Cargo.toml Cargo.lock ./
+COPY src/ src/
+COPY migrations/ migrations/
+
+# sqlx offline mode: use pre-generated query metadata (no live DB needed)
+ENV SQLX_OFFLINE=true
+COPY sqlx-data.json ./
+
+RUN cargo build --release
+
+# ===================================================================
+# Stage 2: Build SolidJS frontend
+# ===================================================================
+FROM node:22-alpine AS frontend-builder
+
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci --ignore-scripts
+
+COPY frontend/ ./
+RUN npm run build
+
+# ===================================================================
+# Stage 3: Minimal runtime image
+# ===================================================================
+FROM debian:bookworm-slim AS runtime
+
+# Install only what the binary needs at runtime
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        libssl3 \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN groupadd --system appuser \
+    && useradd --system --gid appuser --home-dir /app --no-create-home --shell /usr/sbin/nologin appuser
+
+WORKDIR /app
+
+# Copy backend binary
+COPY --from=backend-builder /app/target/release/ai-weekly-synth ./ai-weekly-synth
+
+# Copy migrations (run at startup)
+COPY --from=backend-builder /app/migrations/ ./migrations/
+
+# Copy frontend static files
+COPY --from=frontend-builder /app/frontend/dist/ ./static/
+
+# Set ownership
+RUN chown -R appuser:appuser /app
+
+USER appuser
+
+ENV PORT=8080
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8080/api/v1/health || exit 1
+
+ENTRYPOINT ["./ai-weekly-synth"]
+CMD ["serve"]
+```
+
+**Key design decisions:**
+
+- **cargo-chef**: Separates dependency compilation from source compilation. Changing a `.rs` file only rebuilds the final stage, not all dependencies. This typically saves 3-8 minutes per build.
+- **SQLX_OFFLINE=true**: Uses pre-generated `sqlx-data.json` so the build does not need a live database connection. Developers generate this file locally with `cargo sqlx prepare`.
+- **curl in runtime**: Required for the `HEALTHCHECK` instruction. Adds approximately 3 MB to the image.
+- **Non-root user**: `appuser` has no shell, no home directory, and no login capability.
+- **ENTRYPOINT + CMD split**: Allows running CLI subcommands (e.g., `docker run ai-weekly-synth create-admin admin@example.com`) by overriding CMD.
+
+### 1.2 .dockerignore
+
+```
+target/
+node_modules/
+.git/
+.env
+.env.*
+!.env.example
+*.md
+docs/
+tests/
+frontend/node_modules/
+frontend/dist/
+**/*.swp
+**/*.swo
+.DS_Store
+```
+
+### 1.3 docker-compose.yml (Production)
+
+```yaml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: ai-synth
+    restart: unless-stopped
+    env_file: .env
+    environment:
+      - DATABASE_URL=postgres://ai_synth:${POSTGRES_PASSWORD}@db:5432/ai_synth
+    depends_on:
+      db:
+        condition: service_healthy
+    networks:
+      - internal
+    # Port is NOT exposed to host; Caddy handles external traffic
+    expose:
+      - "8080"
+    read_only: true
+    tmpfs:
+      - /tmp:noexec,nosuid,size=64M
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/health"]
+      interval: 30s
+      timeout: 5s
+      start_period: 15s
+      retries: 3
+
+  db:
+    image: postgres:17-alpine
+    container_name: ai-synth-db
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ai_synth
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ai_synth
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - internal
+    # NOT exposed to host in production
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ai_synth -d ai_synth"]
+      interval: 10s
+      timeout: 5s
+      start_period: 10s
+      retries: 5
+    shm_size: 128mb
+
+  caddy:
+    image: caddy:2-alpine
+    container_name: ai-synth-caddy
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"  # HTTP/3
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      app:
+        condition: service_healthy
+    networks:
+      - internal
+
+networks:
+  internal:
+    driver: bridge
+
+volumes:
+  postgres_data:
+    driver: local
+  caddy_data:
+    driver: local
+  caddy_config:
+    driver: local
+```
+
+**Key design decisions:**
+
+- **Internal network only**: The app and database communicate on an internal Docker bridge network. Only Caddy exposes ports 80/443 to the host.
+- **read_only + tmpfs**: The app container's filesystem is read-only. `/tmp` is mounted as tmpfs for any transient file needs.
+- **Postgres health check**: The app service waits for Postgres to be ready before starting (`condition: service_healthy`).
+- **shm_size**: Postgres uses shared memory; 128 MB is sufficient for this workload.
+- **No `version` key**: Docker Compose v2+ no longer requires the `version` field.
+
+### 1.4 docker-compose.dev.yml (Development Override)
+
+Run with: `docker compose -f docker-compose.yml -f docker-compose.dev.yml up`
+
+```yaml
+services:
+  app:
+    build:
+      target: backend-deps  # Stop at the deps stage; source is mounted
+    command: ["cargo", "watch", "-x", "run -- serve"]
+    volumes:
+      - ./Cargo.toml:/app/Cargo.toml
+      - ./Cargo.lock:/app/Cargo.lock
+      - ./src:/app/src
+      - ./migrations:/app/migrations
+      - cargo_cache:/usr/local/cargo/registry
+      - target_cache:/app/target
+    environment:
+      - DATABASE_URL=postgres://ai_synth:devpassword@db:5432/ai_synth
+      - RUST_LOG=debug,ai_weekly_synth=trace
+      - RUST_BACKTRACE=1
+      - APP_URL=http://localhost:3000
+    read_only: false
+    security_opt: []
+    cap_drop: []
+    ports:
+      - "8080:8080"  # Expose API directly for debugging
+
+  frontend:
+    image: node:22-alpine
+    container_name: ai-synth-frontend-dev
+    working_dir: /app/frontend
+    command: ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
+    volumes:
+      - ./frontend:/app/frontend
+      - frontend_node_modules:/app/frontend/node_modules
+    ports:
+      - "3000:3000"
+    environment:
+      - VITE_API_URL=http://localhost:8080
+    networks:
+      - internal
+
+  db:
+    ports:
+      - "5432:5432"  # Expose Postgres for direct access with psql/pgAdmin
+    environment:
+      POSTGRES_PASSWORD: devpassword
+
+  mailpit:
+    image: axllent/mailpit:latest
+    container_name: ai-synth-mailpit
+    restart: unless-stopped
+    ports:
+      - "8025:8025"   # Mailpit web UI
+      - "1025:1025"   # SMTP
+    networks:
+      - internal
+
+  caddy:
+    # Disable Caddy in dev; frontend dev server handles its own port
+    profiles:
+      - production-only
+
+volumes:
+  cargo_cache:
+    driver: local
+  target_cache:
+    driver: local
+  frontend_node_modules:
+    driver: local
+```
+
+**Development workflow:**
+
+- **Backend**: `cargo-watch` recompiles and restarts the Rust server on any file change in `src/`. The cargo registry and target directory are cached in named volumes so rebuilds are fast.
+- **Frontend**: Vite dev server runs separately on port 3000 with HMR. API requests are proxied to `localhost:8080` via the Vite config's `proxy` setting.
+- **Database**: Postgres port 5432 is exposed to the host so developers can connect with `psql`, pgAdmin, or DBeaver.
+- **Email**: Mailpit catches all outgoing emails on SMTP port 1025 and provides a web UI at `http://localhost:8025` for inspecting magic link emails.
+- **Caddy**: Disabled in development (no TLS needed locally).
+
+### 1.5 Simplified Development Without Docker
+
+For developers who prefer running outside Docker, a minimal setup is also possible:
+
+```bash
+# Terminal 1: Postgres (still in Docker for convenience)
+docker run -d --name ai-synth-pg \
+  -e POSTGRES_USER=ai_synth \
+  -e POSTGRES_PASSWORD=devpassword \
+  -e POSTGRES_DB=ai_synth \
+  -p 5432:5432 \
+  postgres:17-alpine
+
+# Terminal 2: Rust backend with cargo-watch
+cargo install cargo-watch sqlx-cli
+export DATABASE_URL="postgres://ai_synth:devpassword@localhost:5432/ai_synth"
+sqlx database create && sqlx migrate run
+cargo watch -x 'run -- serve'
+
+# Terminal 3: Frontend
+cd frontend && npm install && npm run dev
+
+# Terminal 4: Mailpit
+docker run -d --name ai-synth-mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit
+```
+
+---
+
+## 2. Environment Configuration
+
+### 2.1 Complete Environment Variable Reference
+
+| Variable | Description | Required | Default | Example |
+|---|---|---|---|---|
+| **Database** | | | | |
+| `DATABASE_URL` | Postgres connection string | Yes | -- | `postgres://ai_synth:s3cret@db:5432/ai_synth` |
+| **Security** | | | | |
+| `MASTER_ENCRYPTION_KEY` | 256-bit hex key for encrypting user API keys at rest (AES-256-GCM) | Yes | -- | `a1b2c3...` (64 hex chars) |
+| `SESSION_SECRET` | Secret for signing session cookies (HMAC) | Yes | -- | `e4f5a6...` (64 hex chars) |
+| **Application** | | | | |
+| `APP_URL` | Public URL of the app (used in magic link emails, CORS origin) | Yes | -- | `https://synth.example.com` |
+| `PORT` | HTTP port the Rust server listens on | No | `8080` | `8080` |
+| `RUST_LOG` | Logging level filter (tracing-subscriber) | No | `info` | `info,ai_weekly_synth=debug` |
+| `STATIC_DIR` | Path to the built SolidJS frontend files | No | `./static` | `/app/static` |
+| **Email (Resend)** | | | | |
+| `RESEND_API_KEY` | Resend API key for transactional email (magic links, synthesis delivery) | Yes | -- | `re_abc123...` |
+| `EMAIL_FROM` | Sender address for outgoing emails | Yes | -- | `AI Weekly Synth <noreply@synth.example.com>` |
+| **Captcha (Cloudflare Turnstile)** | | | | |
+| `TURNSTILE_SECRET_KEY` | Turnstile server-side secret key | Yes | -- | `0x4AAAAAAA...` |
+| `TURNSTILE_SITE_KEY` | Turnstile client-side site key (passed to frontend) | Yes | -- | `0x4BBBBBB...` |
+| **Postgres (docker-compose only)** | | | | |
+| `POSTGRES_PASSWORD` | Password for the Postgres `ai_synth` user | Yes | -- | `strong-random-password` |
+
+### 2.2 .env.example
+
+```env
+# ==============================================================================
+# AI Weekly Synth - Environment Configuration
+# ==============================================================================
+# Copy this file to .env and fill in the values.
+# NEVER commit .env to version control.
+# ==============================================================================
+
+# --- Database ---
+# Connection string for Postgres. In docker-compose, the hostname is "db".
+DATABASE_URL=postgres://ai_synth:CHANGE_ME@db:5432/ai_synth
+POSTGRES_PASSWORD=CHANGE_ME
+
+# --- Security ---
+# 256-bit key for encrypting user LLM API keys at rest (64 hex characters).
+# Generate with: openssl rand -hex 32
+MASTER_ENCRYPTION_KEY=
+
+# Secret for signing session cookies (64 hex characters).
+# Generate with: openssl rand -hex 32
+SESSION_SECRET=
+
+# --- Application ---
+# Public URL where the app is accessible (no trailing slash).
+# Used for magic link URLs, CORS origin, and cookie domain.
+APP_URL=https://synth.example.com
+
+# Port for the backend HTTP server (inside the container).
+PORT=8080
+
+# Logging level. Options: error, warn, info, debug, trace.
+# Format: "level" or "level,crate=level"
+RUST_LOG=info,ai_weekly_synth=debug
+
+# --- Email (Resend) ---
+# Sign up at https://resend.com and create an API key.
+RESEND_API_KEY=re_CHANGE_ME
+
+# Sender address. Must be a verified domain in Resend.
+EMAIL_FROM=AI Weekly Synth <noreply@synth.example.com>
+
+# --- Captcha (Cloudflare Turnstile) ---
+# Sign up at https://dash.cloudflare.com/turnstile
+TURNSTILE_SECRET_KEY=0x4AAAAAAA_CHANGE_ME
+TURNSTILE_SITE_KEY=0x4BBBBBB_CHANGE_ME
+```
+
+### 2.3 Configuration Loading in Rust
+
+Use a typed configuration struct with `dotenvy` for `.env` file loading and `serde` for deserialization from environment variables via the `envy` crate.
+
+```rust
+// src/config.rs
+use secrecy::{ExposeSecret, SecretString};
+use serde::Deserialize;
+
+#[derive(Debug, Deserialize, Clone)]
+pub struct AppConfig {
+    // Database
+    pub database_url: SecretString,
+
+    // Security
+    pub master_encryption_key: SecretString,
+    pub session_secret: SecretString,
+
+    // Application
+    pub app_url: String,
+    #[serde(default = "default_port")]
+    pub port: u16,
+    #[serde(default = "default_static_dir")]
+    pub static_dir: String,
+
+    // Email (Resend)
+    pub resend_api_key: SecretString,
+    pub email_from: String,
+
+    // Captcha (Turnstile)
+    pub turnstile_secret_key: SecretString,
+    pub turnstile_site_key: String,
+}
+
+fn default_port() -> u16 { 8080 }
+fn default_static_dir() -> String { "./static".to_string() }
+
+impl AppConfig {
+    pub fn from_env() -> Result<Self, envy::Error> {
+        dotenvy::dotenv().ok(); // Load .env file if present (not an error if missing)
+        envy::from_env::<AppConfig>()
+    }
+
+    /// Validate that secrets meet minimum requirements
+    pub fn validate(&self) -> Result<(), String> {
+        let key = self.master_encryption_key.expose_secret();
+        if key.len() != 64 || !key.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err("MASTER_ENCRYPTION_KEY must be exactly 64 hex characters".into());
+        }
+        let secret = self.session_secret.expose_secret();
+        if secret.len() < 64 {
+            return Err("SESSION_SECRET must be at least 64 characters".into());
+        }
+        if !self.app_url.starts_with("http://") && !self.app_url.starts_with("https://") {
+            return Err("APP_URL must start with http:// or https://".into());
+        }
+        Ok(())
+    }
+}
+```
+
+**Design notes:**
+
+- `SecretString` from the `secrecy` crate prevents accidental logging of secrets via `Debug` or `Display` traits. The secret is only accessible via `.expose_secret()`.
+- `dotenvy::dotenv().ok()` loads `.env` if present but does not fail if the file is missing (environment variables can be injected by Docker).
+- `validate()` is called at startup. The app refuses to start with invalid configuration rather than failing at runtime.
+
+---
+
+## 3. Database Management
+
+### 3.1 Migration Tooling
+
+**Tool**: `sqlx-cli` (the official SQLX command-line tool).
+
+```bash
+# Install sqlx-cli with Postgres support
+cargo install sqlx-cli --no-default-features --features postgres
+
+# Create the database (if it does not exist)
+sqlx database create
+
+# Run all pending migrations
+sqlx migrate run
+
+# Revert the last migration
+sqlx migrate revert
+
+# Check migration status
+sqlx migrate info
+
+# Prepare offline query data (for Docker builds without a live DB)
+cargo sqlx prepare
+```
+
+### 3.2 Migration Execution Strategy
+
+**Migrations run at application startup** before the HTTP server begins accepting requests.
+
+```rust
+// In main.rs, during initialization
+async fn run_migrations(pool: &PgPool) -> Result<(), sqlx::Error> {
+    tracing::info!("Running database migrations...");
+    sqlx::migrate!("./migrations")
+        .run(pool)
+        .await?;
+    tracing::info!("Migrations complete.");
+    Ok(())
+}
+```
+
+**Rationale**: For a single-instance self-hosted application, running migrations at startup is simple and reliable. There is no risk of multiple instances racing to apply migrations. If a migration fails, the application exits with an error before serving traffic.
+
+**Safeguard**: The `sqlx::migrate!` macro embeds migration files at compile time. If migrations are missing or corrupted, the build fails.
+
+### 3.3 Migration Files (Postgres)
+
+All migrations live in `migrations/` with the naming convention `YYYYMMDDHHMMSS_description.sql`.
+
+```sql
+-- migrations/20260321000001_create_users.sql
+CREATE TABLE users (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email       TEXT NOT NULL UNIQUE,
+    display_name TEXT,
+    role        TEXT NOT NULL DEFAULT 'user' CHECK (role IN ('user', 'admin')),
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX idx_users_email ON users(email);
+```
+
+```sql
+-- migrations/20260321000002_create_sessions.sql
+CREATE TABLE sessions (
+    session_hash TEXT PRIMARY KEY,           -- SHA-256(session_id)
+    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    expires_at  TIMESTAMPTZ NOT NULL,
+    last_active_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    ip_address  TEXT,
+    user_agent  TEXT
+);
+CREATE INDEX idx_sessions_user_id ON sessions(user_id);
+CREATE INDEX idx_sessions_expires_at ON sessions(expires_at);
+```
+
+```sql
+-- migrations/20260321000003_create_magic_tokens.sql
+CREATE TABLE magic_tokens (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email       TEXT NOT NULL,
+    token_hash  TEXT NOT NULL UNIQUE,        -- SHA-256(token)
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    expires_at  TIMESTAMPTZ NOT NULL,
+    used        BOOLEAN NOT NULL DEFAULT false
+);
+CREATE INDEX idx_magic_tokens_email ON magic_tokens(email);
+CREATE INDEX idx_magic_tokens_expires ON magic_tokens(expires_at);
+```
+
+```sql
+-- migrations/20260321000004_create_settings.sql
+CREATE TABLE settings (
+    user_id              UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+    theme                TEXT NOT NULL DEFAULT 'Intelligence Artificielle',
+    max_age_days         INTEGER NOT NULL DEFAULT 7 CHECK (max_age_days BETWEEN 1 AND 365),
+    categories           JSONB NOT NULL DEFAULT '["Annonces majeures", "Recherche et innovation", "Industrie et entreprises", "Secteur public", "Opinions et analyses"]'::jsonb,
+    max_items_per_category INTEGER NOT NULL DEFAULT 4 CHECK (max_items_per_category BETWEEN 1 AND 20),
+    search_agent_behavior TEXT NOT NULL DEFAULT '',
+    ai_provider          TEXT NOT NULL DEFAULT 'gemini',
+    ai_model             TEXT NOT NULL DEFAULT 'gemini-2.5-flash',
+    updated_at           TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+```sql
+-- migrations/20260321000005_create_sources.sql
+CREATE TABLE sources (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    title       TEXT NOT NULL,
+    url         TEXT NOT NULL,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX idx_sources_user_id ON sources(user_id);
+CREATE INDEX idx_sources_user_created ON sources(user_id, created_at DESC);
+```
+
+```sql
+-- migrations/20260321000006_create_syntheses.sql
+CREATE TABLE syntheses (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    week        TEXT NOT NULL,               -- e.g. "2026-W12"
+    sections    JSONB NOT NULL,              -- [{ title, items: [{ title, url, summary }] }]
+    status      TEXT NOT NULL DEFAULT 'completed' CHECK (status IN ('pending', 'in_progress', 'completed', 'failed')),
+    error_message TEXT,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX idx_syntheses_user_id ON syntheses(user_id);
+CREATE INDEX idx_syntheses_user_created ON syntheses(user_id, created_at DESC);
+```
+
+```sql
+-- migrations/20260321000007_create_llm_providers.sql
+-- Admin-configured LLM provider catalog (provider + available models)
+CREATE TABLE llm_providers (
+    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    provider     TEXT NOT NULL UNIQUE CHECK (provider IN ('gemini', 'openai', 'anthropic')),
+    display_name TEXT NOT NULL,
+    models       JSONB NOT NULL,             -- ["gemini-2.5-flash", "gemini-2.5-pro"]
+    is_enabled   BOOLEAN NOT NULL DEFAULT true,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+```sql
+-- migrations/20260321000008_create_user_api_keys.sql
+-- Users bring their own API keys (encrypted at rest)
+CREATE TABLE user_api_keys (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id         UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    provider        TEXT NOT NULL,            -- 'gemini', 'openai', 'anthropic'
+    encrypted_key   BYTEA NOT NULL,           -- AES-256-GCM ciphertext
+    nonce           BYTEA NOT NULL,           -- 12-byte GCM nonce
+    key_prefix      TEXT NOT NULL,            -- First 6 chars for display ("sk-pr...")
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE(user_id, provider)
+);
+CREATE INDEX idx_user_api_keys_user ON user_api_keys(user_id);
+```
+
+```sql
+-- migrations/20260321000009_create_rate_limit_config.sql
+CREATE TABLE rate_limit_config (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    provider        TEXT NOT NULL UNIQUE REFERENCES llm_providers(provider),
+    max_requests    INTEGER NOT NULL DEFAULT 29,
+    time_window_secs INTEGER NOT NULL DEFAULT 60,
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+```sql
+-- migrations/20260321000010_create_audit_log.sql
+CREATE TABLE audit_log (
+    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    timestamp   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    user_id     UUID NOT NULL REFERENCES users(id),
+    action      TEXT NOT NULL,
+    target_type TEXT NOT NULL,
+    target_id   UUID,
+    details     JSONB,
+    ip_address  TEXT,
+    user_agent  TEXT
+);
+CREATE INDEX idx_audit_timestamp ON audit_log(timestamp);
+CREATE INDEX idx_audit_user ON audit_log(user_id);
+```
+
+### 3.4 Backup Strategy
+
+For a single-tenant self-hosted Postgres running in Docker Compose.
+
+**Automated pg_dump via cron on the host:**
+
+```bash
+#!/usr/bin/env bash
+# /opt/ai-synth/backup.sh
+# Run via cron: 0 3 * * * /opt/ai-synth/backup.sh
+
+set -euo pipefail
+
+BACKUP_DIR="/opt/ai-synth/backups"
+RETENTION_DAYS=30
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+BACKUP_FILE="${BACKUP_DIR}/ai_synth_${TIMESTAMP}.sql.gz"
+
+mkdir -p "${BACKUP_DIR}"
+
+# Dump and compress
+docker exec ai-synth-db pg_dump -U ai_synth -d ai_synth \
+    --format=custom \
+    --compress=6 \
+    > "${BACKUP_FILE}"
+
+# Verify backup is not empty
+if [ ! -s "${BACKUP_FILE}" ]; then
+    echo "ERROR: Backup file is empty!" >&2
+    exit 1
+fi
+
+# Remove backups older than RETENTION_DAYS
+find "${BACKUP_DIR}" -name "ai_synth_*.sql.gz" -mtime +${RETENTION_DAYS} -delete
+
+echo "Backup completed: ${BACKUP_FILE} ($(du -h "${BACKUP_FILE}" | cut -f1))"
+```
+
+**Crontab entry:**
+```
+0 3 * * * /opt/ai-synth/backup.sh >> /var/log/ai-synth-backup.log 2>&1
+```
+
+**Restore procedure:**
+```bash
+# Stop the app (to prevent writes during restore)
+docker compose stop app
+
+# Restore from backup
+docker exec -i ai-synth-db pg_restore \
+    -U ai_synth -d ai_synth \
+    --clean --if-exists \
+    < /opt/ai-synth/backups/ai_synth_20260321_030000.sql.gz
+
+# Restart the app
+docker compose start app
+```
+
+**Docker volume backup (alternative):**
+```bash
+# Full volume backup (filesystem level)
+docker run --rm \
+    -v ai-synth_postgres_data:/data:ro \
+    -v /opt/ai-synth/backups:/backup \
+    alpine tar czf /backup/pg_volume_$(date +%Y%m%d).tar.gz -C /data .
+```
+
+### 3.5 Seed Data
+
+After the first deployment and migration, the admin creates the provider catalog. However, a seed command is useful for initial setup.
+
+```rust
+// CLI: ai-weekly-synth seed-providers
+// Inserts default provider entries (without API keys -- users provide their own)
+async fn seed_providers(pool: &PgPool) -> Result<()> {
+    let providers = vec![
+        ("gemini", "Google Gemini", serde_json::json!([
+            "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.0-flash"
+        ])),
+        ("openai", "OpenAI", serde_json::json!([
+            "gpt-4o", "gpt-4o-mini", "o3-mini"
+        ])),
+        ("anthropic", "Anthropic", serde_json::json!([
+            "claude-sonnet-4-20250514", "claude-haiku-3-5-20241022"
+        ])),
+    ];
+
+    for (provider, display_name, models) in providers {
+        sqlx::query!(
+            r#"INSERT INTO llm_providers (provider, display_name, models)
+               VALUES ($1, $2, $3)
+               ON CONFLICT (provider) DO UPDATE SET
+                   display_name = EXCLUDED.display_name,
+                   models = EXCLUDED.models,
+                   updated_at = now()"#,
+            provider, display_name, models
+        )
+        .execute(pool)
+        .await?;
+    }
+
+    Ok(())
+}
+```
+
+---
+
+## 4. CLI Commands
+
+The binary uses `clap` for subcommand parsing. The default subcommand is `serve`.
+
+### 4.1 CLI Structure
+
+```rust
+// src/main.rs
+use clap::{Parser, Subcommand};
+
+#[derive(Parser)]
+#[command(name = "ai-weekly-synth", version, about = "AI Weekly Synth server")]
+struct Cli {
+    #[command(subcommand)]
+    command: Option<Commands>,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Start the web server (default)
+    Serve,
+
+    /// Create an admin user account
+    CreateAdmin {
+        /// Email address for the admin account
+        email: String,
+    },
+
+    /// Run database migrations
+    Migrate,
+
+    /// Seed the LLM provider catalog with defaults
+    SeedProviders,
+
+    /// Check application health (DB connectivity, config validity)
+    HealthCheck,
+
+    /// Re-encrypt all user API keys with a new master key
+    RotateEncryptionKey {
+        /// The new master encryption key (64 hex characters)
+        new_key: String,
+    },
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+
+    match cli.command.unwrap_or(Commands::Serve) {
+        Commands::Serve => run_server().await,
+        Commands::CreateAdmin { email } => create_admin(&email).await,
+        Commands::Migrate => run_migrations_cli().await,
+        Commands::SeedProviders => seed_providers_cli().await,
+        Commands::HealthCheck => health_check_cli().await,
+        Commands::RotateEncryptionKey { new_key } => rotate_key(&new_key).await,
+    }
+}
+```
+
+### 4.2 create-admin Command
+
+Creates an admin user directly in the database. The user can then request a magic link to log in.
+
+```rust
+async fn create_admin(email: &str) -> Result<()> {
+    let config = AppConfig::from_env()?;
+    let pool = PgPool::connect(config.database_url.expose_secret()).await?;
+
+    // Validate email format
+    if !email.contains('@') || email.len() > 255 {
+        anyhow::bail!("Invalid email address: {}", email);
+    }
+
+    // Check if user already exists
+    let existing = sqlx::query!("SELECT id, role FROM users WHERE email = $1", email)
+        .fetch_optional(&pool)
+        .await?;
+
+    match existing {
+        Some(user) if user.role == "admin" => {
+            println!("User {} is already an admin.", email);
+        }
+        Some(user) => {
+            // Promote existing user to admin
+            sqlx::query!("UPDATE users SET role = 'admin', updated_at = now() WHERE id = $1", user.id)
+                .execute(&pool)
+                .await?;
+            println!("User {} promoted to admin.", email);
+        }
+        None => {
+            // Create new admin user
+            sqlx::query!(
+                r#"INSERT INTO users (email, role) VALUES ($1, 'admin')"#,
+                email
+            )
+            .execute(&pool)
+            .await?;
+            println!("Admin user created: {}", email);
+            println!("The user can now log in by requesting a magic link at the login page.");
+        }
+    }
+
+    Ok(())
+}
+```
+
+**Usage:**
+```bash
+# In Docker
+docker exec ai-synth ./ai-weekly-synth create-admin admin@example.com
+
+# Or using docker compose run (for first-time setup before the app is running)
+docker compose run --rm app ./ai-weekly-synth create-admin admin@example.com
+```
+
+### 4.3 Other CLI Commands
+
+**migrate**: Runs pending migrations. Useful for manual control or CI pipelines.
+```bash
+docker compose run --rm app ./ai-weekly-synth migrate
+```
+
+**seed-providers**: Populates the LLM provider catalog with sensible defaults.
+```bash
+docker compose run --rm app ./ai-weekly-synth seed-providers
+```
+
+**health-check**: Verifies DB connectivity, config validity, and Resend API key. Returns exit code 0 on success, 1 on failure.
+```bash
+docker compose run --rm app ./ai-weekly-synth health-check
+```
+
+**rotate-encryption-key**: Re-encrypts all user API keys with a new master key. Used for key rotation.
+```bash
+docker compose run --rm app ./ai-weekly-synth rotate-encryption-key NEW_HEX_KEY
+```
+
+---
+
+## 5. Reverse Proxy & TLS
+
+### 5.1 Recommendation: Caddy
+
+**Caddy** is recommended over nginx for the following reasons:
+
+- Automatic HTTPS with Let's Encrypt (zero configuration for certificate issuance and renewal).
+- Automatic HTTP-to-HTTPS redirect.
+- HTTP/3 support out of the box.
+- Simpler configuration syntax.
+- Runs as a single static binary in an Alpine container (minimal attack surface).
+
+### 5.2 Caddyfile
+
+```
+# Caddyfile
+{
+    email {$ACME_EMAIL:admin@example.com}
+}
+
+{$APP_DOMAIN:synth.example.com} {
+    # Reverse proxy to the Rust app (internal Docker network)
+    reverse_proxy app:8080 {
+        # Health checks so Caddy removes unhealthy backends
+        health_uri /api/v1/health
+        health_interval 30s
+        health_timeout 5s
+    }
+
+    # Compression
+    encode zstd gzip
+
+    # Security headers
+    header {
+        # HSTS (1 year, include subdomains)
+        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
+        # Prevent MIME sniffing
+        X-Content-Type-Options "nosniff"
+        # Prevent clickjacking
+        X-Frame-Options "DENY"
+        # Referrer policy
+        Referrer-Policy "strict-origin-when-cross-origin"
+        # Permissions policy (disable unused APIs)
+        Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=()"
+        # Content Security Policy
+        Content-Security-Policy "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self'; frame-src https://challenges.cloudflare.com; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"
+        # Remove server header
+        -Server
+    }
+
+    # Rate limiting at the reverse proxy level (defense in depth)
+    # Caddy does not have built-in rate limiting; use the app's rate limiter.
+
+    # Logging
+    log {
+        output stdout
+        format json
+    }
+}
+```
+
+**Notes:**
+
+- `{$APP_DOMAIN}` and `{$ACME_EMAIL}` are environment variables. In docker-compose, set these in the `.env` file or the caddy service's environment.
+- The `frame-src https://challenges.cloudflare.com` directive allows the Turnstile captcha widget to load in an iframe.
+- Caddy automatically provisions a TLS certificate from Let's Encrypt for `APP_DOMAIN`. The domain's DNS must point to the server's public IP before starting Caddy.
+- Caddy stores certificates in the `caddy_data` volume. They persist across container restarts and are auto-renewed.
+
+### 5.3 Alternative: nginx Configuration
+
+If nginx is preferred for familiarity or existing infrastructure:
+
+```nginx
+# /etc/nginx/conf.d/ai-synth.conf
+server {
+    listen 80;
+    server_name synth.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name synth.example.com;
+
+    # TLS (managed by certbot)
+    ssl_certificate /etc/letsencrypt/live/synth.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/synth.example.com/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Security headers
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-Frame-Options "DENY" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+    # Proxy to app
+    location / {
+        proxy_pass http://app:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # SSE support (generation progress)
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 120s;
+    }
+
+    # Gzip
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml;
+}
+```
+
+With nginx, TLS certificate management requires certbot:
+```bash
+# Install certbot and obtain initial certificate
+docker run --rm -v certbot_data:/etc/letsencrypt -v certbot_www:/var/www/certbot \
+    certbot/certbot certonly --webroot -w /var/www/certbot \
+    -d synth.example.com --email admin@example.com --agree-tos
+```
+
+**Recommendation**: Use Caddy unless there is a specific reason to use nginx. Caddy eliminates certificate management entirely.
+
+### 5.4 SSE Considerations
+
+The reverse proxy must support Server-Sent Events for the synthesis generation progress stream. Key settings:
+
+- **Caddy**: Works out of the box (no buffering by default for streaming responses).
+- **nginx**: Requires `proxy_buffering off;` and `proxy_cache off;` on the SSE endpoint.
+
+The Rust backend should set `Cache-Control: no-cache`, `Content-Type: text/event-stream`, and `Connection: keep-alive` on SSE responses.
+
+---
+
+## 6. Testing Strategy
+
+### 6.1 Backend Unit Tests
+
+**What to test:**
+
+| Module | What to test | Mocking needed |
+|---|---|---|
+| `config.rs` | Validation logic (key length, URL format, required fields) | No |
+| `services/encryption.rs` | AES-256-GCM encrypt/decrypt roundtrip, key derivation, nonce uniqueness | No |
+| `services/captcha.rs` | Turnstile verification parsing (success, failure, invalid response) | Mock HTTP client |
+| `middleware/rate_limit.rs` | Token bucket logic: allows up to N requests, blocks after limit, resets after window | No (test in-memory state) |
+| `middleware/auth.rs` | Session extraction, hash verification, expiry checks | Mock DB pool |
+| `services/llm/types.rs` | Schema building from user categories | No |
+| `services/scraper.rs` | HTML parsing, date extraction, soft-404 detection, SSRF IP validation | No (test with static HTML) |
+| `models/*` | Serialization/deserialization, validation constraints | No |
+| `services/email.rs` | Email template rendering (magic link, synthesis) | Mock SMTP |
+
+**Test module structure:**
+
+Tests live alongside the code they test (Rust convention):
+
+```rust
+// src/services/encryption.rs
+
+pub fn encrypt_api_key(key: &str, master_key: &[u8; 32]) -> Result<(Vec<u8>, Vec<u8>)> {
+    // ... implementation
+}
+
+pub fn decrypt_api_key(ciphertext: &[u8], nonce: &[u8], master_key: &[u8; 32]) -> Result<String> {
+    // ... implementation
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn encrypt_decrypt_roundtrip() {
+        let master_key = [0xab; 32];
+        let api_key = "sk-proj-abc123def456";
+
+        let (ciphertext, nonce) = encrypt_api_key(api_key, &master_key).unwrap();
+        let decrypted = decrypt_api_key(&ciphertext, &nonce, &master_key).unwrap();
+
+        assert_eq!(decrypted, api_key);
+    }
+
+    #[test]
+    fn decrypt_with_wrong_key_fails() {
+        let master_key = [0xab; 32];
+        let wrong_key = [0xcd; 32];
+        let api_key = "sk-proj-abc123def456";
+
+        let (ciphertext, nonce) = encrypt_api_key(api_key, &master_key).unwrap();
+        let result = decrypt_api_key(&ciphertext, &nonce, &wrong_key);
+
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn each_encryption_produces_unique_nonce() {
+        let master_key = [0xab; 32];
+        let api_key = "sk-proj-abc123def456";
+
+        let (_, nonce1) = encrypt_api_key(api_key, &master_key).unwrap();
+        let (_, nonce2) = encrypt_api_key(api_key, &master_key).unwrap();
+
+        assert_ne!(nonce1, nonce2);
+    }
+}
+```
+
+**Mocking strategy:**
+
+Use trait objects and the `mockall` crate for mocking external dependencies.
+
+```rust
+// Define traits for mockable services
+#[cfg_attr(test, mockall::automock)]
+#[async_trait]
+pub trait EmailService: Send + Sync {
+    async fn send_magic_link(&self, to: &str, token: &str) -> Result<()>;
+    async fn send_synthesis(&self, to: &str, synthesis: &Synthesis) -> Result<()>;
+}
+
+#[cfg_attr(test, mockall::automock)]
+#[async_trait]
+pub trait CaptchaVerifier: Send + Sync {
+    async fn verify(&self, token: &str) -> Result<bool>;
+}
+```
+
+In production, concrete implementations (ResendEmailService, TurnstileCaptchaVerifier) are injected into AppState. In tests, `MockEmailService` and `MockCaptchaVerifier` are used.
+
+### 6.2 Backend Integration Tests
+
+**Test database setup:** Use `testcontainers-rs` to spin up a temporary Postgres container per test suite.
+
+```rust
+// tests/common/mod.rs
+use testcontainers::{clients::Cli, images::postgres::Postgres};
+use sqlx::PgPool;
+
+pub struct TestDb {
+    _container: testcontainers::Container<'static, Postgres>,
+    pub pool: PgPool,
+}
+
+impl TestDb {
+    pub async fn new() -> Self {
+        let docker = Cli::default();
+        let container = docker.run(Postgres::default());
+        let port = container.get_host_port_ipv4(5432);
+        let url = format!("postgres://postgres:postgres@localhost:{}/postgres", port);
+
+        let pool = PgPool::connect(&url).await.unwrap();
+        sqlx::migrate!("./migrations").run(&pool).await.unwrap();
+
+        TestDb {
+            _container: container,
+            pool,
+        }
+    }
+}
+```
+
+**Alternative (faster, less isolation):** Use a single shared Postgres container across tests with per-test schema isolation:
+
+```rust
+pub async fn setup_test_schema(pool: &PgPool) -> String {
+    let schema = format!("test_{}", uuid::Uuid::new_v4().to_string().replace('-', ""));
+    sqlx::query(&format!("CREATE SCHEMA {}", schema)).execute(pool).await.unwrap();
+    sqlx::query(&format!("SET search_path TO {}", schema)).execute(pool).await.unwrap();
+    // Run migrations within the schema...
+    schema
+}
+```
+
+**API endpoint tests:**
+
+Use `axum::test` helpers or `reqwest` against a running test server:
+
+```rust
+// tests/api/auth_test.rs
+use axum::http::StatusCode;
+use axum_test::TestServer;
+
+#[tokio::test]
+async fn register_and_login_flow() {
+    let db = TestDb::new().await;
+    let app = build_test_app(db.pool.clone()).await;
+    let server = TestServer::new(app).unwrap();
+
+    // 1. Register
+    let resp = server
+        .post("/api/v1/auth/register")
+        .json(&json!({
+            "email": "test@example.com",
+            "display_name": "Test User",
+            "captcha_token": "test-token"  // Mock captcha always succeeds in test
+        }))
+        .await;
+    assert_eq!(resp.status_code(), StatusCode::OK);
+
+    // 2. Extract magic token from DB (in production this would be sent via email)
+    let token_row = sqlx::query!("SELECT token_hash FROM magic_tokens WHERE email = 'test@example.com'")
+        .fetch_one(&db.pool)
+        .await
+        .unwrap();
+    // In tests, we also store the raw token for verification
+    let raw_token = get_test_raw_token(&db.pool, "test@example.com").await;
+
+    // 3. Verify magic link
+    let resp = server
+        .get(&format!("/api/v1/auth/verify?token={}", raw_token))
+        .await;
+    assert_eq!(resp.status_code(), StatusCode::FOUND); // 302 redirect
+    let session_cookie = resp.header("set-cookie");
+    assert!(session_cookie.contains("ai_synth_session"));
+
+    // 4. Access protected endpoint
+    let resp = server
+        .get("/api/v1/auth/me")
+        .add_header("cookie", session_cookie.clone())
+        .add_header("x-requested-with", "XMLHttpRequest")
+        .await;
+    assert_eq!(resp.status_code(), StatusCode::OK);
+    let body: serde_json::Value = resp.json();
+    assert_eq!(body["email"], "test@example.com");
+
+    // 5. Logout
+    let resp = server
+        .post("/api/v1/auth/logout")
+        .add_header("cookie", session_cookie)
+        .add_header("x-requested-with", "XMLHttpRequest")
+        .await;
+    assert_eq!(resp.status_code(), StatusCode::OK);
+}
+```
+
+**Generation pipeline tests with mocked LLM:**
+
+```rust
+#[tokio::test]
+async fn generate_synthesis_with_mocked_llm() {
+    let db = TestDb::new().await;
+    let mut mock_provider = MockLlmProvider::new();
+
+    // Mock Pass 1: return structured search results
+    mock_provider
+        .expect_generate_search_pass()
+        .returning(|_, _, _, _| Ok(json!({
+            "category_0": [
+                { "title": "Test Article", "url": "https://example.com/article", "summary": "Test summary" }
+            ]
+        })));
+
+    // Mock Pass 2: return rewritten results
+    mock_provider
+        .expect_generate_rewrite_pass()
+        .returning(|_, _, _, _| Ok(json!({
+            "category_0": [
+                { "title": "Rewritten Title", "url": "https://example.com/article", "summary": "Better summary" }
+            ]
+        })));
+
+    let app = build_test_app_with_provider(db.pool.clone(), Box::new(mock_provider)).await;
+    // ... trigger generation and verify results
+}
+```
+
+**Key integration test scenarios:**
+
+1. Full auth flow: register -> magic link -> verify -> session -> logout
+2. CRUD operations: create/read/update/delete for sources, settings, syntheses
+3. Ownership isolation: user A cannot access user B's data
+4. Admin operations: create admin -> configure providers -> manage rate limits
+5. Rate limiting: verify requests are throttled after exceeding limits
+6. CSRF protection: verify requests without `X-Requested-With` header are rejected
+7. Generation pipeline: full async generation with SSE progress events (mocked LLM)
+8. Email delivery: magic link email rendering (mocked SMTP)
+9. API key encryption: store and retrieve encrypted keys through the API
+
+**Test fixtures:**
+
+```rust
+// tests/fixtures/mod.rs
+pub async fn create_test_user(pool: &PgPool, email: &str) -> User {
+    sqlx::query_as!(
+        User,
+        r#"INSERT INTO users (email, display_name, role)
+           VALUES ($1, 'Test User', 'user')
+           RETURNING *"#,
+        email
+    )
+    .fetch_one(pool)
+    .await
+    .unwrap()
+}
+
+pub async fn create_test_admin(pool: &PgPool, email: &str) -> User {
+    sqlx::query_as!(
+        User,
+        r#"INSERT INTO users (email, display_name, role)
+           VALUES ($1, 'Admin User', 'admin')
+           RETURNING *"#,
+        email
+    )
+    .fetch_one(pool)
+    .await
+    .unwrap()
+}
+
+pub async fn create_test_session(pool: &PgPool, user_id: &Uuid) -> String {
+    let raw_token = generate_session_token();
+    let hash = sha256_hex(&raw_token);
+    sqlx::query!(
+        r#"INSERT INTO sessions (session_hash, user_id, expires_at)
+           VALUES ($1, $2, now() + interval '30 days')"#,
+        hash, user_id
+    )
+    .execute(pool)
+    .await
+    .unwrap();
+    raw_token
+}
+
+pub async fn create_test_synthesis(pool: &PgPool, user_id: &Uuid) -> Synthesis {
+    sqlx::query_as!(
+        Synthesis,
+        r#"INSERT INTO syntheses (user_id, week, sections, status)
+           VALUES ($1, '2026-W12', $2, 'completed')
+           RETURNING *"#,
+        user_id,
+        json!([{ "title": "Test Section", "items": [{ "title": "Article", "url": "https://example.com", "summary": "Summary" }] }])
+    )
+    .fetch_one(pool)
+    .await
+    .unwrap()
+}
+```
+
+### 6.3 Frontend Unit Tests
+
+**Tooling:** Vitest + `@solidjs/testing-library` + `jsdom`
+
+```json
+// frontend/package.json (devDependencies to add)
+{
+  "devDependencies": {
+    "vitest": "^3.0",
+    "@solidjs/testing-library": "^0.8",
+    "@testing-library/jest-dom": "^6.6",
+    "jsdom": "^26.0",
+    "msw": "^2.7"
+  }
+}
+```
+
+```typescript
+// frontend/vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import solidPlugin from 'vite-plugin-solid';
+
+export default defineConfig({
+    plugins: [solidPlugin()],
+    test: {
+        environment: 'jsdom',
+        globals: true,
+        setupFiles: ['./src/test/setup.ts'],
+        transformMode: {
+            web: [/\.tsx?$/],
+        },
+    },
+});
+```
+
+**Component rendering tests:**
+
+```typescript
+// frontend/src/components/__tests__/SourceList.test.tsx
+import { render, screen, fireEvent } from '@solidjs/testing-library';
+import { describe, it, expect, vi } from 'vitest';
+import SourceList from '../SourceList';
+
+describe('SourceList', () => {
+    it('renders a list of sources', () => {
+        const sources = [
+            { id: '1', title: 'TechCrunch', url: 'https://techcrunch.com', created_at: '2026-03-21' },
+            { id: '2', title: 'Ars Technica', url: 'https://arstechnica.com', created_at: '2026-03-21' },
+        ];
+
+        render(() => <SourceList sources={sources} onDelete={vi.fn()} />);
+
+        expect(screen.getByText('TechCrunch')).toBeInTheDocument();
+        expect(screen.getByText('Ars Technica')).toBeInTheDocument();
+    });
+
+    it('calls onDelete when delete button is clicked', async () => {
+        const onDelete = vi.fn();
+        const sources = [
+            { id: '1', title: 'TechCrunch', url: 'https://techcrunch.com', created_at: '2026-03-21' },
+        ];
+
+        render(() => <SourceList sources={sources} onDelete={onDelete} />);
+
+        const deleteButton = screen.getByRole('button', { name: /supprimer/i });
+        await fireEvent.click(deleteButton);
+
+        expect(onDelete).toHaveBeenCalledWith('1');
+    });
+});
+```
+
+**Signal/store logic tests:**
+
+```typescript
+// frontend/src/stores/__tests__/settings.test.ts
+import { describe, it, expect } from 'vitest';
+import { createRoot } from 'solid-js';
+import { createSettingsStore } from '../settings';
+
+describe('Settings Store', () => {
+    it('initializes with default categories', () => {
+        createRoot((dispose) => {
+            const [settings] = createSettingsStore();
+            expect(settings.categories.length).toBe(5);
+            expect(settings.categories[0]).toBe('Annonces majeures');
+            dispose();
+        });
+    });
+
+    it('validates max categories limit', () => {
+        createRoot((dispose) => {
+            const [settings, { addCategory }] = createSettingsStore();
+            // Fill up to 20 categories
+            for (let i = 0; i < 20; i++) {
+                addCategory(`Category ${i}`);
+            }
+            expect(() => addCategory('Category 21')).toThrow();
+            dispose();
+        });
+    });
+});
+```
+
+**API client tests (MSW for mocking):**
+
+```typescript
+// frontend/src/lib/__tests__/api.test.ts
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
+import { setupServer } from 'msw/node';
+import { http, HttpResponse } from 'msw';
+import { fetchApi } from '../api';
+
+const server = setupServer(
+    http.get('/api/v1/syntheses', () => {
+        return HttpResponse.json([
+            { id: '1', week: '2026-W12', created_at: '2026-03-21T10:00:00Z', sections: [] },
+        ]);
+    }),
+    http.get('/api/v1/auth/me', () => {
+        return HttpResponse.json({
+            id: '1',
+            email: 'test@example.com',
+            display_name: 'Test User',
+            role: 'user',
+        });
+    }),
+    http.post('/api/v1/auth/logout', () => {
+        return HttpResponse.json({ message: 'Logged out' });
+    }),
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+describe('fetchApi', () => {
+    it('fetches syntheses list', async () => {
+        const data = await fetchApi('/api/v1/syntheses');
+        expect(data).toHaveLength(1);
+        expect(data[0].week).toBe('2026-W12');
+    });
+
+    it('throws on 401 unauthorized', async () => {
+        server.use(
+            http.get('/api/v1/syntheses', () => {
+                return new HttpResponse(null, { status: 401 });
+            }),
+        );
+        await expect(fetchApi('/api/v1/syntheses')).rejects.toThrow();
+    });
+});
+```
+
+**SSE handling tests:**
+
+```typescript
+// frontend/src/lib/__tests__/sse.test.ts
+import { describe, it, expect, vi } from 'vitest';
+import { createRoot } from 'solid-js';
+import { createGenerationStream } from '../sse';
+
+describe('SSE Generation Stream', () => {
+    it('parses progress events correctly', () => {
+        createRoot((dispose) => {
+            const mockEventSource = {
+                addEventListener: vi.fn(),
+                close: vi.fn(),
+            };
+            vi.stubGlobal('EventSource', vi.fn(() => mockEventSource));
+
+            const [status] = createGenerationStream('job-123');
+
+            // Simulate SSE events
+            const onMessage = mockEventSource.addEventListener.mock.calls.find(
+                ([event]: [string]) => event === 'progress'
+            )?.[1];
+
+            onMessage?.({ data: JSON.stringify({ step: 'search', progress: 0.5 }) });
+            expect(status().step).toBe('search');
+            expect(status().progress).toBe(0.5);
+
+            dispose();
+        });
+    });
+});
+```
+
+### 6.4 End-to-End Tests
+
+**Tool: Playwright**
+
+Playwright is recommended over Cypress for its multi-browser support, better TypeScript integration, and built-in auto-waiting.
+
+```typescript
+// e2e/playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+    testDir: './e2e/tests',
+    fullyParallel: false,  // Tests share state (auth), run sequentially
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 2 : 0,
+    workers: 1,
+    reporter: process.env.CI ? 'github' : 'html',
+    use: {
+        baseURL: process.env.E2E_BASE_URL || 'http://localhost:3000',
+        trace: 'on-first-retry',
+        screenshot: 'only-on-failure',
+    },
+    projects: [
+        { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    ],
+    webServer: process.env.CI ? undefined : {
+        command: 'docker compose -f docker-compose.yml -f docker-compose.e2e.yml up',
+        url: 'http://localhost:3000',
+        reuseExistingServer: true,
+        timeout: 120_000,
+    },
+});
+```
+
+**Key E2E scenarios:**
+
+```typescript
+// e2e/tests/auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Authentication Flow', () => {
+    test('register new account and login via magic link', async ({ page }) => {
+        await page.goto('/login');
+
+        // Fill registration form
+        await page.fill('[name="email"]', 'e2e-test@example.com');
+        await page.fill('[name="displayName"]', 'E2E Test User');
+        // Turnstile is configured to auto-pass in test mode
+        await page.click('button:has-text("Créer un compte")');
+
+        // Verify success message
+        await expect(page.locator('text=Un lien de connexion a été envoyé')).toBeVisible();
+
+        // Extract magic link from Mailpit API
+        const magicLink = await getMagicLinkFromMailpit('e2e-test@example.com');
+
+        // Click the magic link
+        await page.goto(magicLink);
+
+        // Should be redirected to dashboard
+        await expect(page).toHaveURL('/');
+        await expect(page.locator('text=E2E Test User')).toBeVisible();
+    });
+
+    test('logout clears session', async ({ page }) => {
+        // Login first (helper)
+        await loginAsTestUser(page);
+
+        // Click logout
+        await page.click('button:has-text("Déconnexion")');
+
+        // Should be redirected to login
+        await expect(page).toHaveURL('/login');
+    });
+});
+```
+
+```typescript
+// e2e/tests/synthesis.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Synthesis Generation', () => {
+    test.beforeEach(async ({ page }) => {
+        await loginAsTestUser(page);
+    });
+
+    test('create source and generate synthesis', async ({ page }) => {
+        // Add a source
+        await page.goto('/sources');
+        await page.fill('[name="title"]', 'TechCrunch');
+        await page.fill('[name="url"]', 'https://techcrunch.com');
+        await page.click('button:has-text("Ajouter")');
+        await expect(page.locator('text=TechCrunch')).toBeVisible();
+
+        // Trigger generation
+        await page.goto('/generate');
+        await page.click('button:has-text("Nouvelle synthèse")');
+
+        // Wait for SSE progress (generation is async)
+        await expect(page.locator('[data-testid="generation-progress"]')).toBeVisible({ timeout: 10_000 });
+
+        // Wait for completion (in E2E with mocked LLM, this is fast)
+        await expect(page.locator('text=Synthèse terminée')).toBeVisible({ timeout: 30_000 });
+
+        // Verify synthesis appears in list
+        await page.goto('/');
+        await expect(page.locator('[data-testid="synthesis-card"]')).toHaveCount(1);
+    });
+});
+```
+
+```typescript
+// e2e/tests/admin.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Admin Configuration', () => {
+    test.beforeEach(async ({ page }) => {
+        await loginAsAdmin(page);
+    });
+
+    test('admin configures LLM providers', async ({ page }) => {
+        await page.goto('/admin/providers');
+
+        // Verify seeded providers appear
+        await expect(page.locator('text=Google Gemini')).toBeVisible();
+        await expect(page.locator('text=OpenAI')).toBeVisible();
+        await expect(page.locator('text=Anthropic')).toBeVisible();
+
+        // Toggle a provider off
+        const openaiToggle = page.locator('[data-provider="openai"] input[type="checkbox"]');
+        await openaiToggle.uncheck();
+
+        // Verify it saves
+        await page.reload();
+        await expect(openaiToggle).not.toBeChecked();
+    });
+});
+```
+
+**Running E2E tests in Docker:**
+
+```yaml
+# docker-compose.e2e.yml
+services:
+  app:
+    environment:
+      # Use test Turnstile keys (always pass)
+      - TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
+      - TURNSTILE_SITE_KEY=1x00000000000000000000AA
+      # Point to Mailpit for email
+      - RESEND_API_KEY=test-key
+      - EMAIL_SMTP_HOST=mailpit
+      - EMAIL_SMTP_PORT=1025
+      # Use a mocked LLM provider for fast, deterministic tests
+      - LLM_MOCK_MODE=true
+
+  playwright:
+    image: mcr.microsoft.com/playwright:v1.50.0-noble
+    container_name: ai-synth-e2e
+    working_dir: /app
+    command: ["npx", "playwright", "test"]
+    volumes:
+      - ./e2e:/app/e2e
+      - ./frontend:/app/frontend
+      - playwright_results:/app/test-results
+    environment:
+      - E2E_BASE_URL=http://caddy:443
+      - MAILPIT_API_URL=http://mailpit:8025
+    depends_on:
+      app:
+        condition: service_healthy
+    networks:
+      - internal
+
+volumes:
+  playwright_results:
+    driver: local
+```
+
+### 6.5 Test Summary Table
+
+| Layer | Tool | What | Run Command |
+|---|---|---|---|
+| Backend Unit | `cargo test` | Encryption, parsing, validation, rate limiting | `cargo test --lib` |
+| Backend Integration | `cargo test` + testcontainers | API endpoints, auth flows, DB operations | `cargo test --test '*'` |
+| Frontend Unit | Vitest | Components, signals, stores | `cd frontend && npm test` |
+| Frontend Integration | Vitest + MSW | API client, SSE, auth context | `cd frontend && npm test` |
+| E2E | Playwright | Full user flows | `npx playwright test` |
+
+---
+
+## 7. CI/CD Pipeline
+
+### 7.1 GitHub Actions Workflow
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  SQLX_OFFLINE: true
+
+jobs:
+  # =============================================
+  # Backend: Lint + Test
+  # =============================================
+  backend-check:
+    name: Backend Lint & Test
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - name: Cache cargo registry & build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: cargo-${{ runner.os }}-
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Run clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+      - name: Run unit tests
+        run: cargo test --lib
+
+      - name: Run integration tests
+        env:
+          DATABASE_URL: postgres://test:test@localhost:5432/test
+          MASTER_ENCRYPTION_KEY: "0000000000000000000000000000000000000000000000000000000000000000"
+          SESSION_SECRET: "0000000000000000000000000000000000000000000000000000000000000000"
+          APP_URL: "http://localhost:8080"
+          RESEND_API_KEY: "re_test"
+          EMAIL_FROM: "test@test.com"
+          TURNSTILE_SECRET_KEY: "1x0000000000000000000000000000000AA"
+          TURNSTILE_SITE_KEY: "1x00000000000000000000AA"
+        run: cargo test --test '*'
+
+      - name: Security audit
+        run: |
+          cargo install cargo-audit --locked
+          cargo audit
+
+  # =============================================
+  # Frontend: Lint + Test
+  # =============================================
+  frontend-check:
+    name: Frontend Lint & Test
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run ESLint
+        run: npm run lint
+
+      - name: Run type check
+        run: npx tsc --noEmit
+
+      - name: Run unit & integration tests
+        run: npm test -- --run
+
+      - name: Build (verify production build works)
+        run: npm run build
+
+      - name: Security audit
+        run: npm audit --audit-level=high
+
+  # =============================================
+  # Docker: Build image
+  # =============================================
+  docker-build:
+    name: Build Docker Image
+    runs-on: ubuntu-latest
+    needs: [backend-check, frontend-check]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build image (no push)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: false
+          tags: ai-weekly-synth:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  # =============================================
+  # Docker: Push image on main
+  # =============================================
+  docker-push:
+    name: Push Docker Image
+    runs-on: ubuntu-latest
+    needs: [docker-build]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:latest
+            ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+### 7.2 Caching Strategy
+
+| What | Cache key | Tool |
+|---|---|---|
+| Cargo registry + git index | `cargo-{os}-{hash(Cargo.lock)}` | `actions/cache` |
+| Cargo target (compiled deps) | Included in the cargo cache above | `actions/cache` |
+| npm node_modules | `{os}-node-{hash(package-lock.json)}` | `actions/setup-node` built-in cache |
+| Docker layers | GitHub Actions cache backend (`type=gha`) | `docker/build-push-action` |
+
+**cargo-chef in CI**: The Dockerfile already uses cargo-chef, so Docker layer caching handles Rust dependency caching for the image build step. The separate `backend-check` job caches cargo artifacts via `actions/cache` for the lint+test steps.
+
+### 7.3 Optional: E2E Tests in CI
+
+```yaml
+  # Add this job to the workflow when E2E tests are ready
+  e2e:
+    name: End-to-End Tests
+    runs-on: ubuntu-latest
+    needs: [docker-build]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Start services
+        run: docker compose -f docker-compose.yml -f docker-compose.e2e.yml up -d --wait
+
+      - name: Run Playwright tests
+        run: docker compose -f docker-compose.yml -f docker-compose.e2e.yml run --rm playwright
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: test-results/
+
+      - name: Stop services
+        if: always()
+        run: docker compose -f docker-compose.yml -f docker-compose.e2e.yml down -v
+```
+
+---
+
+## 8. Monitoring & Observability
+
+### 8.1 Structured Logging
+
+Use the `tracing` crate with JSON output for machine-parseable logs.
+
+```rust
+// src/main.rs
+use tracing_subscriber::{fmt, prelude::*, EnvFilter};
+
+fn init_tracing() {
+    tracing_subscriber::registry()
+        .with(EnvFilter::from_default_env())  // Reads RUST_LOG
+        .with(
+            fmt::layer()
+                .json()                        // JSON output
+                .with_target(true)             // Include module path
+                .with_thread_ids(false)
+                .with_file(true)
+                .with_line_number(true)
+        )
+        .init();
+}
+```
+
+**Sensitive data filtering**: Never log API keys, session tokens, or email addresses. Use the `secrecy` crate's `SecretString` which implements `Debug` as `Secret([REDACTED])`.
+
+```rust
+// Example: structured log for a generation request
+tracing::info!(
+    user_id = %user.id,
+    provider = %settings.ai_provider,
+    model = %settings.ai_model,
+    categories_count = settings.categories.len(),
+    "Starting synthesis generation"
+);
+```
+
+### 8.2 Health Check Endpoint
+
+```rust
+// src/handlers/health.rs
+
+#[derive(Serialize)]
+pub struct HealthResponse {
+    status: &'static str,
+    version: &'static str,
+    database: &'static str,
+    uptime_seconds: u64,
+}
+
+pub async fn health_check(State(state): State<AppState>) -> impl IntoResponse {
+    let db_ok = sqlx::query("SELECT 1")
+        .execute(&state.pool)
+        .await
+        .is_ok();
+
+    let status = if db_ok { "healthy" } else { "degraded" };
+    let db_status = if db_ok { "connected" } else { "disconnected" };
+    let http_status = if db_ok { StatusCode::OK } else { StatusCode::SERVICE_UNAVAILABLE };
+
+    (
+        http_status,
+        Json(HealthResponse {
+            status,
+            version: env!("CARGO_PKG_VERSION"),
+            database: db_status,
+            uptime_seconds: state.start_time.elapsed().as_secs(),
+        }),
+    )
+}
+```
+
+### 8.3 Key Metrics to Monitor
+
+| Metric | Source | What it tells you |
+|---|---|---|
+| HTTP request count & latency (by route, status) | Tower middleware or tracing spans | Overall API health, slow endpoints |
+| Generation duration (P50, P95, P99) | Timed spans in synthesis service | LLM API performance |
+| Generation success/failure rate | Logged events | LLM reliability |
+| Active sessions count | Periodic DB query | User engagement |
+| Rate limiter rejections | Rate limiter middleware logs | Abuse detection |
+| Auth endpoint error rate | Handler logs | Brute-force attempts |
+| Database query latency | sqlx instrumentation | DB performance |
+| Scraper success/failure rate | Scraper service logs | Target site availability |
+| Memory/CPU usage | Docker stats / cAdvisor | Resource planning |
+
+### 8.4 Lightweight Monitoring Stack (Optional)
+
+For a self-hosted deployment, a lightweight monitoring stack can be added as optional docker-compose services:
+
+```yaml
+# docker-compose.monitoring.yml (optional override)
+services:
+  # Metrics collection
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: ai-synth-prometheus
+    volumes:
+      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus_data:/prometheus
+    networks:
+      - internal
+    profiles:
+      - monitoring
+
+  # Dashboard
+  grafana:
+    image: grafana/grafana:latest
+    container_name: ai-synth-grafana
+    environment:
+      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD:-admin}
+    volumes:
+      - grafana_data:/var/lib/grafana
+    ports:
+      - "3001:3000"
+    networks:
+      - internal
+    profiles:
+      - monitoring
+
+  # Log aggregation (lightweight alternative to ELK)
+  loki:
+    image: grafana/loki:latest
+    container_name: ai-synth-loki
+    volumes:
+      - loki_data:/loki
+    networks:
+      - internal
+    profiles:
+      - monitoring
+
+volumes:
+  prometheus_data:
+  grafana_data:
+  loki_data:
+```
+
+**Simpler alternative**: For most self-hosted deployments, structured JSON logs piped to `docker logs` and monitored with `docker stats` are sufficient. Add Prometheus/Grafana only if operational visibility becomes a need.
+
+**Exposing Prometheus metrics from the Rust app:**
+
+Use the `metrics` crate with `metrics-exporter-prometheus`:
+
+```rust
+// In router setup
+use metrics_exporter_prometheus::PrometheusBuilder;
+
+let prometheus_handle = PrometheusBuilder::new()
+    .install_recorder()
+    .expect("failed to install Prometheus recorder");
+
+// Add a /metrics endpoint (not exposed externally, only on internal network)
+Router::new()
+    .route("/metrics", get(move || async move { prometheus_handle.render() }))
+```
+
+---
+
+## 9. Documentation
+
+### 9.1 README.md Structure
+
+```
+# AI Weekly Synth
+
+AI-powered weekly news synthesis generator. Self-hosted, multi-provider (Gemini, OpenAI, Anthropic).
+
+## Features
+- ...
+
+## Quick Start (Docker)
+1. Clone the repository
+2. Copy .env.example to .env and configure
+3. docker compose up -d
+4. Create admin: docker compose run --rm app ./ai-weekly-synth create-admin admin@example.com
+5. Open https://your-domain.com
+
+## Documentation
+- [Deployment Guide](docs/deployment.md)
+- [Admin Guide](docs/admin-guide.md)
+- [Developer Guide](docs/developer-guide.md)
+- [Architecture Overview](docs/architecture.md)
+
+## Tech Stack
+- Backend: Rust (Axum) + Postgres
+- Frontend: SolidJS + Tailwind CSS
+- Infrastructure: Docker, Caddy, Resend
+
+## License
+[TBD]
+```
+
+### 9.2 Deployment Guide Outline
+
+```
+# Deployment Guide
+
+## Prerequisites
+- Linux server (2 GB RAM minimum, 10 GB disk)
+- Docker Engine 24+ and Docker Compose v2
+- Domain name with DNS pointing to the server
+- Resend account (free tier: 3,000 emails/month)
+- Cloudflare Turnstile keys (free)
+
+## Step-by-Step Deployment
+1. Clone the repository
+2. Configure environment variables (.env)
+3. Configure domain (Caddyfile)
+4. Start the stack: docker compose up -d
+5. Run initial setup:
+   - docker compose run --rm app ./ai-weekly-synth migrate
+   - docker compose run --rm app ./ai-weekly-synth seed-providers
+   - docker compose run --rm app ./ai-weekly-synth create-admin admin@example.com
+6. Verify: open https://your-domain.com
+
+## DNS Configuration
+- A record: your-domain.com -> server IP
+- Resend domain verification (SPF, DKIM)
+
+## Updating
+1. git pull
+2. docker compose build
+3. docker compose up -d
+   (Migrations run automatically on startup)
+
+## Troubleshooting
+- Check logs: docker compose logs app
+- Check health: curl https://your-domain.com/api/v1/health
+- Database: docker exec -it ai-synth-db psql -U ai_synth
+```
+
+### 9.3 Admin Guide Outline
+
+```
+# Admin Guide
+
+## First-Time Setup
+1. Create your admin account (CLI command)
+2. Log in via magic link
+3. Navigate to Admin > Providers
+4. Configure at least one LLM provider (enable/disable, set models)
+5. Configure rate limits (optional, defaults are sensible)
+
+## Managing Providers
+- Enable/disable providers
+- Update available model list
+- Rate limit configuration per provider
+
+## Managing Users
+- View all registered users
+- Promote/demote admin role
+- Revoke user sessions (security response)
+
+## Backups
+- Automated daily backups (cron)
+- Manual backup: ./backup.sh
+- Restore procedure
+
+## Monitoring
+- Health endpoint: /api/v1/health
+- Logs: docker compose logs -f app
+- Database size: docker exec ai-synth-db psql -U ai_synth -c "SELECT pg_size_pretty(pg_database_size('ai_synth'))"
+
+## Security
+- Rotating the master encryption key
+- Rotating the session secret
+- Updating Caddy/Postgres/app images
+```
+
+### 9.4 Developer Guide Outline
+
+```
+# Developer Guide
+
+## Prerequisites
+- Rust 1.85+ (rustup)
+- Node.js 22+ (nvm recommended)
+- Docker (for Postgres and Mailpit)
+- sqlx-cli: cargo install sqlx-cli --no-default-features --features postgres
+
+## Local Development Setup
+1. Start Postgres and Mailpit (Docker)
+2. Copy .env.example to .env, set DATABASE_URL
+3. Run migrations: sqlx migrate run
+4. Start backend: cargo watch -x 'run -- serve'
+5. Start frontend: cd frontend && npm install && npm run dev
+6. Open http://localhost:3000
+
+## Project Structure
+(Directory tree with descriptions)
+
+## Running Tests
+- Backend unit: cargo test --lib
+- Backend integration: cargo test --test '*'
+- Frontend: cd frontend && npm test
+- E2E: npx playwright test
+
+## Database
+- Creating a migration: sqlx migrate add description
+- Running migrations: sqlx migrate run
+- Preparing offline data: cargo sqlx prepare
+
+## Code Conventions
+- Rust: follow clippy warnings, use thiserror for errors
+- Frontend: ESLint config, Tailwind class ordering
+- Commits: conventional commits format
+
+## Adding a New LLM Provider
+1. Implement the LlmProvider trait in src/services/llm/
+2. Register in the provider factory
+3. Add provider to the migration seed
+4. Update frontend provider selector
+```
+
+---
+
+## 10. Security Hardening Checklist
+
+### Docker
+
+- [ ] Non-root user in Dockerfile (`USER appuser`)
+- [ ] Read-only root filesystem (`read_only: true`) with tmpfs for `/tmp`
+- [ ] No secrets baked into the image (all via env vars at runtime)
+- [ ] `no-new-privileges:true` security option
+- [ ] `cap_drop: ALL` (drop all Linux capabilities)
+- [ ] `.dockerignore` excludes `.env`, `.git`, `target/`, sensitive files
+- [ ] Base images pinned to specific versions (not just `:latest`)
+- [ ] Multi-stage build (no compiler, source code, or build tools in runtime image)
+
+### Postgres
+
+- [ ] Strong random password (minimum 32 characters)
+- [ ] Not exposed to host network in production (only on internal Docker network)
+- [ ] No default `postgres` superuser password (use application-specific user)
+- [ ] Health check configured
+- [ ] Persistent volume for data
+- [ ] Regular backups with tested restore procedure
+
+### TLS / HTTPS
+
+- [ ] HTTPS everywhere (Caddy with automatic Let's Encrypt)
+- [ ] HTTP automatically redirected to HTTPS
+- [ ] HSTS header with `max-age=31536000; includeSubDomains`
+- [ ] TLS 1.2+ only (Caddy default)
+- [ ] The Rust app only listens on internal network, not exposed directly
+
+### Security Headers
+
+- [ ] `Content-Security-Policy` (restrictive, script-src 'self')
+- [ ] `X-Frame-Options: DENY`
+- [ ] `X-Content-Type-Options: nosniff`
+- [ ] `Referrer-Policy: strict-origin-when-cross-origin`
+- [ ] `Permissions-Policy` disabling unused browser APIs
+- [ ] `Strict-Transport-Security` (set by Caddy)
+- [ ] Server header removed (Caddy's `-Server`)
+
+### Authentication & Sessions
+
+- [ ] Session cookies: `HttpOnly`, `Secure`, `SameSite=Lax`, `Path=/`
+- [ ] Session IDs: 32 bytes cryptographic random, SHA-256 hashed in DB
+- [ ] Magic link tokens: 32 bytes random, 15-minute expiry, single-use, hashed in DB
+- [ ] Account enumeration prevention (identical responses for existing/non-existing emails)
+- [ ] CSRF protection via `X-Requested-With` header requirement on mutating requests
+- [ ] 30-day session expiration
+- [ ] Logout invalidates server-side session
+
+### Rate Limiting
+
+- [ ] Auth endpoints: `POST /auth/register` 3/hour per IP, `POST /auth/login` 5/15min per IP, 3/hour per email
+- [ ] Generation endpoint: 3/hour per user
+- [ ] General API: 120 reads/min per user, 30 writes/min per user
+- [ ] Global rate limit as DDoS protection
+
+### Data Protection
+
+- [ ] User LLM API keys encrypted at rest with AES-256-GCM
+- [ ] Master encryption key in environment variable, never in code or logs
+- [ ] API keys never sent to frontend (only key prefix for display)
+- [ ] `secrecy` crate wrapping all sensitive values (prevents accidental logging)
+- [ ] Parameterized SQL queries everywhere (sqlx compile-time checking)
+- [ ] User data strictly isolated (`WHERE user_id = $1` on every query)
+
+### SSRF Prevention (URL Scraping)
+
+- [ ] Block private IP ranges (10.x, 172.16.x, 192.168.x, 127.x, 169.254.169.254)
+- [ ] Only allow `http://` and `https://` schemes
+- [ ] Connection timeout: 5s, response timeout: 15s, total: 30s
+- [ ] Response size limit: 5 MB
+- [ ] Redirect limit: 3 hops, each validated against IP blocklist
+
+### Dependency Security
+
+- [ ] `cargo audit` in CI (checks for known vulnerabilities in Rust dependencies)
+- [ ] `npm audit` in CI (checks for known vulnerabilities in npm packages)
+- [ ] Dependabot or Renovate configured for automated dependency updates
+- [ ] No `unsafe` blocks unless absolutely necessary and audited
+
+### Input Validation
+
+- [ ] All request bodies validated with `serde` + `validator` crate
+- [ ] URL inputs validated (scheme allowlist, length limit)
+- [ ] User prompt inputs length-limited
+- [ ] File upload size limits (CSV import)
+- [ ] LLM-generated content treated as untrusted (no `innerHTML`)
+
+### Operational
+
+- [ ] `.env` file permissions `600` (owner read/write only)
+- [ ] Secrets never passed as CLI arguments
+- [ ] Secrets never logged
+- [ ] Audit log for admin actions (append-only)
+- [ ] Backup encryption for off-site storage
+- [ ] Periodic backup restore testing
+
+---
+
+## Appendix: First-Time Deployment Checklist
+
+This is the step-by-step sequence for deploying AI Weekly Synth for the first time.
+
+```
+1. Provision a Linux server (2+ GB RAM, Docker installed)
+2. Point your domain DNS A record to the server IP
+3. Clone the repository
+4. Create .env from .env.example:
+   - Generate MASTER_ENCRYPTION_KEY: openssl rand -hex 32
+   - Generate SESSION_SECRET: openssl rand -hex 32
+   - Generate POSTGRES_PASSWORD: openssl rand -hex 24
+   - Set APP_URL to https://your-domain.com
+   - Set RESEND_API_KEY from Resend dashboard
+   - Set EMAIL_FROM (must match verified Resend domain)
+   - Set TURNSTILE_SECRET_KEY and TURNSTILE_SITE_KEY from Cloudflare dashboard
+5. Update Caddyfile: replace synth.example.com with your domain
+6. chmod 600 .env
+7. docker compose up -d
+8. Wait for healthy status: docker compose ps
+9. Create admin: docker compose run --rm app ./ai-weekly-synth create-admin your@email.com
+10. Seed providers: docker compose run --rm app ./ai-weekly-synth seed-providers
+11. Open https://your-domain.com, request a magic link, log in
+12. Go to Admin > Providers, verify the provider catalog
+13. Set up backup cron: crontab -e -> add the backup.sh entry
+14. Verify backup: run backup.sh manually, check the file was created
+```