1 ADR 0018 map tile provider boundary
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0018: Map Tile Provider Boundary

Status: accepted Date: 2026-05-21

Context

Places/Map has been promoted into the v1 baseline. Memories should let a family browse visible geotagged media on a map and see a small map preview in media detail, while preserving the project's privacy-first and self-hosted/local-first priorities.

Map rendering introduces a dependency that is different from Memories' own media/location data. A tile provider can supply visual map imagery, but it must not own coordinates, sharing semantics, location provenance, backup/restore truth, or export data. External tile providers also create a privacy leak: they can observe client IP address, approximate viewport/zoom area, request timing, and user agent. That is acceptable only if explicit and replaceable.

Options Considered

Option Summary Benefits Costs / Risks
A Hard-code OpenStreetMap tiles Fastest implementation, familiar map style Creates hidden external dependency, makes later switching/self-hosting harder, weak privacy story
B Require self-hosted tiles for v1 Strongest privacy/local-first posture High operational burden, large data/storage requirements, makes v1 harder to finish
C Configurable tile provider abstraction with OpenStreetMap-compatible default/template Practical v1 delivery, explicit privacy disclosure, supports self-hosted/alternate providers later Slightly more configuration/design work; external-provider privacy risk remains when chosen

Decision

Use option C.

  • v1 Map and media-detail map previews use a configurable map tile provider boundary.
  • An OpenStreetMap-compatible provider/template is acceptable as the practical v1 default or example.
  • v1 uses Leaflet as the browser map renderer because it is a boring, mature raster-tile library that fits OpenStreetMap-compatible {z}/{x}/{y} tile templates and simple self-hosted tile services.
  • Operators must be able to switch to another URL/template or a self-hosted tile service without code changes.
  • Tile providers are presentation dependencies only. They do not own Memories coordinates, effective location metadata, media visibility, sharing policy, backup/restore truth, or exports.
  • Core API remains authoritative for map viewport results, clustering inputs, media visibility, location-sharing policy, and media-detail location disclosure.
  • The web client must not receive unrestricted raw location rows and then enforce privacy itself; it should request authorized viewport/cluster data from Core API.
  • Memories must disclose that external tile providers may observe client IP address, tile/viewport/zoom area, request timing, and user agent. Self-hosted tiles are the privacy-preserving option for operators who want Map without third-party tile requests.

Reverse geocoding, provider-backed place names, offline tile packs, vector tile generation, routing, and cloud enrichment are not part of this decision.

Consequences

  • Map can be delivered in v1 without turning self-hosted tile infrastructure into a prerequisite.
  • The architecture keeps local media/location authority independent from any map vendor.
  • Privacy tradeoffs are visible rather than hidden: using external tiles is convenient but leaks viewport behavior; using self-hosted tiles is more private but operationally heavier.
  • The frontend needs a small provider configuration model rather than hard-coded tile URLs.
  • Core API needs an authorized map viewport/clustering read boundary so map counts cannot leak private or unshared locations.
  • Backup/restore/export remain centered on PostgreSQL/media storage/configuration; tile cache/provider responses are not authoritative media data.

Revisit Triggers

Revisit this decision if:

  • Memories adds provider-backed reverse geocoding or place-name enrichment.
  • The project wants offline-first maps or bundled/self-hosted vector tiles as the default.
  • Public internet deployment becomes a supported threat model requiring stronger tile proxying or request anonymization.
  • A tile provider's terms, rate limits, attribution requirements, or privacy behavior make the v1 default unsuitable.
  • Map usage becomes heavy enough that tile caching/proxying is needed for reliability or privacy.