1 ADR 0095 per face crops via generic discovery thumbnail job
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

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.