1 ADR 0029 managed geonames install and import controls
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0029: Managed GeoNames Install And Import Controls

Status: accepted Date: 2026-05-22

Context

ADR 0024 intentionally avoids bundling or automatically downloading a worldwide gazetteer by default. However, requiring the operator to manually fetch files outside Memories would make the feature harder to use. Christian wants Memories itself to be able to install GeoNames, and wants the Super Admin to control which kinds of resolution and additional languages are imported.

This pushes convenience against local-first/operator-explicit control:

  • Memories should make local GeoNames setup practical from the Admin UI/API.
  • Memories must not silently download large datasets or hide attribution/license/storage costs.
  • Import scope should be tunable so small households can avoid unnecessary storage and import work.
  • Language import should be explicit because alternate names can substantially increase data volume and influence title language behavior.

Options Considered

Option Summary Benefits Costs / Risks
A. Manual file import only Admin downloads GeoNames externally and points Memories at files Minimal downloader complexity; strong operator control Poor UX; easy setup mistakes; harder status/updates
B. Automatic default GeoNames install Memories downloads/imports data automatically Best convenience Violates no-surprise posture; storage/network/license surprise
C. Managed Super Admin install/import Memories provides explicit download/import tooling with scope controls Practical UX while preserving consent and visibility More Admin/API/jobs complexity
D. External online provider instead Avoid local import Fast labels Violates local-first/default-private posture

Decision

Provide managed GeoNames install/import tooling, initiated and configured by a Super Admin.

Memories may download GeoNames country/world files and related alternate-name data itself, but only after explicit Super Admin action that shows source, license/attribution, approximate size where known, selected scope, and import/update behavior. Fresh installs still do not automatically download or import GeoNames.

The Super Admin must be able to configure at least:

  1. Geographic scope: one or more countries/regions, and optionally worldwide import as an explicit advanced choice.
  2. Resolution/import levels mapped into ADR 0025 normalized levels, for example:
    • country
    • admin_region
    • city
    • locality
    • geographic_area
    • venue/POI/toponym where the provider data can support it
  3. Alternate-name languages: no alternate names, selected language codes, or possibly all languages as an explicit advanced/high-storage choice.
  4. Update mode: manual update first; scheduled update may be added later only with visible operator configuration.

The import job records selected countries/regions, selected normalized levels, selected languages, source URLs/files, GeoNames dump date/version, license/attribution, imported counts by level/language, skipped counts, errors, and storage estimate where available.

The selected import scope should remain curated rather than importing every GeoNames feature code. The next production-quality iteration includes A.ADM1-A.ADM4 administrative levels, common populated-place and neighborhood codes, selected landscape/beach/water/destination codes, and selected tourism/landmark/leisure venue codes. It excludes broad/noisy/privacy-sensitive classes such as hotels, restaurants, schools, hospitals, private/residential buildings, farms/estates, and generic buildings unless a later validation pass explicitly promotes them.

Where the selected scope imports A.ADM1-A.ADM4, the import/update process may derive non-authoritative administrative coverage geometry from descendant toponyms, parent clipping, and sibling subtraction. This is a title-selection aid with provenance, not an official boundary import.

Consequences

Positive

  • Makes local-first place lookup practical for self-hosters.
  • Preserves explicit operator consent and avoids hidden worldwide downloads.
  • Lets households tune storage/quality tradeoffs.
  • Supports title localization and local names without importing every alternate name by default.

Negative / Costs

  • Requires downloader/import job design, progress, failure recovery, and checksum/source validation.
  • Requires mapping GeoNames feature classes/codes into ADR 0025 levels according to selected import resolution.
  • Alternate names/languages add storage and title-selection complexity.
  • Worldwide/all-language/all-resolution imports may be heavy and need warnings.

Boundaries Preserved

  • GeoNames remains a provider candidate, not the domain model.
  • No automatic install happens on fresh deployments.
  • External online reverse lookup remains opt-in and separate from downloading public GeoNames dump files.
  • Product features still consume normalized provider-neutral place labels.

Revisit Triggers

Revisit this decision if:

  • GeoNames download terms, rate limits, or attribution requirements make in-app download unsuitable.
  • Operators prefer volume/file-based import over network download from the app.
  • Import resolution/language controls are too complex for the Admin UX.
  • Another local gazetteer provider becomes the preferred first managed installer.