ai_synth/docs/superpowers/specs/2026-03-26-multi-theme-design.md

Design: Multi-Theme Synthesis Support

Date: 2026-03-26 Scope: Allow users to create multiple themes, each with its own content settings and sources, generating syntheses per theme.

---

Context

Currently each user has a single theme with one set of categories. Users who follow multiple topics (e.g. AI + Cybersecurity) must choose one or regenerate with different settings. This feature adds support for multiple themes per user.

---

1. Data Model

New table: themes

CREATE TABLE themes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    name TEXT NOT NULL,
    theme TEXT NOT NULL,
    categories JSONB NOT NULL DEFAULT '[]',
    max_items_per_category INTEGER NOT NULL DEFAULT 4,
    max_age_days INTEGER NOT NULL DEFAULT 7,
    summary_length INTEGER NOT NULL DEFAULT 3,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_themes_user_id ON themes(user_id);

Modified table: sources

Add theme_id UUID REFERENCES themes(id) ON DELETE CASCADE. Sources become per-theme.

Modified table: syntheses

Add theme_id UUID REFERENCES themes(id) ON DELETE SET NULL. Links each synthesis to its theme. SET NULL preserves syntheses when a theme is deleted.

Modified table: settings

Remove columns that move to themes: theme, categories, max_items_per_category, max_age_days, summary_length.

Migration strategy

1. Create themes table
2. For each user with settings, create a default theme from their current content settings
3. Add theme_id to sources, populate with the user's default theme
4. Add theme_id to syntheses, populate with the user's default theme
5. Drop moved columns from settings

---

2. Backend API

New endpoints — Themes CRUD

• GET /api/v1/themes — list user's themes
• POST /api/v1/themes — create a new theme
• PUT /api/v1/themes/:id — update a theme
• DELETE /api/v1/themes/:id — delete a theme (syntheses kept with theme_id = NULL)

Modified endpoints

• GET /api/v1/sources — add optional ?theme_id= filter
• POST /api/v1/sources — require theme_id in request body
• POST /api/v1/syntheses/generate — require theme_id in request body
• GET /api/v1/syntheses — response includes theme_name. Add optional ?sort=date|theme param.

Pipeline change

run_generation_inner receives theme_id and loads content settings (theme, categories, max_items, max_age, summary_length) from the themes table instead of settings. Global settings (provider, models, batch_size, rate limits, etc.) still come from settings.

---

3. Frontend — "Personnaliser les syntheses" page

Navigation rename

"Sources personnalisees" → "Personnaliser les syntheses"

Page layout

1. Theme selector — dropdown listing all user themes + "Creer un nouveau theme" button
2. Content settings — theme name, search topic, categories (add/remove), max age, max items, summary length slider. Moved from Settings page.
3. Sources — existing sources list, filtered by selected theme. Add/delete/bulk import scoped to current theme.
4. Delete theme — danger button with confirmation.

Settings page changes

Remove the "Contenu" section. Keep: Sources (pipeline tuning), Intelligence Artificielle, Performance, Import/Export.

---

4. Frontend — Home page enhancements

• Theme badge on synthesis cards (below week label). "Theme supprime" for null theme_id.
• Sort toggle: "Trier par: Date | Theme". Default: Date. Theme sort groups by theme name.
• Generate page: theme dropdown before "Generate" button. Pre-selects last used theme.

---

5. Implementation phases

Phase	Scope	Dependencies
1	Data model + backend API (migrations, themes CRUD, pipeline)	None
2	Theme management page (new page, move content settings)	Phase 1
3	Generation with theme (generate page dropdown)	Phase 1
4	Home page enhancements (theme badge, sort)	Phase 1

Each phase produces working software. Phases 2-4 can be done in any order after Phase 1.

---

Files overview

Phase 1 (Backend)

• Create: backend/migrations/20260326000028_create_themes.sql
• Create: backend/src/db/themes.rs
• Create: backend/src/models/theme.rs
• Create: backend/src/handlers/themes.rs
• Modify: backend/src/db/mod.rs, backend/src/models/mod.rs, backend/src/handlers/mod.rs
• Modify: backend/src/router.rs — add theme routes
• Modify: backend/src/db/sources.rs — add theme_id filter
• Modify: backend/src/db/syntheses.rs — add theme_id, theme_name to queries
• Modify: backend/src/models/settings.rs — remove moved fields
• Modify: backend/src/db/settings.rs — remove moved columns from queries
• Modify: backend/src/services/synthesis.rs — load content settings from theme
• Modify: backend/src/handlers/generation.rs — accept theme_id

Phase 2 (Theme page)

• Create: frontend/src/pages/ThemeManager.tsx
• Create: frontend/src/api/themes.ts
• Modify: frontend/src/App.tsx — routes
• Modify: frontend/src/components/Navbar.tsx — rename nav item
• Modify: frontend/src/pages/Settings.tsx — remove Contenu section
• Modify: frontend/src/i18n/fr.ts — labels

Phase 3 (Generate)

• Modify: frontend/src/pages/GenerateSynthesis.tsx — theme dropdown
• Modify: frontend/src/api/syntheses.ts — pass theme_id

Phase 4 (Home)

• Modify: frontend/src/pages/Home.tsx — theme badge, sort
• Modify: frontend/src/types.ts — add theme fields to types