1 ADR 0030 geonames import source modes
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0030: GeoNames Import Source Modes

Status: accepted Date: 2026-05-22

Context

ADR 0029 accepts managed GeoNames install/import controls. The remaining transport question is how Memories obtains GeoNames files for import. Self-hosted installations vary: some have normal outbound internet access, some are intentionally locked down, and some operators prefer downloading files themselves for audit, caching, or reproducibility.

Memories should make the common case easy without making network download mandatory.

Options Considered

Option Summary Benefits Costs / Risks
A. Direct managed download only Memories downloads GeoNames files from configured URLs Best UX Fails for offline/locked-down installs; app network access required
B. Admin-uploaded files only Super Admin uploads GeoNames files through UI/API Works offline; explicit file provenance Awkward for large files; browser upload limits/timeouts
C. Configured local directory only Operator places files in a mounted import directory Good for large/offline files; scriptable More filesystem/deploy setup; less friendly UI
D. Hybrid source modes Support direct download, admin upload for small/specific files, and configured local directory Flexible for self-hosters More implementation and validation paths

Decision

Support hybrid GeoNames import source modes:

  1. Direct managed download: Super Admin selects countries/regions/levels/languages; Core downloads required GeoNames files from configured/default source URLs after explicit confirmation.
  2. Configured local import directory: operator places GeoNames files in a mounted directory; Super Admin selects files/scope from Admin UI/API; preferred fallback for large/offline/locked-down imports.
  3. Admin-uploaded files: optional convenience path for small extracts or metadata files, subject to file-size limits and resumability constraints.

All modes must produce the same GazetteerImportProfile and provenance shape: source mode, source URL or file identity/path, checksums where available, selected countries/regions, selected levels, selected languages, dataset dump date/version, attribution/license, imported/skipped counts, and errors.

Direct download is the convenience default in connected deployments, but it must not run automatically on fresh installs. Local directory import is the required offline/locked-down path. Admin upload may be implemented later if large-file UX is not worth first-slice complexity.

Consequences

Positive

  • Supports both convenient home installs and locked-down/offline self-hosting.
  • Avoids making browser upload the only path for large GeoNames files.
  • Keeps import provenance uniform across source modes.
  • Allows future scripted/operator-managed dataset caching.

Negative / Costs

  • More Admin/API/job states than one transport path.
  • Local directory mode needs documented Docker Compose volume/path configuration.
  • Direct download needs timeout, resume/retry, checksum/source validation where possible, and clear errors.
  • Admin upload may be deferred if it adds too much complexity.

Revisit Triggers

Revisit this decision if:

  • Direct GeoNames download terms discourage app-managed download.
  • Most operators prefer volume/file import and direct download is rarely used.
  • Admin-uploaded files prove unnecessary or too fragile for large datasets.
  • A future package manager or dataset mirror makes a single source mode sufficient.