immich-photo-flow/CLAUDE.md

CLAUDE.md

What this is

A monorepo (M1) of an Immich photo-flow foundation + the trip-cluster app. See docs/ROADMAP.md for milestones and docs/superpowers/specs/2026-06-27-immich-photo-flow-design.md for the M1 design.

Architecture map

• shared/photoflow/immich — the only Immich client (client.py) + _pipeline/ tag conventions (pipeline.py).
• shared/photoflow/core — the only SQLite owner: store.py (data-access) + models.py.
• shared/photoflow/ui — base.html, shared Jinja macros, shared.js grid+lightbox.
• apps/trip-cluster/app — config.py, cli.py (ingest|cluster|serve|apply), ingest.py, clustering.py (pure), coverage.py (pure), cluster_run.py, review.py, writeback.py, routes/, templates/, static/app.js.

Key invariants

• Immich is the source of truth; SQLite is rebuildable. Only applied decisions survive loss of SQLite (via _pipeline/processed + writeback_log).
• Content/trip tags are never namespaced; pipeline meta-tags nest under _pipeline/.
• Trip detection is timestamp-first, density-adaptive, anchored by existing trip tags, refined by GPS. Existing trip tags are authoritative seeds.
• Write-back is idempotent (writeback_log) and needs explicit confirmation.
• Ingest is scopeable (--from/--to, --tag, --subset) and incremental (updatedAfter).
• trip-cluster serves on 8084.

Dev commands

.venv/bin/python -m pytest                     # unit + route (Immich mocked)
.venv/bin/python -m pytest apps/trip-cluster/tests/ui   # Playwright
docker compose up                              # UI on :8084

Write a failing test first (TDD). Mirrors the sibling apps in /home/mischa/Projects/.