# A guided first pass

[← Documentation index](index.md)

One library, from nothing to a verified upload. Each stage links to its own page; this
is the order, and — more importantly — where the points of no return are.

![The workflow home, with every stage and its counts](images/workflow.png)

The workflow page is the home view and the honest summary: each stage shows its state,
its counts, why it is blocked if it is, and the one action that moves it forward.

| # | stage | reversible afterwards? |
|---|---|---|
| 0 | [Inventory](stages/inventory.md) | nothing was changed |
| 1 | [Duplicate review](stages/duplicates.md) | yes — decisions can be changed, no file is deleted |
| 2 | [Safety review](stages/safety.md) | the decision, yes; the EXIF keyword is a file write |
| 3 | [Analysis](stages/analysis.md) | the result, yes; the caption and keywords are a file write |
| 4 | [Album proposals](stages/albums.md) | yes — approving renames nothing |
| 5 | [Renames](stages/renames.md) | **your folders move.** Recoverable, journaled, but real |
| 6 | [Upload](stages/uploads.md) | **assets exist on the Immich server.** Not undone from here |
| 7 | [Archive](stages/archive.md) | **originals leave active storage.** Restorable while the medium is reachable |
| — | [Diagnostics](stages/diagnostics.md) | read-only, any time |

## Before the first run

Take a backup of the photo library itself. This application is careful — it previews,
journals, and verifies — but it is the first time you are pointing it at your
photographs, and a backup is cheaper than confidence.

If the library is irreplaceable, turn on `PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL`
before anything else. Every mutating request is then refused until you have produced
a read-only reconciliation report and approved it by name.

## The pass

1. **Scan.** Inventory → *Rescan*. Reads only. Check the count, and check that
   nothing under `_IGNORE/` appears.
2. **Resolve duplicates.** Exact byte matches can be accepted as recommended; anything
   fuzzy gets looked at. Resolving first is what stops you paying to analyse the same
   photo twice.
3. **Decide safety.** Every canonical photo becomes `sfw` or `nsfw`. Nothing reaches
   the vision provider until it is confirmed SFW — this is the gate the whole design
   exists around.
4. **Analyse.** Only confirmed-SFW photos. Each result is written to the database and
   projected into EXIF, then read back and verified.
5. **Propose album names.** Evidence from what was analysed. Edit anything you disagree
   with. Approving changes no file.
6. **Build the rename plan, read it, apply it.** The preview shows every old → new
   path. This is where folders move.
7. **Rescan.** Paths are reconciled; identities are unchanged.
8. **Upload.** Preflight lists every blocker. The command is previewed without the API
   key. One album at a time.
9. **Verify.** An uncertain upload is not a failure and not a success — ask the server.
10. **Archive** (optional). Copy, verify, and only then reclaim the space.

Stop anywhere. Every stage is resumable, and closing the browser cancels nothing.

## Two rules worth internalising

**The application refuses more than it warns.** A refusal is not a fault; it is the
design working. [Errors and refusals](errors.md) explains each one.

**One long job at a time.** Browsing stays available while a job runs, but a second
mutating job is refused — that is what makes a crash recoverable rather than
ambiguous.