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.
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