# 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.

## 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.