This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
ADR 0110: Person gallery score sort reuses the face-thumbnails read path
Status: accepted Date: 2026-10-11 Notes: ["2026-10-11: Cross-references — ADR 0098 (standard filter/sort menu contract and per-surface sort options), ADR 0096 (media overlay prev/next neighbour navigation; score mode supplies its own deduped neighbour list because day items are empty), ADR 0109 (person-gallery face ranking context), and the face-thumbnail read path (ClassInstanceFaceThumbnailService / GET /class-instances/{id}/face-thumbnails, the set-representative face picker's source).", "Non-goals (v1): no new endpoint (the existing face-thumbnails read path gained filter parameters — mediaType, favorite, from, to, confirmation); no URL persistence of sort mode (component state, per ADR 0098); no quantile/adaptive binning; no plant/animal domains (rankScore is a face-embedding blend and is gated to domainKey === 'people')."]
Context
The person/class-instance detail gallery (ADR 0098 sort menu: Optagelse/Tilføjet) has no way to browse a person's faces by match quality. A blended per-face rankScore already exists server-side — 0.5 * centrality percentile + 0.3 * recency percentile + 0.2 * quality percentile over the face embedding space — and is exposed per accepted or tentative face occurrence on GET /api/discovery/class-instances/{id}/face-thumbnails (the set-representative face-picker read path): occurrenceId, faceAnnotationId, mediaItemId, faceThumbnailUrl (nullable), capturedAt, confidence, faceBoxArea, isCurrent, centrality, rankScore (0..1|null), qualityScore, assignmentState, server-sorted rankScore DESC, cursor-paginated (limit clamped 1..500). The alternative — teaching the day-bucket endpoints (/days, /days/{dayKey}) a sort=score — is rejected: normalizeClassInstanceDaySort throws 400 on anything but captured/added, day keys are a capture/added date-key space, and day buckets would force materializing the full result set to bucket it. The face-thumbnails endpoint also shaped this ADR: it now takes the same mediaType/favorite/from/to narrowing as the day walls plus its own explicit confirmation parameter (accepted | tentative | all — its own default is accepted, so the client always sends it), and rankScore is computed server-side independent of the filters, so a face's score is identical regardless of which filters are active.
Decision
Person-gallery Score sort (ADR 0098 sort menu contract, third option "Score", people domain only) is a client-side view over the face-thumbnails read path — no new endpoint, and the day-bucket endpoints stay untouched; the read path gained filter parameters (mediaType, favorite, from, to, confirmation) so Score serves the same filters as every other sort mode. The wall stays sectioned, but sections are fixed descending rankScore deciles instead of calendar days: 90–100 %, 80–90 %, …, 0–10 %, plus an unranked bin ("Uden score", rankScore == null) last; empty bins are omitted and each header carries its range plus the loaded face count. Fixed deciles (not quantiles) because the endpoint pages in rankScore DESC order, so bins fill top-down without the full result set, and appending a page only extends existing bins or opens lower ones — section keys stay stable, no re-bucketing churn. Loading mirrors the day-wall reveal-sentinel pattern: pages of 300 auto-load as a bottom sentinel scrolls into the viewport (the endpoint clamps limit to 500 and re-ranks the whole occurrence set per request, so large pages keep request count low under infinite scroll), using the endpoint's nextCursor and total, deduped by occurrenceId; a passive "N of M faces" status line keeps partial state explicit. Tiles are the face crops (square 512×512 synthesized dimensions), keyed by occurrenceId (a photo contributing several faces is intended), with a persistent numeric badge ("87 %", neutral dash when unranked); a null faceThumbnailUrl renders the existing placeholder tile, never a broken image. Clicking a tile opens the existing media overlay deep-linked by mediaItemId; overlay prev/next in Score mode walks the deduped score-ordered media ids (one step per photo). While Score is active: the FilterSortMenu filter trigger and every filter section stay available exactly as in the day modes — media/date params serialize through the shared day-wall helper and confirmation rides along explicitly (unset → all), with rankScore stable across filters because the server computes it independently; one inline hint explains the ranking; and multi-select works exactly as in the day modes (checkboxes + selection action bar, every sort mode): tiles stay occurrence-keyed, but selection speaks MEDIA ids — MediaGrid's optional selectionKey maps each face tile to its media, so a multi-face photo is one selection unit and the action bar counts distinct media. MediaGrid gains an optional pre-computed sectionGroups prop rendered verbatim (no day grouping, no per-bucket re-sort, no day-key parsing, days=[] and no day windowing); every existing caller passes null and is unchanged. Leaving Score goes through the existing reset+refetch path (loadSequence bump, day/item caches cleared) so day items and score items never mix, and the day endpoints are never called with sort=score — the client type for them stays 'captured' | 'added'.
Consequences
['No new endpoint: Score view is entirely served by the face-thumbnails read path — which gained filter parameters (mediaType, favorite, from, to, confirmation) rather than a dedicated Score API; the day-bucket endpoints keep their frozen captured/added sort contract (normalizeClassInstanceDaySort continues to 400 anything else).', "Score view supports the same filters as every other sort mode — media/date via the shared day-wall serialization, confirmation via the endpoint's own parameter (tentative faces included when chosen) — served by the extended face-thumbnails read path; bulk selection is available in every sort mode, Score included, off the same media-id selection model as the day walls (no endpoint change was needed — remove and split already speak media and occurrence ids).", 'Score sections can be partially loaded (top-down): a bin's count reflects loaded faces until pagination completes; the passive "N of M faces" status line (and "End of results." once nextCursor runs out) makes partial state explicit without a manual load-more control.', 'Overlay prev/next in Score mode is score-ordered and deduped by media item (a photo with several scored faces steps once); it is not the day-order navigation of captured/added views — no cross-mode navigation promise is made.', "MediaGrid's sectionGroups contract must stay verbatim: any future day-key parsing, re-sorting or windowing applied to pre-computed groups would corrupt score order.", 'e2e/unit specs for the instance-page sort menu gain Score-option coverage (aria-checked, no sort=score day requests, filter trigger visible with filter params on face-thumbnails, scroll-triggered auto-load, badge) in a follow-up test lane.', 'Background refreshes (e.g. after confirming a tentative face) reload the face list only while at most one page (300 faces) is loaded; with more pages loaded the list is left untouched, so a refresh never silently collapses loaded pagination back to page 1 — the multi-page case deliberately defers to the next explicit refresh. Under confirmation=tentative a confirm does change membership and the single-page reload picks that up; scores themselves never change on a confirm, because the scoring pool is accepted+tentative either way.']
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