ai_synth/audits/2026-03-27/software-architect.md

# Software Architect Audit Report (March 27, 2026)

## Clarification Questions
1. Should a new theme be creatable with empty categories/topic (draft mode), or must it be valid at creation?
2. Should `GET /themes/{id}/schedule` return `404` when absent, or `200` with `null`?
3. Which defaults are canonical for themes: DB/spec (`max_items_per_category=4`, `summary_length=3`) or UI/handler (`5`, `2`)?

## Assumptions
- Documentation in `docs/` is the intended target behavior.
- This is architecture-focused (entry points, service boundaries, major modules), not a line-by-line audit of all files.

## Prioritized Findings

### P0
- Theme creation contract is internally inconsistent and likely broken in practice.
  - Evidence: UI creates empty topic/categories in `/Users/oabrivard/Projects/rust/ai_synth/frontend/src/pages/ThemeManager.tsx:144`, while backend rejects empty topic/categories in `/Users/oabrivard/Projects/rust/ai_synth/backend/src/models/theme.rs:43` and enforces validation in `/Users/oabrivard/Projects/rust/ai_synth/backend/src/handlers/themes.rs:45`.
  - Why it matters: blocks core onboarding flow.
  - Direction: align API contract + UI create flow (draft-support or valid seeded defaults).

### P1
- Schedule API contract drift across spec, backend, tests, and frontend typing.
  - Evidence: spec says `ScheduleResponse` or 404 in `/Users/oabrivard/Projects/rust/ai_synth/docs/technical_specs.md:420`; backend returns `200 null` in `/Users/oabrivard/Projects/rust/ai_synth/backend/src/handlers/schedules.rs:40`; tests expect `200 null` in `/Users/oabrivard/Projects/rust/ai_synth/backend/tests/api_schedules_test.rs:77`; frontend assumes non-null in `/Users/oabrivard/Projects/rust/ai_synth/frontend/src/components/settings/SettingsSchedule.tsx:48`.
  - Why it matters: runtime fragility and contract confusion.
  - Direction: choose one contract and align all layers.

- Theme defaults are inconsistent with DB/spec.
  - Evidence: DB migration defaults 4/3 in `/Users/oabrivard/Projects/rust/ai_synth/backend/migrations/20260326000028_create_themes_and_migrate.sql:8`; handler uses 5/2 in `/Users/oabrivard/Projects/rust/ai_synth/backend/src/handlers/themes.rs:56`; UI uses 5/2 in `/Users/oabrivard/Projects/rust/ai_synth/frontend/src/pages/ThemeManager.tsx:51`.
  - Why it matters: non-deterministic behavior and drift.
  - Direction: establish a single source of truth for defaults.

- Reliability gap: job-store TTL cleanup exists but is not scheduled at runtime.
  - Evidence: cleanup function exists in `/Users/oabrivard/Projects/rust/ai_synth/backend/src/services/job_store.rs:153`; startup schedules other tasks but not job-store cleanup in `/Users/oabrivard/Projects/rust/ai_synth/backend/src/main.rs:66`; docs expect periodic cleanup in `/Users/oabrivard/Projects/rust/ai_synth/docs/technical_specs.md:778`.
  - Why it matters: stale in-memory entries and lock leakage risk over time.
  - Direction: add periodic `job_store.cleanup_expired()` task.

- Scheduled generation path does not enforce 15-minute timeout used by manual generation.
  - Evidence: manual timeout in `/Users/oabrivard/Projects/rust/ai_synth/backend/src/handlers/generation.rs:89`; scheduler calls pipeline directly in `/Users/oabrivard/Projects/rust/ai_synth/backend/src/services/scheduler.rs:57`; requirement states 15-minute cap in `/Users/oabrivard/Projects/rust/ai_synth/docs/requirements.md:30`.
  - Why it matters: scheduled runs can overrun and block throughput.
  - Direction: apply same timeout semantics to scheduled execution.

### P2
- Core pipeline and key pages are too large.
  - Evidence: `/Users/oabrivard/Projects/rust/ai_synth/backend/src/services/synthesis.rs`, `/Users/oabrivard/Projects/rust/ai_synth/backend/src/services/scraper.rs`, `/Users/oabrivard/Projects/rust/ai_synth/frontend/src/pages/ThemeManager.tsx`, `/Users/oabrivard/Projects/rust/ai_synth/frontend/src/pages/Settings.tsx`.
  - Why it matters: weaker SRP, higher cognitive load, slower onboarding/review/testing.
  - Direction: split by bounded responsibilities (phase modules/services/hooks/components).

- Frontend architectural consistency drift (API and data-loading patterns).
  - Evidence: direct `fetch` in `/Users/oabrivard/Projects/rust/ai_synth/frontend/src/pages/GenerateSynthesis.tsx:241` despite centralized client in `/Users/oabrivard/Projects/rust/ai_synth/frontend/src/api/client.ts:25`; guideline preference for `createResource` in `/Users/oabrivard/Projects/rust/ai_synth/docs/dev_guidelines.md:174`.
  - Direction: enforce API client boundary and consistent data-loading patterns.

## SOLID Scorecard

| Dimension | Score (/5) | Notes |
|---|---:|---|
| Single Responsibility | 2 | Several large multi-responsibility modules. |
| Open/Closed | 4 | LLM provider abstraction/factory is extensible. |
| Liskov Substitution | 4 | Provider implementations conform to trait contract cleanly. |
| Interface Segregation | 3 | Mostly good boundaries with a few broad surfaces. |
| Dependency Inversion | 3 | Good trait usage for LLM, pipeline still tightly coupled in places. |
| Overall maintainability | 3 | Good foundations, but contract drift + module size are bottlenecks. |

## Refactoring Plan
1. Phase 0: Contract decisions (0.5-1 day, low risk).
   - Decide canonical behavior for theme creation, schedule GET semantics, and defaults.
2. Phase 1: Correctness alignment (1-2 days, medium risk).
   - Align backend/frontend/tests with chosen contracts.
3. Phase 2: Reliability hardening (1 day, low-medium risk).
   - Add job-store cleanup scheduling and timeout parity in scheduler.
4. Phase 3: Backend decomposition (3-5 days, medium risk).
   - Split synthesis pipeline into phase modules with explicit contexts.
5. Phase 4: Frontend decomposition (3-5 days, medium risk).
   - Split large pages into composables/components and remove direct page-level fetch.
6. Phase 5: Drift prevention (1-2 days, low risk).
   - Add conformance tests/checks for contracts/defaults and PR architecture checklist.

## Architecture/SOLID Scorecard
| Dimension | Score (/5) | Notes |
|---|---:|---|
| Layering clarity | 3 | Clear module boundaries, but some runtime orchestration gaps.
| SRP | 2 | Multiple "god files" in backend and frontend.
| OCP | 4 | LLM provider abstraction/factory is cleanly extensible.
| DIP | 3 | Core synthesis is trait-based for LLM, but still tightly coupled to DB/functions.
| Testability | 3 | Strong unit/integration coverage in backend; scheduler/e2e gaps remain.
| Spec alignment | 2 | Multiple contract/default mismatches.

## Refactoring Plan (Architecture-Level)

### Phase 1 (1-2 days) — Contract and reliability fixes
- Align theme creation contract (UI + model validation + tests).
- Align schedule GET semantics across docs/handler/tests/frontend types.
- Add periodic `job_store.cleanup_expired()` background task.
- Apply 15-minute timeout to scheduled generation path.

### Phase 2 (3-5 days) — Backend decomposition
- Split `services/synthesis.rs` into submodules:
  - `init.rs` (load settings/theme/provider)
  - `phase1_personalized.rs`
  - `phase2_fallback.rs`
  - `finalize.rs`
  - `tracing.rs`
- Introduce explicit pipeline context structs to reduce argument fanout.

### Phase 3 (3-5 days) — Frontend decomposition
- Extract page-level logic from `ThemeManager` and `Settings` into composables/hooks:
  - `useThemeEditor`, `useSourcesManager`, `useScheduleConfig`, `useSettingsForm`
- Normalize API usage through `api/client.ts` only.

### Phase 4 (2-3 days) — Conformance hardening
- Add spec-conformance tests for defaults, schedule contract, and theme creation.
- Add architecture fitness checks (lint/custom tests) for forbidden contract drifts.

## Quick Wins (< 1 day)
1. Add scheduled timeout wrapper in `scheduler.rs`.
2. Add job-store periodic cleanup task in `main.rs`.
3. Fix `ThemeManager` create payload to pass valid initial `theme` and categories.
4. Unify schedule GET typing with actual backend behavior.