1 ADR 0026 place provider attribution surfacing
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0026: Place Provider Attribution Surfacing

Status: accepted Date: 2026-05-22

Context

ADR 0022 defines a reverse place lookup boundary for local gazetteers and optional online providers. ADR 0024 chooses operator-installed country/region imports, initially likely GeoNames or equivalent sources. Many place datasets/providers have attribution requirements. GeoNames data, for example, is provided under a Creative Commons Attribution license.

Attribution needs to be visible enough to satisfy provider/license obligations and preserve inspectability, without cluttering every album card or media detail surface with noisy legal text. It must also survive export/backup so generated titles and labels remain understandable outside the app.

Options Considered

Option Summary Benefits Costs / Risks
A. Admin-only attribution Show provider/license only in Admin settings Low UI clutter Weak for exported/user-visible derived labels; may not satisfy attribution terms
B. Global About attribution List active/used providers in About/legal page Central and discoverable Does not explain individual generated labels
C. Contextual provenance only Show attribution only in title/label provenance drawers Precise and inspectable Easy to miss; less useful for operator/license overview
D. Layered attribution Record attribution everywhere in provenance/export, show provider status in Admin/About, and expose contextual attribution where labels/titles are inspected Balanced inspectability and UI calm Requires more plumbing and consistent copy

Decision

Use layered attribution for place providers.

Memories must:

  1. store attribution requirements with PlaceLookupProvider, LocalGazetteerDataset, CachedPlaceLabel, and generated title provenance where provider-derived labels are used;
  2. show provider/dataset attribution, license/source, version/date, and import status in Admin place lookup settings;
  3. provide a global About/Legal/Data Sources surface listing configured or used place datasets/providers and their attribution text;
  4. show contextual attribution/provenance when a user inspects an automatic album title, place label, cached lookup result, or export record derived from a provider;
  5. include provider/source/version/attribution in JSON/JSONL export wherever place labels contributed to exported suggestions, albums, Places, or metadata.

Normal album/timeline cards do not need persistent visible attribution text for every title. They should offer access to provenance where relevant rather than cluttering the primary family-memory UI.

Consequences

Positive

  • Keeps provider/license obligations visible and auditable.
  • Preserves Memories' inspectability goal without turning everyday album browsing into a legal surface.
  • Makes exported generated titles understandable outside the app.
  • Supports multiple providers with different attribution requirements.

Negative / Costs

  • Requires attribution fields to flow through provider import, cached labels, generated titles, Admin UI, About/Legal, and export.
  • UI copy must distinguish provider attribution from authoritative media metadata.
  • Some provider terms may require stronger or more prominent display than this default; those providers may need per-provider ADRs or implementation rules.

Revisit Triggers

Revisit this decision if:

  • A chosen provider's license/terms require attribution placement stronger than layered attribution.
  • Users find contextual provenance too hidden for trust.
  • Admin/About attribution becomes confusing with multiple datasets/providers.
  • Public sharing or externally published album pages are introduced and need different attribution display rules.