ai_synth/audits/2026-03-27/consolidated-refactoring-plan.md

Consolidated Refactoring Plan (From 5-Agent Audit)

Inputs

• Software architect report
• Frontend SolidJS report
• Backend Rust report
• Technical lead report
• QA integration/E2E report

Clarifications Required Before Implementation

1. Theme creation contract:
   • Draft allowed with empty topic/categories, or mandatory valid values on create?
2. Schedule GET contract:
   • 404 when absent, or 200 with null?
3. Canonical theme defaults:
   • max_items_per_category/summary_length should be 4/3 or 5/2?
4. Theme scoping policy:
   • Are import/export/preferred operations always theme-scoped?
5. Terminology:
   • Fallback category label (Autre vs Divers)
   • Source-link extraction mode still required or deprecated

Executive Summary

• The codebase has good foundations (clear layering intent, provider abstraction, strong backend unit coverage), but there is significant spec/implementation drift in theme/schedule/source contracts.
• Highest risk is correctness, not style: multi-theme data scoping and contract mismatches can break core user flows.
• Complexity is concentrated in a few large files; decomposition should happen only after correctness and reliability fixes.

Priority Backlog

P0 (Immediate)

1. Fix theme-scoped source correctness:
   • Ensure bulk/CSV import preserves theme_id
   • Scope preferred-source updates by theme
   • Make CSV export theme-aware
2. Fix theme creation flow contract mismatch:
   • Align UI create payload and backend validation
3. Add tests for P0 flows:
   • Multi-theme isolation integration tests
   • End-to-end create theme happy path

P1 (Next)

1. Unify schedule API contract across docs/backend/frontend/tests.
2. Align theme defaults across migration/backend/frontend/docs.
3. Harden scheduler reliability:
   • deterministic integration tests
   • timeout parity with manual generation
4. Add deterministic SSE progress integration tests.
5. Add Brave fallback/rate-limit/max-age pipeline integration coverage.

P2 (Then)

1. Decompose backend synthesis pipeline module by phase.
2. Decompose large frontend pages (ThemeManager, Providers, Settings) into hooks/components.
3. Remove direct fetch in pages; enforce API client boundary.
4. Remove hardcoded UI strings; enforce i18n conventions.
5. Replace silent .ok() error swallowing with warn/metric patterns.

P3 (Opportunistic)

1. Convention enforcement via lint/codemods.
2. Clean reactive anti-patterns (render-time side effects).
3. Performance optimizations (N+1 phase-2 checks, set-based inserts).

Suggested Delivery Sequence (For Follow-up Team)

1. Decision sprint (0.5-1 day): finalize 5 open clarifications.
2. Correctness sprint (1-2 weeks): all P0 + tests merged.
3. Reliability sprint (1 week): scheduler/SSE/fallback/rate-limit/max-age tests + runtime parity fixes.
4. Simplification sprint (1-2 weeks): decomposition of largest backend/frontend hotspots.
5. Governance sprint (2-3 days): lint/conformance checks to prevent drift.

Acceptance Criteria

1. No spec drift for theme/schedule/source contracts (tests and docs aligned).
2. Multi-theme operations fully isolated and verifiably correct.
3. Scheduled generation reliability covered by deterministic integration tests.
4. SSE and fallback branches have deterministic coverage in CI.
5. Largest hotspots reduced in size and complexity with no behavior regression.