Goal
Reduce complexity in the largest workflow modules by extracting clearer boundaries without changing behavior.
Context
Large hotspots include source sync service, review UI routes, the movies router, and maintenance update/job execution. This issue is intentionally architecture-focused, but it should still be implemented as a sequence of small behavior-preserving PRs.
Suggested Scope
- Split source-sync decision logic from import/export/parsing concerns.
- Extract review queue/view-model helpers from route handlers.
- Introduce a small maintenance job runner abstraction with explicit dry-run/apply/cancel behavior.
- Keep route behavior, templates, and database writes unchanged in each PR.
- Prefer one extraction at a time rather than a broad rewrite.
Files or Areas
api/services/source_sync.py
api/routers/ui/review.py
api/routers/movies.py
api/routers/collection_health.py
api/services/vault_update.py
api/services/movie_review.py
tests/test_source_sync.py
tests/test_movies_ui.py
tests/test_collection_health_api.py
Out of Scope
- UI redesign
- Database schema changes unless separately justified
- Changing import/review semantics
- Moving code into
legacy/
- Combining unrelated feature work with refactors
Acceptance Criteria
- Route handlers become thinner and easier to review.
- Existing behavior is preserved and covered by current tests.
- Each PR names the boundary it extracts and the tests that prove behavior did not change.
- No destructive or bulk data changes are introduced.
Verification
- Start with focused tests for the touched workflow, such as
pytest tests/test_source_sync.py, pytest tests/test_movies_ui.py, or pytest tests/test_collection_health_api.py.
- Run
make codex.check before opening a PR.
Contributor Notes
This is probably not a first PR unless scoped to one small extraction. Contributors are welcome to comment with the slice they want to tackle before opening a larger refactor PR.
Goal
Reduce complexity in the largest workflow modules by extracting clearer boundaries without changing behavior.
Context
Large hotspots include source sync service, review UI routes, the movies router, and maintenance update/job execution. This issue is intentionally architecture-focused, but it should still be implemented as a sequence of small behavior-preserving PRs.
Suggested Scope
Files or Areas
api/services/source_sync.pyapi/routers/ui/review.pyapi/routers/movies.pyapi/routers/collection_health.pyapi/services/vault_update.pyapi/services/movie_review.pytests/test_source_sync.pytests/test_movies_ui.pytests/test_collection_health_api.pyOut of Scope
legacy/Acceptance Criteria
Verification
pytest tests/test_source_sync.py,pytest tests/test_movies_ui.py, orpytest tests/test_collection_health_api.py.make codex.checkbefore opening a PR.Contributor Notes
This is probably not a first PR unless scoped to one small extraction. Contributors are welcome to comment with the slice they want to tackle before opening a larger refactor PR.