ADR 0095: Per-Face Crops Via Generic Discovery Thumbnail Job
Status: accepted Date: 2026-09-06
Context
Per-face thumbnails (crops) have been dead since the thumbnail-pipeline unification (commit 022e1a84): ADR 0094 (proposed) mandates a single generic generate_discovery_thumbnail job type and forbids domain-specific thumbnail types, and the generic worker path only renders instance thumbnails. Result: 0 of 16411 faces have thumbnail_derived_asset_id; every suggestion/face UI thumbnail 404s (frontend guarded by PR #708, which suppresses broken URLs). Spec 014 task S014T003 planned removal of the legacy per-face path. On 2026-09-06 the product owner approved reviving per-face crops — inside the generic pipeline, not by reinstating a domain-specific job. Serving is already prepared: DerivedAssetController.faceThumbnail resolves via thumbnail_derived_asset_id OR variant face-{id}-%, ~51k legacy per-face assets still exist on storage, and endpoint GET /api/media/{mediaId}/faces/{faceAnnotationId}/thumbnail stays. This ADR extends ADR 0094 (which remains proposed); it does not supersede it.
Decision
Revive per-face thumbnail (crop) generation by riding the existing generic generate_discovery_thumbnail job type — no new domain-specific job type, preserving ADR 0094 core generality.
- Payload: add optional faceAnnotationId (UUID string) beside classInstanceId; boundingBox comes from discovery_results.scope.
- Worker (apps/worker-media MediaJobHandlers.generateDiscoveryThumbnail): face mode renders sizes 256+512 with variant face-{faceAnnotationId}-{size} and generationVersion face-thumbnail-v1; result includes faceAnnotationId, variant, size, complete flag (true at 512). Instance mode unchanged (512 only, discovery-thumb-{classInstanceId}-512).
- API acceptance (WorkerResultService.acceptDiscoveryThumbnail): face mode upserts derived_assets(face_thumbnail) and sets discovery_results.thumbnail_derived_asset_id; instance mode keeps the existing class_instances update. Photo-only (no video), same as current generic behavior.
- Enqueue: new enqueueMissingFaceCropJobs() (+ ForMedia variant) in WorkerJobEnqueueService — people faces with state IN (accepted, owner_recognized) AND thumbnail_derived_asset_id IS NULL, idempotent (skip existing assets/jobs). Triggers: after people-results acceptance for affected media, plus a trickle @Scheduled backfill (small batch per run, queue-depth-safe for ~16k faces → ~32k files).
- Legacy removal (fulfills spec 014 task S014T003): delete deprecated generate_face_thumbnail job type, MediaJobHandlers.generateFaceThumbnail, WorkerResultService.acceptFaceThumbnail + canonicalFaceThumbnailVariant, WorkerJobEnqueueService.faceThumbnailPayload + enqueueMissingFaceThumbnailJobs, credential bootstrap + compose.yaml capability entries.
- Serving: unchanged. DerivedAssetController.faceThumbnail continues to resolve via thumbnail_derived_asset_id OR variant face-{id}-% — serves both ~51k legacy assets and new crops through the same storage/variant conventions.
- Privacy/ops: crops are biometric-derived data generated server-side onto self-hosted storage only (existing precedent); ~2 files per face (~32k files for this instance), trickle-backfilled.
Consequences
Positive: per-face UI thumbnails (suggestions, face grid) return — the 404-guarded UI becomes functional again; ADR 0094 generic pipeline preserved (no domain-specific job type reinstated); spec 014 S014T003 fulfilled by removal not retention (legacy path deleted, one pipeline forward); existing serving path handles new and legacy assets uniformly; idempotent enqueue plus trickle backfill keeps queue load bounded. Negative: storage growth of ~2 files per face (~32k files for ~16k faces); backfill adds sustained background queue load after deployment; dual-variant coexistence — ~51k legacy per-face assets live alongside new face-{id}-{size} variants until/unless GC policy covers them. Revisit triggers: if face-crop demand exceeds queue-depth-safe trickle, revisit batch sizing; if per-face assets later need domain-specific semantics (e.g. different retention), revisit whether face crops stay inside the generic job payload.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference