Maps Architecture
@prox-os/maps is the Prox OS map and geospatial surface package. It provides
Position
@prox-os/maps is the Prox OS map and geospatial surface package. It provides
contracts, React primitives, provider labels, attribution UI, Storybook examples,
and action intent for maps. It is not a Google Maps clone, a Mapbox clone, or a
full GIS platform.
Prox OS should provide OS-native map surfaces that apps can reuse while leaving tile infrastructure, search, routing, private geodata, and heavy geospatial processing to explicit adapters and future platform services.
Renderer Direction
MapLibre GL JS is the Phase 1 default renderer because it is open source, supports vector tile style workflows, works well with WebGL, and aligns with the future PMTiles / Protomaps / OpenMapTiles / R2 direction.
The React package uses @vis.gl/react-maplibre as the first wrapper. The public
package API stays under @prox-os/maps so apps are not tied directly to one
React wrapper.
OSM Tile Boundary
OSM data is open, but public OSM tile servers are not a production CDN for Prox OS. Production deployments should use self-hosted, static-hosted, cached, or properly licensed tile infrastructure.
Phase 1 stories may use MapLibre demo styles or demo-only tile URLs to prove the package works. Those examples must keep attribution visible and must not be treated as production defaults.
Provider Positioning
| Provider or library | Position | Phase 1 dependency |
|---|---|---|
| MapLibre GL JS | Official default renderer for vector tiles, style specs, WebGL maps, and future PMTiles/R2 integration. | Yes |
| Leaflet | Lightweight fallback for simple markers and low-complexity apps. | No |
| OpenLayers | Advanced GIS fallback for WMS/WFS, projections, and professional data sources. | No |
| deck.gl | Large-scale geospatial visualization overlay for heatmaps, trips, arcs, scatterplots, and data-viz links. | No |
| PMTiles | Preferred future static tile archive direction for Cloudflare/R2. | Type/docs placeholder only |
| Protomaps / OpenMapTiles | Future white-box vector tile sources. | Docs only |
Package Boundary
The maps package emits geospatial action intent. The OS Shell owns system context menu execution.
@prox-os/maps must not import apps/os-shell private window manager, context
menu, registry, or shell state modules. Components can receive callbacks such as
onAction and onContextMenuRequest from the host app.
Phase 1
OsCoordinate,OsGeoPoint,OsMapSource,OsMapLayerConfig, and source reference types.OsMapActionand context action intent types.OsMap,MapLibreMapPreview, marker, popup, layer preview, attribution, provider badge, map card, static placeholder, and mock context action UI.- Storybook examples under UI Workshop.
- Demo-only MapLibre style notices and visible attribution.
Phase 2: PMTiles / R2 / Cloudflare
- PMTiles adapter.
- R2-hosted map archives.
- Protomaps / OpenMapTiles documentation.
- Cloudflare caching strategy.
- Cloudflare Worker signed/private tile access.
- Workspace-aware tile policy.
Phase 3: Places / Geocoding
- Places contract.
- Saved Places app.
- Self-host Nominatim policy.
- Photon and Pelias adapters.
- Search box.
- Reverse geocoding.
Public Nominatim must not be treated as a production high-frequency geocoding API.
Phase 4: Routing / Tracks
- Route planner.
- OSRM, Valhalla, and GraphHopper adapters.
- GPX and GeoJSON import.
- Timeline tracks.
- Moments location history.
Phase 5: Spatial Data OS
- Geo dataset viewer.
- GeoJSON editor.
- deck.gl layers.
- Heatmaps.
- User-owned spatial data.
- Community map spaces.
Non-Goals
- No Google Maps clone.
- No complete GIS platform.
- No production tile service.
- No real geocoding service.
- No real routing engine.
- No map editor.
- No offline map download manager.