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