ADR-0012 — Basemaps: locally hosted reference data first, cascaded external WMS as a complement¶
Date: 2026-09-02 · Status: accepted (validated by prototype 7)
Context¶
Maps need a background layer. It can be produced from downloaded reference data hosted in the platform, or proxied from an external provider (cascade). The platform must control licences, availability and load put on third parties.
Decision¶
- Hosted reference data is the default: public-domain datasets (Natural
Earth for the prototype) loaded into the
basemapschema by anogr2ogrJob, published with code-managed SLD styles, cached on S3. Source archives come from the internal artifact repository in production (ADR-0007). - Cascaded external WMS is an optional complement (
BASEMAP_WMS_*), served and tile-cached by GeoServer — subject to the provider's terms of use and availability; disabled by emptying the URL. - Both patterns are configured by the init plugin — nothing manual.
Rejected alternatives¶
| Alternative | Why rejected |
|---|---|
| External tiles fetched directly by clients | No caching control, mixed origins, licence checks pushed to every client |
| Cascade as the only basemap | Availability and licence dependency for a core visual function |
| Raster basemap generated offline (pre-rendered tiles) | Heavier pipeline; can be added later without changing the architecture |
Consequences¶
- Basemap updates are data loads (Job), not configuration changes.
- The cascaded provider can be swapped or disabled by ConfigMap.
- Vector-tile (MVT) or relief basemaps can be added later under the same declarative mechanism.