1 ADR 0024 operator installed country region gazetteer imports
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0024: Operator-Installed Country/Region Gazetteer Imports

Status: accepted Date: 2026-05-22

Context

ADR 0022 defines a local-first reverse place lookup boundary and ADR 0023 selects PostgreSQL + PostGIS for storage/indexing. The next decision is how Memories should package and scope the first local gazetteer data.

GeoNames offers worldwide and country-level downloads. A worldwide import may be convenient for globally distributed libraries, but it increases first-use storage, import time, attribution/documentation burden, backup/restore expectations, and operational surprise. Most household libraries initially need countries/regions where the family actually takes photos.

This decision should preserve local-first operation without making a large third-party dataset a hidden required payload of Memories itself.

Options Considered

Option Summary Benefits Costs / Risks
A. Bundle worldwide gazetteer Ship/import a worldwide GeoNames-like dataset by default Best out-of-box coverage Large artifact; attribution/distribution complexity; import/update cost; surprising dependency
B. Bundle selected country examples Include one or a few sample country datasets Easier demos Arbitrary country bias; still distribution/attribution burden; not enough for real users
C. Operator-installed country/region extracts Admin chooses/imports needed GeoNames country/world files or equivalent local datasets Lightweight default; explicit attribution/source; scalable to household needs Requires setup/import UX and documentation before useful labels appear
D. Online provider first Avoid local dataset packaging Fast labels; no import storage Violates local-first/default-private posture

Decision

Start with operator-installed country/region gazetteer imports, plus tiny fixture data for tests/development.

Memories will not bundle or automatically download a worldwide gazetteer as part of the core application by default. The first production path should let a Super Admin install or import one or more country/region extracts, initially likely GeoNames country files or equivalent local datasets, into the PostGIS-backed provider-neutral tables. Worldwide import can be supported as an explicit operator choice later, but it is not the default.

ADR 0029 refines this posture: operator-installed may include Memories-managed GeoNames download/import tooling, as long as installation is explicit Super Admin action with scope, resolution, language, license/attribution, and storage implications shown before work starts.

The Admin/operator surface should make dataset absence an understandable degraded state: reverse lookup is unavailable or fallback-only until a local dataset is imported or an external online provider is explicitly enabled.

Consequences

Positive

  • Keeps default deployments lighter and less surprising.
  • Avoids distributing a large third-party dataset with the application before license/attribution/update obligations are fully operationalized.
  • Encourages explicit operator awareness of dataset source, version, coverage, and attribution.
  • Supports small household deployments that only need a few countries/regions.

Negative / Costs

  • Automatic album titles may have weak/fallback place labels until the operator imports data.
  • Requires import UX/docs/status before the feature feels complete.
  • Cross-border trips or globally mixed libraries may require several imports or an explicit worldwide import.
  • Country extracts may lack enough context near borders or for geographic areas/venues.

Boundaries Preserved

  • GeoNames remains a replaceable provider candidate, not a bundled domain dependency.
  • External online providers remain opt-in only.
  • Fixture data is for tests/development and must not be mistaken for production coverage.

Revisit Triggers

Revisit this decision if:

  • Users consistently expect useful place labels immediately after install and accept the cost of bundled data.
  • GeoNames or another provider offers a redistribution/package format that makes default local data low-cost and license-clear.
  • Import UX proves too burdensome for self-hosters.
  • Automatic album quality is unacceptable without broader default coverage.