photoanalyzer/docs/first-pass.md

A guided first pass

← Documentation index

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 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	nothing was changed
1	Duplicate review	yes — decisions can be changed, no file is deleted
2	Safety review	the decision, yes; the EXIF keyword is a file write
3	Analysis	the result, yes; the caption and keywords are a file write
4	Album proposals	yes — approving renames nothing
5	Renames	your folders move. Recoverable, journaled, but real
6	Upload	assets exist on the Immich server. Not undone from here
7	Archive	originals leave active storage. Restorable while the medium is reachable
—	Diagnostics	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 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.