ai_synth/docs/superpowers/specs/2026-03-27-preferred-sources-design.md

Design: Preferred Sources

Date: 2026-03-27 Scope: Allow users to mark sources as preferred so they are processed first during synthesis generation.

---

1. Data Model

Add is_preferred BOOLEAN NOT NULL DEFAULT false to the sources table. All existing sources default to non-preferred.

Bulk update endpoint: PUT /api/v1/sources/preferred with body { "source_ids": ["uuid1", "uuid2"] }. Sets the listed sources to preferred = true and all others (for the same user) to false. This is an idempotent "set the full list" operation.

---

2. Pipeline Shuffle

Source ordering (before wave chunking)

After rotate_sources, split into preferred and non-preferred, preserving rotation order within each group:

rotated = rotate_sources(all_sources)
preferred = rotated.filter(is_preferred)
non_preferred = rotated.filter(!is_preferred)
ordered = preferred ++ non_preferred
waves = ordered.chunks(window_size)

Preferred sources are processed in earlier waves, maximizing their chance of filling the synthesis.

URL shuffle (within each wave)

After extracting links from a wave's sources, split candidate URLs by whether their source was preferred:

preferred_urls = wave_urls.filter(source is preferred)
other_urls = wave_urls.filter(source is not preferred)
shuffle(preferred_urls)
shuffle(other_urls)
final = preferred_urls ++ other_urls

---

3. Frontend

ThemeManager source list

• Checkbox on each source row (left side)
• Preferred sources get a star icon or subtle highlight
• Counter at bottom: "X source(s) prioritaire(s)"
• Auto-save: on check/uncheck, immediately call PUT /api/v1/sources/preferred with updated ID list

---

4. Files

• Create: backend/migrations/20260327000029_add_source_preferred.sql
• Create: backend/tests/api_sources_preferred_test.rs
• Modify: backend/src/models/source.rs — add is_preferred: bool to Source
• Modify: backend/src/db/sources.rs — add to queries, add update_preferred function
• Modify: backend/src/handlers/sources.rs — add update_preferred handler
• Modify: backend/src/router.rs — add route
• Modify: backend/src/services/synthesis.rs — preferred-first ordering + shuffle
• Modify: backend/tests/pipeline_test.rs — test preferred ordering
• Modify: frontend/src/pages/ThemeManager.tsx — checkboxes, counter, auto-save
• Modify: frontend/src/api/sources.ts — add updatePreferred
• Modify: frontend/src/types.ts — add is_preferred to Source
• Modify: frontend/src/i18n/fr.ts — labels
• Modify: e2e/tests/sources.spec.ts — add preferred test
• Modify: CLAUDE.md — migration count