1 ADR 0021 time location album suggestions
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0021: Time/Location Automatic Album Suggestions

Status: accepted Date: 2026-05-22

Context

v1 supports owner-owned manual albums/events. It intentionally defers automatic album creation from folders and group-owned collaborative albums. Memories now needs a post-v1 direction for automatic album-like organization based on how family memories naturally cluster: trips, visits, weekends, vacations, and events often appear as media sets with coherent time periods and nearby locations.

Christian's desired behavior is:

  • co-cluster media by time and location;
  • identify media sets with a coherent time period and spatial area;
  • propose a title using the narrowest useful time period and place area;
  • examples of place granularity include toponym/venue (Landal Sonnenberg), city (Trier), geographic area (Eifel), land/state/region (Rheinland-Pfalz), and country (Germany);
  • choose the place level according to the suggestion shape: compact local events may use narrow venue/locality/city labels, while multi-place regional trip parents should prefer a common containing administrative/geographic area such as Trier-Saarburg, Saarburg-Kell, or Eifel over a child/centroid-nearby place such as Holzerath;
  • show the result as a suggestion and let the owner accept it;
  • follow the same broad collaboration direction as People: create/curate locally first, then share a separate ownable/forkable collaborative album/event identity so other owners may contribute their own media without transferring ownership.

This intersects with existing privacy and ownership decisions:

  • album membership must not copy or mutate originals;
  • Super Admin/group roles must not bypass media-owner authority;
  • location metadata visibility is policy-controlled;
  • map tiles and future reverse-place providers are presentation dependencies, not authoritative location owners;
  • external online provider use must not become a hidden cloud dependency;
  • useful generated place titles likely require a local gazetteer/reverse-place index such as GeoNames or an equivalent downloadable dataset.

Options Considered

Option Summary Benefits Costs / Risks
A. Automatically create real albums Core silently creates albums from detected clusters Immediate organization, low user friction Clutters library, surprises users, hard to undo, risks overwriting user intent
B. Suggestions first, owner accepts Core creates owner-private suggestions; accepted suggestions become normal albums Preserves owner agency, easy review/reject, compatible with manual album semantics Requires suggestion state, review UI, rejection memory
C. Only transient Explore/Event cards Show generated clusters but never convert to albums No album model changes, low permanence Users cannot curate/save them as durable albums
D. Group/collaborative generated albums first Generate shared family event albums from visible shared media Useful family feature Hard authority problem: who accepts/edits/rejects, whose location metadata may title it, how revocation behaves
E. Owner-local first, then share CollaborativeAlbumEvent identity Owner accepts a local album/event, then shares a separate ownable/forkable collaborative identity so others can contribute their own matching media Mirrors collaborative People direction; preserves ownership and agency Requires future collaborative album/event roles, contribution, and fork policy

Decision

Adopt owner-local suggestions first, then a shareable, ownable, forkable CollaborativeAlbumEvent identity as the target model.

Automatic album generation creates owner-private AlbumSuggestion records. A suggestion becomes a normal owner-owned AlbumEvent only after explicit media-owner acceptance. Once accepted, the album follows normal album semantics: owner-editable name/description/membership/order, no original-byte mutation, and no silent regeneration overwrites.

The long-term collaboration model follows the People direction from ADR 0013: a user curates locally first, then shares a separate ownable collaborative identity. Other invited media owners may contribute their own matching media according to explicit contribution actions or owner policy. The CollaborativeAlbumEvent owns the curation graph, roles, contribution policy, and fork/retention history; it does not own original media bytes.

Album collaboration should mirror Person collaboration unless there is an explicit album-specific reason to diverge:

  • roles: album_owner, album_admin, contributor, viewer;
  • share policies: allow, require_album_admin_approval, deny, with future per-action overrides;
  • contribution states: suggested, pending_album_admin_approval, accepted, rejected, revoked, superseded;
  • fork semantics: when collaboration ends, each side keeps a usable album/event identity over contributions it is allowed to retain, with provenance linking source, reason, retained/removed contribution sets, and new owner/admin selection.

Default collaborative album/event policy is conservative: invited owners receive private manual contribution suggestions; newly shared albums default to require_album_admin_approval; allow is an explicit owner/admin choice for trusted audiences; and owner-controlled auto-contribution, if later added, is disabled by default per owner and per collaborative album/event.

Album forks retain only visible-and-allowed album state. A fork may keep retained contributions, visible title/description, ordering over retained contributions, a retained or replacement cover, permitted captions/comments/notes, and generated-title provenance that does not newly expose hidden coordinates or place metadata. Removed contributions and hidden metadata do not leak through the fork.

Rules

  1. Suggestions are not albums: A generated suggestion is reviewable metadata, not a user-visible normal album until accepted.
  2. Owner acceptance is required: Core must not silently create durable albums from clustering output.
  3. Accepted suggestions become normal owner-owned albums: Acceptance creates an AlbumEvent and AlbumItem references using existing album lifecycle rules.
  4. Manual edits win: After acceptance, owner edits to album name, order, membership, or description must not be silently overwritten by later clustering runs.
  5. Core-owned clustering: Core owns generation, state transitions, acceptance/rejection, fingerprints, and provenance. The browser does not receive unrestricted private media/location data and cluster locally.
  6. Owner-private first slice: Initial generation operates on the current owner's own active media, but the model should prepare for later CollaborativeAlbumEvent sharing.
  7. Collaborative identity is separate from media ownership: A CollaborativeAlbumEvent owns curation and contribution relationships, not original media bytes.
  8. Album identity links do not grant media visibility: Other owners' media appears only through explicit contribution or owner-authorized contribution policy.
  9. Contribution suggestions are owner-private: Invited owners may receive suggestions over their own matching media, but those suggestions remain private until accepted or auto-contributed by that owner.
  10. Roles and policies mirror People: CollaborativeAlbumEvent roles, share policies, contribution states, and fork mechanics should match CollaborativePerson semantics by default.
  11. Admin approval is the default shared-album policy: New collaborative album/event shares default to require_album_admin_approval; allow must be explicitly chosen for trusted audiences.
  12. Auto-contribution is disabled by default: Owner-controlled auto-contribution may be added later, but it must be scoped, revocable, auditable, and off unless the contributing owner explicitly enables it for that collaborative album/event.
  13. Fork/retention must preserve usable album state: Ending collaboration must not delete another owner's media or local album state; each side can keep a usable fork over retained contributions and visible-and-allowed album metadata only.
  14. Location privacy applies: Suggestions and generated titles must not expose coordinates or place names to users who cannot see the underlying location metadata.
  15. No required external online geocoder: Clustering works from stored Core metadata. Useful place-name enrichment should use user/local/fallback sources first, preferably through a local gazetteer/reverse-place index. External online geocoding/place providers, if added, are opt-in with privacy disclosure and provider provenance.
  16. Place names are title metadata: Generated toponyms/place labels are presentation/title metadata unless the owner explicitly saves them as album titles or separately edits media location metadata. They do not become authoritative coordinates or EXIF/location overrides.
  17. Rejected suggestions have memory: Rejected/dismissed suggestions retain a stable fingerprint so unchanged clusters do not reappear immediately.
  18. Parent titles describe the parent: Regional trip/vacation parent titles should describe the containing trip area. Narrow child labels may be shown as child/highlight evidence, but they should not become the parent title when they cover only part of the parent.
  19. Centroid-nearest villages are not parent titles: Regional parent title selection must not use a centroid-nearest city/village merely because a synthetic point-derived buffer intersects the candidate. Child/event anchors and common administrative/geographic containment evidence must agree; otherwise the title should use a child-place summary or neutral fallback.
  20. Derived admin coverage may support title selection: For administrative GeoNames levels A.ADM1 through A.ADM4, reverse lookup may provide non-authoritative derived coverage polygons from descendant toponyms and sibling partitioning. Automatic album titles may use these as evidence for a smallest common administrative ancestor, but must keep provenance and must not present them as official boundaries.

Consequences

Positive

  • Memories can surface trip/event structure without taking control away from the owner.
  • The feature composes with v1 albums instead of redefining album ownership.
  • The long-term model aligns with collaborative People rather than inventing a separate family-sharing mental model.
  • Rejected suggestions and accepted suggestion provenance make automation inspectable and reversible.
  • Manual albums remain stable and intentional.
  • External online geocoding is avoidable; local-first operation remains possible with a local gazetteer or fallback titles.

Negative / Costs

  • Requires new suggestion/run/decision state rather than simply inserting albums.
  • Requires implementing CollaborativeAlbumEvent roles, contribution policy, and fork policy before shared family event albums can be complete, but these mirror already-decided Person semantics.
  • Conservative defaults add review friction for trusted households until they explicitly choose allow or future scoped auto-contribution.
  • Needs a review UX in Albums or a related suggestion surface.
  • Requires careful duplicate/suppression logic so suggestions do not annoy users.
  • Good titles likely require a local gazetteer/reverse-place dataset or explicit external online place provider.
  • Co-clustering thresholds may need tuning against real family libraries.

Privacy And Security Impact

  • Time/location clusters reveal movement patterns. Suggestion APIs must remain owner-authorized and scope-aware.
  • Shared media whose location metadata is withheld must not contribute to visible shared suggestions or place titles for other users.
  • Album/event identity sharing must not reveal invited owners' matching private media until they explicitly contribute or configure policy.
  • External online place providers can reveal coordinates/areas/timing and must be disclosed and opt-in.
  • Local gazetteer datasets still carry license, attribution, storage, update, and quality implications.

Backup / Export Impact

  • Fidelity backup should preserve pending/rejected/accepted/superseded suggestion state, clustering runs, fingerprints, and accepted-album links.
  • JSON/JSONL export should include suggestion provenance and title-source metadata so generated albums are inspectable outside the app.

Revisit Triggers

Revisit this decision if:

  • Memories promotes group-owned or collaborative automatic albums.
  • Automatic suggestions should update accepted albums through explicit "suggest adding media" workflows.
  • Album-specific metadata such as cover, ordering, captions, comments, and title provenance require fork/retention rules beyond the visible-and-allowed defaults above.
  • A local gazetteer/reverse-place index becomes a first-class dependency.
  • External online geocoding/place-name providers become common enough to require per-provider ADRs or proxy/anonymization rules beyond ADR 0022.
  • Users prefer transient Explore event cards over durable albums.
  • The chosen clustering algorithm produces too many noisy suggestions or misses obvious trips/events.