1 ADR 0031 defer admin uploaded geonames files
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0031: Defer Admin-Uploaded GeoNames Files

Status: accepted Date: 2026-05-22

Context

ADR 0030 accepts hybrid GeoNames import source modes and leaves admin-uploaded files optional. The first implementation slice needs a clear boundary: direct managed download covers connected deployments, and configured local import directory covers offline/locked-down or large-file workflows.

Browser/admin upload adds separate complexity: large upload resumability, reverse proxy limits, temporary storage, checksum handling, progress UX, failure recovery, and security scanning/validation. Those are solvable, but not necessary if direct download and local directory modes exist.

Options Considered

Option Summary Benefits Costs / Risks
A. Include admin upload in first slice Super Admin uploads GeoNames files through UI/API Convenient for small files; no shell/volume access Large-file fragility; proxy/timeouts; extra temporary storage/security concerns
B. Defer admin upload First slice supports direct download and configured local import directory Simpler and more robust; covers connected/offline cases Less convenient for operators without volume access
C. Never support upload Keep imports download/directory only Lowest complexity May frustrate non-technical admins later

Decision

Defer admin-uploaded GeoNames files from the first implementation slice.

The first slice should support:

  1. direct managed download from configured/default GeoNames source URLs; and
  2. configured local import directory for offline, locked-down, cached, or large-file workflows.

Admin upload remains a future optional source mode. If added later, it must reuse the same GazetteerImportSource and provenance model and must address size limits, resumability, temporary storage cleanup, checksums, and reverse proxy behavior.

Consequences

Positive

  • Reduces first-slice implementation and operational risk.
  • Avoids large browser upload/reverse-proxy failure modes.
  • Still supports both connected and offline deployments.
  • Keeps import provenance model ready for upload later.

Negative / Costs

  • Super Admins without shell/volume access must use direct download rather than upload.
  • Some hosted/self-hosted setups may find local directory configuration less convenient.

Revisit Triggers

Revisit this decision if:

  • Operators frequently cannot use direct download or configured local directory.
  • Small GeoNames metadata/alternate-name file upload would materially improve UX.
  • A resumable upload infrastructure already exists elsewhere in Memories and can be reused safely.