# US09-03 — Write the Architecture Overview

Epic: [E09](../E09-documentation.md)

As a developer or reviewer new to this repository, I want an architecture overview that
explains what the pieces are and which rules they enforce, so that I can find the right
module and not violate an invariant I never knew existed.

## Acceptance criteria

- A **context diagram**: the operator, the browser application, the API and worker, the
  photo library, the Immich server, the vision provider, and the archive destination —
  with the direction and nature of every interaction, including which ones leave the
  machine.
- A **runtime diagram**: the migrate/api/worker composition, the data volume, the library
  bind mount, the SQLite database, and the process lock — showing what is shared and what
  is exclusive.
- A **module map**: every package under `photo_pipeline/` with its responsibility and the
  boundary it must not cross (which modules may touch the filesystem, which may call an
  external provider, which own schema).
- **Key flows**, each as a diagram plus prose: the durable job lifecycle from enqueue to
  recovery; the rename journal state machine including the rollback and manual-resolution
  paths; the upload lifecycle through preflight, run, report ingestion, and verification.
- **The invariants and where they are enforced**, each pointing at the module that owns
  it: one writer at a time, the library process lock, the path policy and library roots,
  `_IGNORE/` exclusion, verified EXIF before upload, safety decisions gating the vision
  provider, and restart-safety of every mutation.
- **The data model**: the tables, what identity means for an asset, and how a moved file
  keeps its identity.
- A short **history and donor** section: what was migrated out of the legacy CLIs, where
  the archive and its ledger live, and why they are kept.
- Diagrams are ```mermaid``` blocks so the source is diffable and Gitea renders them
  natively.

## Automated tests

- Every package and top-level module under `photo_pipeline/` appears in the module map,
  and every module named in the map exists — a new service cannot appear on the map's
  blind side.
- Every job state, journal state, and upload batch state named in the document exists in
  the code, and every state the code defines is named in the document.
- Every mermaid block parses (rendered in the browser test without an error node).
- Every code path referenced by file name exists.

## Dependencies

- US09-01