Skip to content

Refactor source sync, review, and maintenance job modules around workflow boundaries #201

Description

@cmsjade5000

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions