domverse/photoanalyzer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

US09-03 — Write the Architecture Overview #104

New Issue
Closed
opened 2026-08-23 15:06:15 +02:00 by domverse · 3 comments
domverse commented 2026-08-23 15:06:15 +02:00
Owner
Copy Link

Source specification: delivery_backlog/stories/US09-03-architecture-overview.md

US09-03 — Write the Architecture Overview

Epic: E09

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
Source specification: [delivery_backlog/stories/US09-03-architecture-overview.md](https://git.domverse-berlin.eu/domverse/photoanalyzer/src/branch/main/delivery_backlog/stories/US09-03-architecture-overview.md) # 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
domverse self-assigned this 2026-08-23 15:06:15 +02:00
domverse added this to the E09 — Product Documentation milestone 2026-08-23 15:07:41 +02:00
domverse added this to the Photo Analyzer Delivery project 2026-08-23 15:09:06 +02:00
domverse added a new dependency 2026-08-23 15:10:17 +02:00
#102 US09-01 — Serve the Documentation Inside the Application
domverse added a new dependency 2026-08-23 15:10:19 +02:00
#106 US09-05 — Automate Documentation Acceptance
domverse removed their assignment 2026-08-23 15:15:06 +02:00
domverse added status/in-progress and removed status/backlog labels 2026-08-23 21:47:22 +02:00
domverse self-assigned this 2026-08-23 21:47:23 +02:00
domverse commented 2026-08-23 21:47:23 +02:00
Author
Owner
Copy Link

Claimed for implementation on branch us/US09-03-write-the-architecture-overview.

Claimed for implementation on branch `us/US09-03-write-the-architecture-overview`.
domverse added status/review and removed status/in-progress labels 2026-08-23 22:35:12 +02:00
domverse commented 2026-08-23 22:35:13 +02:00
Author
Owner
Copy Link

Submitted for review: #109

Tests passed:

  • work_item/scripts/python -m unittest discover -s work_item/tests -v
  • work_item/scripts/python -m pytest tests -q
  • work_item/scripts/python -m pytest tests/integration/test_architecture_overview.py tests/e2e/test_docs_ui.py -q
Submitted for review: https://git.domverse-berlin.eu/domverse/photoanalyzer/pulls/109 Tests passed: - `work_item/scripts/python -m unittest discover -s work_item/tests -v` - `work_item/scripts/python -m pytest tests -q` - `work_item/scripts/python -m pytest tests/integration/test_architecture_overview.py tests/e2e/test_docs_ui.py -q`
domverse added status/done and removed status/review labels 2026-08-23 22:35:31 +02:00
domverse commented 2026-08-23 22:35:31 +02:00
Author
Owner
Copy Link

Completed and merged via PR #109.

Completed and merged via PR #109.
domverse moved this to Done in Photo Analyzer Delivery on 2026-08-23 22:48:19 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/backend
Backend services, jobs, or API
 area/database
Schema, persistence, migration, or queries
 area/documentation
Manuals, architecture notes, and in-app documentation
 area/filesystem
Filesystem identity, mutation, or storage
 area/frontend
Browser UI and client-side application
 area/integration
External tools or provider integrations
 area/testing
Automated test suites, fixtures, and tooling
 priority/critical
Release-blocking safety or correctness
 priority/high
Important phase outcome
 priority/normal
Normal planned work
 status/backlog
Awaiting dependency eligibility or prioritization
 status/blocked
Cannot proceed without an explicit resolution
 status/done
Merged, tested, and completed
 status/in-progress
Currently being implemented
 status/ready
Eligible to be claimed
 status/review
Submitted in a pull request for review
 type/documentation
Written documentation delivered as a product artefact
 type/feature
User-facing or domain capability
 type/hardening
Security, resilience, operations, or release hardening
 type/migration
Donor extraction, migration, or legacy consolidation
 type/test
Automated test infrastructure or acceptance coverage
No Label area/documentation priority/normal status/done type/documentation
Milestone
No items
No Milestone E09 — Product Documentation
Projects
Clear projects
No project Photo Analyzer Delivery
Assignees
Clear assignees
domverse
No Assignees domverse
1 Participants
Notifications
Due Date
No due date set.
Blocks
#106 US09-05 — Automate Documentation Acceptance
domverse/photoanalyzer
Depends on
#102 US09-01 — Serve the Documentation Inside the Application
domverse/photoanalyzer
Reference: domverse/photoanalyzer#104
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?