2.9 KiB
Photo Pipeline documentation
One local application that takes a photo library from discovery to a verified Immich upload: duplicate detection, safety review, content analysis, album naming, guarded renaming, upload, and archive — one visible, resume-safe workflow.
These pages are readable three ways, and they are the same files each time: in the
repository under docs/, on Gitea, and inside the running application under
Docs. There is no separate copy to fall out of date.
Read in this order
- Overview — what the application does, the stages it moves a photo through, and the rules it will not break.
- Installation and operations — host and container installation, every setting, the first-run checklist, upgrades, backup and restore, and what each refusal at startup means.
- A guided first pass — one library from scan to verified upload, with the point of no return named in each stage.
- Architecture — the context and runtime diagrams, what each module owns, the three journals a restart reads, and where every invariant is enforced.
The stages, one page each
Every page answers the same four questions: what the stage is for, what you decide, what it changes on disk or on the server, and what it refuses.
- Inventory and discovery
- Duplicate review
- Safety review
- Analysis
- Album proposals
- Renames
- Upload
- Archive
- Diagnostics and library statistics
When something goes wrong
- Errors and refusals — every error code, what caused it, what to do.
- Recovery — what the application resolves by itself, and what needs you.
Keeping these pages true
Documentation that disagrees with the application is worse than none, because it is trusted. So one command compares them:
python -m photo_pipeline docs-gate
It runs every phase_i check — dead links and anchors, pages nobody links to, images
nobody shows, settings, commands, exit codes, error codes, and states that no longer
exist in the code, the pages rendering in a real browser without a console or policy
error, and the screenshots still showing what the application shows. It retains its
evidence and accepts no skipped check: a check that did not run is a page nobody
compared. CI runs it on every pull request.
The repository's own build, test, and release notes live in the README.
Conventions
A page tells you what a stage changes on disk or on the server before it tells you how to run it. Refusals are documented as intentional: this application would rather stop and explain than guess about somebody's photographs.