1 ADR 0035 automatic album clustering research gate
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0035: Automatic Album Clustering Research Gate

Status: accepted Date: 2026-05-22

Context

Automatic album suggestions depend on finding coherent family-memory clusters from capture time and location. Poor clustering would be worse than no automation: it would create noisy suggestions, repeatedly annoy owners, or imply false trips/events.

The first implementation could use a simple deterministic heuristic, but Christian prefers to evaluate DBSCAN/HDBSCAN-like clustering before committing to the first production algorithm. This deliberately favors suggestion quality and long-term fit over the fastest implementation path.

The decision must still respect Memories' architecture:

  • Core owns suggestion generation, provenance, fingerprints, acceptance/rejection, and authorization.
  • The browser must not receive unrestricted media/location rows to cluster client-side.
  • Clustering must be owner-scoped and location-visibility aware.
  • Algorithm output must remain inspectable, deterministic enough for rejection fingerprints, and replaceable across versions.
  • Original media bytes, coordinates, and accepted/manual albums are never modified silently.

Options Considered

Option Summary Benefits Costs / Risks
A. Implement deterministic heuristic first Use simple temporal buckets plus spatial grid/geohash grouping Fast, boring, inspectable, easy to ship May split/merge real trips poorly; hardcoded thresholds may become throwaway work
B. Research DBSCAN/HDBSCAN-style clustering before implementation Evaluate density-based algorithms and baselines against real/synthetic family-memory scenarios Better chance of useful suggestions; avoids committing to weak algorithm too early Slower first delivery; requires local evaluation harness and explicit criteria
C. Defer automatic albums entirely Do not work on suggestions until more product demand exists No immediate complexity Leaves reverse lookup unused by its main motivating feature
D. Use external/ML event recognition Rely on external services or broader AI models to infer events Potentially richer event detection Conflicts with local-first/privacy posture; hard to inspect; cloud dependency risk

Decision

Choose Option B: research DBSCAN/HDBSCAN-style clustering before the first automatic-album implementation slice.

This ADR does not select DBSCAN, HDBSCAN, OPTICS, ST-DBSCAN, or a deterministic baseline as the production algorithm. It creates a research gate: implementation tasks for persisted album suggestions should wait until an empirical comparison identifies the first algorithm profile, thresholds, provenance shape, and failure/degradation behavior.

The research must compare at least:

  1. deterministic temporal bucket + geohash/grid baseline;
  2. two-phase temporal segmentation followed by spatial DBSCAN;
  3. spatio-temporal DBSCAN/ST-DBSCAN-style distance model;
  4. HDBSCAN or OPTICS-style variable-density candidate, if a maintainable local implementation exists.

The chosen algorithm profile must be versioned and stored with every AlbumSuggestionRun so future algorithm changes can coexist with old suggestions, rejected fingerprints, and accepted-album provenance.

Consequences

Positive

  • Reduces risk of building a noisy suggestion generator that users stop trusting.
  • Makes clustering quality, thresholds, and edge cases explicit before schema/API tasks assume them.
  • Keeps the algorithm replaceable by requiring versioned run provenance from the start.
  • Encourages real-family-library validation without weakening owner/privacy boundaries.

Negative / Costs

  • Delays the first visible automatic-album feature.
  • Requires a local-only evaluation harness and scenario fixtures before production implementation.
  • May introduce dependency questions if HDBSCAN/OPTICS libraries are considered for Java/Core.
  • Research may still conclude that a simple baseline is best for the first production slice.

Privacy / Security Impact

  • Research data must remain local. Any exported comparison corpus must be anonymized and should avoid raw exact coordinates unless explicitly kept inside the local developer environment.
  • Evaluation outputs should prefer media IDs, rounded/geohashed locations, cluster metrics, and human-readable local summaries over raw GPS dumps.

Revisit Triggers

Revisit this decision if:

  • research shows deterministic heuristics clearly outperform density-based approaches for Christian's library;
  • no maintainable local DBSCAN/HDBSCAN/OPTICS implementation fits the Core API operational model;
  • clustering research blocks product progress for too long without improving expected suggestion quality;
  • automatic albums shift from owner-private suggestions to collaborative/group-first generation;
  • performance on large libraries makes the chosen algorithm impractical without a worker/offline batch boundary.