48 lines
2.4 KiB
Markdown
48 lines
2.4 KiB
Markdown
# 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
|