69 lines
2.9 KiB
Markdown
69 lines
2.9 KiB
Markdown
# 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
|
|
|
|
1. [Overview](overview.md) — what the application does, the stages it moves a photo
|
|
through, and the rules it will not break.
|
|
2. [Installation and operations](installation.md) — host and container installation,
|
|
every setting, the first-run checklist, upgrades, backup and restore, and what
|
|
each refusal at startup means.
|
|
3. [A guided first pass](first-pass.md) — one library from scan to verified upload,
|
|
with the point of no return named in each stage.
|
|
4. [Architecture](architecture.md) — 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.
|
|
|
|
1. [Inventory and discovery](stages/inventory.md)
|
|
2. [Duplicate review](stages/duplicates.md)
|
|
3. [Safety review](stages/safety.md)
|
|
4. [Analysis](stages/analysis.md)
|
|
5. [Album proposals](stages/albums.md)
|
|
6. [Renames](stages/renames.md)
|
|
7. [Upload](stages/uploads.md)
|
|
8. [Archive](stages/archive.md)
|
|
9. [Diagnostics and library statistics](stages/diagnostics.md)
|
|
|
|
## When something goes wrong
|
|
|
|
- [Errors and refusals](errors.md) — every error code, what caused it, what to do.
|
|
- [Recovery](recovery.md) — 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:
|
|
|
|
```bash
|
|
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](../README.md).
|
|
|
|
## 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.
|