domverse
792134c72d
Adds the installation manual, architecture overview, and illustrated user manual as a five-story epic, plus the acceptance gate that keeps them true. The documentation is markdown under docs/, so the same files are readable in the repository and rendered by the deployed application at /app/#/docs. An operator who was handed a URL and an access secret has no repository checkout in front of them, and the network the application is deployed to is not assumed to reach a CDN. Two decisions are recorded in the epic rather than left to implementation: - The renderer is vendored (marked), not written and not fetched. - Diagrams are mermaid, rendered client-side, with script-src untouched. Whether mermaid needs 'unsafe-eval' was measured rather than assumed: its bundle contains no eval( and no new Function, and rendered under this application's exact CSP it produced an SVG with no script-src violation. What it does violate is style-src, which gains 'unsafe-inline'. With script-src, img-src, connect-src, and font-src all unchanged, that leaves defacement rather than execution or exfiltration. The alternative -- pre-rendering diagrams to committed SVG with the already-installed Playwright -- is recorded as the migration if that trade is ever refused. Screenshots are generated from the running application, never pasted, and every documented setting, command, exit code, error code, and state is cross-checked against the code that implements it, so stale documentation fails a test instead of misleading an operator. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015csGY8XV1M92fHfKnMmjtu
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
|