Cartos — Comprehensive Guide

Sovereign geospatial vertical-AI platform. Last updated 2026-08-01 — two updates, most recent first. Map legibility + the GFM arc's close. (1) Catalog layers now render risk as risk — any layer whose features carry risk_score + risk_tier is automatically drawn as severity (tier colour, tier-graduated size, pulsing target rings, optional name labels), and every feature popup is rebuilt from a 20-row key: value dump into a shaped card with a risk hero band, score-driver bars and grouped, unit-formatted attributes. Both are auto-detected from the data, not configured per layer, so Guardian's 50 strike targets and its 2 500 collateral-risk POIs are one code path and any future layer adopting the same field names inherits it. ⚠ The work uncovered a silent renderer bug — a label layer without an explicit text-font falls back to a font OpenFreeMap does not serve, drawing nothing at all with no error — found only by executing the real layers through a headless MapLibre harness after tsc and vite build were both already clean. Live on prod (d4805bc); see §9.12. (2) The GFM arc completed 2026-07-30 → 08-01 across nine PRs (#136–#148) for under $2 000 of model spend: a frozen open encoder + embedding index + verified operators free multispectral fusion measured at +0.067 accuracy and stored beside the vector rather than concatenated into it, dataset supersession so a re-embed hides its predecessor instead of double-serving it, and a cost gate that is live but deliberately inert (§9.11). ⚠ Stage 1 was measured and declined — the $15–35k continued-pretraining step had a documented falsifier that nobody had ever tested, so the frozen baseline was measured on CPU for nothing; it fired, and the money was not spent. Those sections were written at the time; this changelog entry is the header catching up to them.

Earlier: 2026-07-29 — five updates, most recent first. Security + operability pass, all shipped to main and deployed to prod (verified). (1) Migration 0087 closes an RLS gap on the three Cartos Harvest tables — crop_calendars, field_parcels and farmer_registry each described themselves as tenant-scoped but carried no row-level-security policy, leaving only the app-layer WHERE filter as the boundary; farmer_registry holds PII (name / national_id / phone). The fix pairs ENABLE + FORCE + tenant_team_isolation with a cartos-data/src/harvest.rs change so all nine set_tenant_session call sites forward the caller's real groups instead of &[] — ⚠ the two halves must ship together (see §7). Verified on prod: relrowsecurity and relforcerowsecurity true on all three, zero RLS-violation lines in the API log. (2) The Africa cadastre ingest is now a saved, credentialed, re-syncable connector in Admin → Integrations (migration 0088, connectors/parcel_fabric.rs on the existing RealConnector seam) — credentials stay server-side and the idempotent-upsert + human-review-preservation guarantees hold across re-syncs, turning a one-shot demo call into an operational feed (see §8.4). (3) Admin console usability — module/feature filters on the Modules and Features tabs, and a Test button with a coloured status badge on Catalog and Integrations (see §7.4). (4) Build-pipeline hygiene — the CI gate no longer duplicates itself on every push to main, no longer rebuilds on documentation- or website-only commits, and the mobile iOS build is now run on demand rather than on every mobile push. Earlier today: Cartos Africa's africa-parcel module is wired to a real cadastral store — merged to main and deployed + verified on prod (migration 0086 applied; live-ingest tested end-to-end). africa-parcel went from a surface-only stub to a source-agnostic, LADM-aligned (ISO 19152) parcel + party store (africa_parcels + africa_parcel_parties) that two ArcGIS ingest adapters map INTO, so the same review/scope/export path serves either source: parcel_fabric maps Esri's documented Parcel Fabric information model (Name/StatedArea/ CreatedByRecord/RetiredByRecord/IsSeed/GlobalID — ready to point at a real ArcGIS Enterprise fabric, though no public one exists to demo against), and featureserver is a config-driven field map for any generic ArcGIS parcel/ cadastre service — this is the adapter behind the live demo, verified end-to-end on prod against a real public Esri Tax_Parcels service (8 parcels ingested → summary → LADM export, then cleaned up). New ParcelFabricPanel (admin ingest form, load-in-view, colour by tenure/lifecycle, click-to-review, LADM GeoJSON export) and five routes under /api/africa/parcels/*. This is the ingest half of the module's parcel fabric — an existing authoritative cadastre flowing into the LADM store; the SAM2 segmentation pipeline that generates parcel candidates from imagery (prompts/map-africa/ 07-parcel-fabric-development.md) is still the other, not-yet-built half. See the new subsection in §8.4. Earlier: 2026-07-28 — three updates, most recent first. Cartos Harvest is merged to main (tag cartos-harvest-v1) — the ninth edition is no longer branch-only; every reference to "branch harvest, not yet merged" below is now historical (and as of 2026-07-29 Harvest is deployed and live at https://harvest.cartosatlas.com, with its own Caddy vhost and Keycloak redirect origin like every other edition — see §8.7). The same merge ships persisted derived products (M03) for Harvest: any Crop Type / Health / Yield / Water / Risk panel run can tick "Save to products" to persist its result as a lineage-tracked derived_dataset row (reuses migration 0013 — no new migration), browsable in a new Saved Products panel (SavedProductsPanel.tsx) and queryable by a new harvest_products agent tool (GET /api/harvest/products + /products/:id); and the farmer registry (migration 0085) landed, completing the harv-boundaries module with a FarmerRegistryPanel.tsx + two more agent tools (parcel_fabric_summary, farmer_lookup). A ride-along platform fix in the same merge: the map agent's Anthropic response parser now round-trips Opus 5 thinking/redacted_thinking content blocks verbatim (llm.rs's ContentBlock enum), fixing intermittent 502s on reasoning turns — engine-wide, not Harvest-specific. Earlier the same day: two more updates. First, the ownership/licensing framing was reworked per the Owner's direction: Cartos — the engine and every edition — is the sole and exclusive property of Steven P. Santovasi (the Owner); Solution Strategy Partners (SSP) holds a single unrestricted, perpetual, irrevocable, worldwide, royalty-free, sublicensable master license to all of Cartos; downstream edition instances (Cartos Atlas, Cartos Grid, …) are non-exclusive sublicenses under SSP's master license, not direct grants from the Owner. See the reworked table in §1 and EarthWatch3D-PRD/PRD.md §20 for the full licensing language. Second, §8.7 was added documenting Cartos Harvest — STAC-native crop intelligence (crop type, health, yield, water/drought, field boundaries, agri-risk) for ministries of agriculture, agri-insurers/lenders, and extension services, anchored on Kenya + Nigeria and reusing Cartos Africa's country-scope and foundation-layer fabric. Earlier: 2026-07-26 — Cartos Sentry, the reactive crisis-monitoring edition, is merged to main and LIVE at https://sentry.cartosatlas.com — the eighth live Cartos edition (alongside the newly-documented seventh, Cartos Guardian, live at https://guardian.cartosatlas.com since 2026-07-22). A new §8.6 covers Sentry in full, and a new §8.5 closes the gap and documents Guardian for the first time. Cartos Guardian is the proactive counterpart — UAE critical-infrastructure protection, Strait-of-Hormuz-focused, with a transparent per-site strike-risk model (0-100 score from criticality + Hormuz proximity + category weight) ranking 103 curated sites, a POI-collateral layer, grid/strategic-vector overlays, and live AIS/ADS-B traffic — 5 modules (guard-command/guard-energy/ guard-utilities/guard-emergency/guard-defense), theme Red. Cartos Sentry is the reactive counterpart — optical + SAR + thermal satellite change detection for crisis monitoring: watch Guardian's highest-risk assets → autonomously detect an event → open a scored incident with cross-modality confidence + before/after evidence → report + alert — 3 modules (sentry-command/sentry-detect/sentry-incidents), theme Camo. The Guardian → Sentry handshake is the moat: strike-risk score seeds Sentry's monitoring-watchlist priority (P1/P2/P3), which sizes the commercial-tasking spend a P1 incident can defensibly justify. Sentry ships the platform's first background ingestion loop (sentry_monitor.rs — an opt-in tokio interval daemon that autonomously screens the watchlist, resolves before/after epochs via STAC, runs real model-free detectors, fuses cross-modality confidence, and raises + dispatches incident alerts with dedup, all with no fabricated certainty — a hard "mock guard" means a degraded model sidecar never raises a fake incident), the platform's first incident state machine + outbound alert dispatch, and the platform's first commercial-data-tasking connectors (cost-visible Umbra/Capella/ICEYE/Maxar/Planet vendor cards + a live Umbra open-archive search, for the crisis-hour reactivity open imagery can't deliver). Both editions are author-owned reference instances, not yet licensed externally, live on their own sovereign subdomains exactly like every other edition (hostname-detected, dedicated Caddy vhost + Keycloak redirect origin). Earlier: 2026-07-18 — Cartos Africa (the One Africa edition) is merged to main and LIVE at https://africa.cartosatlas.com — the sixth live Cartos edition, standing alongside Atlas/Grid/Tower/Milepost/Blueprint on its own sovereign subdomain (dedicated Caddy vhost + Let's Encrypt cert + Keycloak redirect origin; hostname → edition detection selects it automatically, same as every other edition — reachable directly, not only via ?edition=africa). A new §8.4 covers it in full: a continental-scale Government edition for African governments, national mapping agencies (NMAs), and ministries — an operational layer over a free/open national-basemap substrate — 9 modules (africa-command + eight use-case departments: Food Sustainability & Agriculture, Health & Immunization, Border Management, Port Management, Land Use & Land Cover, Parcel Fabric Development, Flood & Climate Risk, Settlement Management) on the shared IndustryModule surface (cartos-web/src/modules/africa/, edition preset africa, default theme Desert); a country-scope system (lib/country-scope.tsx → CountryScopeContext, an iso3/adm1 filter that reaches map layers, KPIs, dashboards, and agent answers; CountryScopePanel HUD chip with AU-region quick-groups — North/West/Central/East/Southern — plus a sub-national ADM1 drill-down once exactly one country is selected; geoBoundaries ADM0 — all 54 AU member states — and a priority-country ADM1 set, 147 units across Kenya/Nigeria/Egypt/Ghana/Ethiopia/South Africa); a foundation-layer fabric (FoundationLayersPanel + a typed lib/africa-data-catalog.ts registry of continental imagery/terrain/land-cover/ boundary sources grouped by category — keyless/open entries render live, premium/derived entries list as license-badged reference rows; normative license posture: geoBoundaries not GADM, GLO-30 DSM not FABDEM, Esri imagery view-only, commercial sources never client-keyed); the Continental Command dashboard (features/africa/AfricaCommandDashboard — initiative KPIs, a country- onboarding board, cross-module roll-up charts, honours the current scope); real data loaded into all 8 use-case modules via OpenStreetMap, Natural Earth (public domain), and curated anchors, with truthful caveats — africa-parcel is a built-up-extent reference, not legal parcels, and the flood module's raster/ COG/SAR layers are license-flagged references pending a COG render path (real counts + full caveats in §8.4); and the new africa_scope agent tool (resolve country names / ISO3 codes / an AU region / whole-continent → the canonical scope_iso3 list) plus a countries filter added to query_catalog_layer (§9.6) so "ask the map" answers stay inside the selected scope. Real data loaded in prod across all 9 modules — 7,379 health facilities · 3,011 food/market points · 1,928 built-up-extent parcel-reference polygons · 1,285 settlements · 435 ports · 406 land-cover polygons · 124 flood/hydrology features · 14 border crossings · 201 command boundaries (54 ADM0 + 147 ADM1) — with symbology applied (see the real-counts table in §8.4). Engine-level ride-alongs shipped the same day (apply platform-wide, not just to Africa): the "Satellite · Esri" basemap is now framed as a global high-res imagery option in every module's basemap pulldown, relabelled from a UAE-specific name (§9.4); the agent panel and the External Data Sources drawer now scope to the actual current module (agentFocusFromPath / moduleIdFromPath in shell/AppShell.tsx) instead of always resolving to Smart City on Grid/industry/Africa routes (§7); and every floating popup panel now follows the active theme accent — a 27-file CSS sweep plus two new --accent-rgb/--bg-rgb custom properties so panel borders, glows, resize chips, and glass backgrounds recolour with the platform theme instead of hardcoding holographic cyan (§9.4). Also shipped 2026-07-18, after the merge (engine-wide, every edition): the header edition switcher is now a pulldown (shell/EditionSwitcher.tsx — a single accent-dot + name + caret trigger opening a menu, click-outside/Escape to close) instead of a horizontal pill row, freeing header width so the module-nav tabs fit on one row; Cartos Africa is in the list. Catalog points now render a holographic 3-layer symbology stack — a blurred glow halo in the feature's data-driven color, a bright core "orb" with a rim-light stroke, and an animated sonar-pulse selection ring — instead of a flat circle (lib/catalog-layers.ts, opt out per layer via style.point.halo/pulse), plus feature-type icons drawn on top from zoom 9 — medical cross, anchor, cart, tree, gate, droplet, bolt, graduation cap — auto-classified from each feature's own attributes (amenity/harbour/ natural/boundary/power/…) with zero per-layer config (lib/catalog-icons.ts; migration 0061 gives Africa's border crossings an explicit gate icon). And session vectors now always draw above rasters: a new raiseVectorsToTop re-raises every cat-* vector layer above whatever raster was just added — foundation, satellite, GIBS, STAC, ArcGIS, or a basemap swap — via a self-terminating styledata listener, and the Compare tool's non-"current" panes now copy the session's vectors on top of the compared raster too, matching the main map (§9.6). Earlier: 2026-07-13 (a new §9.10 covering Mapillary crowd-sourced street-level imagery, shipped to main today: a new portable capability feature mapillary (crates/cartos-core/src/catalog.rs FEATURES, seventeenth entry) attachable to any module like Overture. The web overlay (features/mapillary/MapillaryOverlay.tsx, lib/mapillary.ts) pulls Mapillary's public mly1_public MVT vector tileset straight into a MapLibre vector source — no server of ours — as two layers: drive-path mapillary-sequences and mapillary-images photo points (zoom ≥ 14); clicking a photo point resolves it through the Mapillary Graph API (graph.mapillary.com/{id}) and shows the dated street-level image + compass heading in a floating popup, with attribution and an "Open in Mapillary" link. Panel controls: coverage on/off, opacity, a "captured since" year slider, and a 360°-panoramas-only toggle, all persisted per panel; a new camera-icon mapillary kind in shell/PanelDock.tsx. Default-on in the native trio (Smart City, Emergency Services, Maritime) and every industry-edition department module (Cartos Tower/Milepost/Blueprint via IndustryModule) — not Cartos Grid, where it's an admin add-on like any cross-pollinated feature. A new cross-module agent tool mapillary_street_imagery (crates/cartos-agent/src/builtin/mapillary_street_imagery.rs, register_mapillary) searches the Graph API by bbox or point+radius for "is there street imagery of this intersection?"-style questions, with pano_only/since_year/limit filters, returning configured: false gracefully when no server-side token is set. External, community-contributed data — © Mapillary contributors, CC-BY-SA — a reference overlay, not sovereign ground truth (that's Cartos Field); labelled as such in the UI. Needs a free client token (VITE_MAPILLARY_TOKEN, web) and a server token (MAPILLARY_TOKEN, agent tool) — the panel shows a setup notice without one. New backfill migration 0044_enable_mapillary.sql (deploy needs a cartos-api rebuild). Cross-referenced from the feature-registry table in §7.4, the agent tool-registry list in §7, the data-sources table in §10, and the roadmap in §13.7. Earlier: 2026-07-11 — a new §9.9 covering the map-tools UI + navigation suite shipped to main, live across every native/Grid/industry-edition module: a shared "widget kit" holographic HUD design language (features/widgets/widget-kit.css, wk-* classes, theme-token-driven via color-mix() so a platform theme recolours every map-tool panel) restyling Measure/Time of Day and styling the two new tools; a new Draw & Annotate capability feature (draw, features/draw/DrawOverlay.tsx, migration 0043) — Select/Point/Line/Polygon/Rectangle with per-feature stroke/fill/width + optional label, a feature list, Clear all, Copy/Download GeoJSON, localStorage persistence, default-on in Smart City/Maritime/Emergency Services; and a new always-on Navigate compass rail (features/navigate/NavWidget.tsx, replaces MapLibre's default zoom/compass/geolocate/fullscreen controls in every native/Grid/industry module) — a collapsible, drag + resizable HUD with a live compass rose bound to bearing/pitch/zoom (click-to-reset-north), a pitch slider, geolocate, fullscreen, a globe/mercator toggle, a multi-CRS coordinate readout (lib/coords.ts, new proj4+mgrs deps: WGS84 dec/DMS, Web Mercator, UTM, MGRS, 21-zone CONUS State Plane — the map itself still only renders Mercator/Globe, MapLibre's limit, so CRS drives the readout not the projection) for both map-centre and cursor, and a toggleable UTM/MGRS grid overlay (lib/grid-overlay.ts, Off·UTM·MGRS) with zone/GZD boundaries, 100 km squares, zoom-adaptive spacing, vertical easting labels, and colour/line-style/thickness controls; lib/nav-controls.ts now only adds the metric+imperial scale bars. Every floating map surface is now uniformly drag + resizable — DockablePanel (already was), the new Navigate rail, CatalogLegend (now closable), and every showFloatingPopup window including the ArcGIS identify popup (the last native maplibregl.Popup converted). Cross-referenced from the feature-registry table in §7.4 (now sixteen features) and the roadmap in §13.7. ⚠ Ops gotcha (already fixed, noted for the next one): a new module FeatureDef needs a tenant_features backfill migration (mig 0042 for the map-tools set, 0043 for draw) + an API restart before it surfaces for tenants seeded before the feature existed — load_entitlements reads the DB enable-state rows, not the compile-time catalog defaults. Earlier: 2026-07-10 — Time of Day (features/time-of-day/TimeOfDayOverlay.tsx, lib/time-of-day.ts), a dependency-free NOAA/SunCalc-style solar-position engine that drives setLight 3D building shading, hillshade illumination direction/colour, and setSky day/twilight/night gradients from a solar-time + date slider (sunrise/golden/noon/sunset presets, Play + speed, a hillshade-contrast Shadows approximation — real deck.gl cast shadows are a noted TODO); and Measure (features/measure/MeasureOverlay.tsx, extended lib/measure.ts), the measure tool upgraded to a 3D-aware Distance/Area/Height panel with map.queryTerrainElevation-derived slope length, a per-segment 3D/horizontal/Δh/bearing table, and an m/ft toggle, degrading gracefully to 2D with no terrain — both are PanelDock rail items, default-on in Smart City/Maritime/Emergency Services via crates/cartos-core/src/catalog.rs (no new migration needed), and cross-referenced from the feature-registry table in §7.4 and the roadmap in §13.7. Earlier: a dedicated §8.3 write-up of the three Cartos industry editions — Cartos Tower (Airport), Cartos Milepost (Transportation/DOT), and Cartos Blueprint (Infrastructure PM/AEC), built 2026-07-07 and now live on their own subdomains (tower./milepost./blueprint.cartosatlas.com, verified against deploy/Caddyfile.prod) — closing the gap flagged in the 2026-07-09 refresh (this guide covered the catalog/dashboard work over these editions but never described the editions themselves). Covers the 29-module lineup read straight from cartos-web/src/modules/industry/modules.ts (Tower 10 / Milepost 10 incl. an Executive Overview portfolio surface / Blueprint 9 incl. a Portfolio View), the shared config-driven IndustryModule surface + IndustryDashboard, the edition.ts hostname-detection preset system extended to tower/milepost/blueprint, the engine+editions+instances table in §1 extended to all five live editions, and the per-project/portfolio-wide access-grant RBAC that backs Milepost/Blueprint's scope model (migrations 0036/0037, crates/cartos-data/src/industry.rs + crates/cartos-api/src/industry.rs, features/industry-access/ProjectAccessPanel.tsx, and its modules/admin/ProjectAccessConfig.tsx User-Admin console tab). §2 now also lists all five live app subdomains, not just the marketing site. Earlier: the operational-data / admin-layer / ask-the-map epic — ALL 4 phases shipped to main and live on cartosatlas.com: Phase 1 a DB-backed Datasource + Layer Catalog (migrations 0038/0040 catalog_features) scoped by tenant/edition/module/group/role/user-type, with a tech_admin CatalogConfig console and a portable cat--prefixed reconciler + CatalogLayersOverlay mounted in every MapLibre-native module; Phase 2 real OpenStreetMap data (via tools/osm_to_geojson.py + Overpass, ingested with the new cartos-cli load-geojson region loader) live in all 7 MapLibre-native module families — Cartos Grid/Charlotte (293 substations, 1,278 transmission spans), Smart City/Abu Dhabi (95 hospitals, 201 schools), Maritime/Gulf (94 marine facilities), Emergency Services/Abu Dhabi (56 stations), Cartos Tower/DFW (265 airfield movement segments), Cartos Milepost/Indianapolis (1,537 motorway segments), Cartos Blueprint/Las Vegas (363 construction sites) — plus a live bottom stats bar and GET /api/catalog/kpi; Phase 3 an attribute-driven symbology engine (lib/catalog-style.ts — categorical/graduated color + size, dashed lines, polygon fill/outline) with an in-panel style editor + on-map legend, and real 3D (polygon fill-extrusions + deck.gl 3D point columns via lib/catalog-3d.ts); Phase 4 two cross-module agent tools, catalog_layers + query_catalog_layer ("ask the map" — attribute filter, proximity, group-and-count, coordinate sample, all scope-enforced) over any catalog layer the caller can see. Alongside: per-edition full-screen dashboards — every Grid + industry-edition department module now has its own /<moduleId>/dashboard route (shell/DashboardPage) that returns to its own map, not a hardcoded Smart City; a new reusable CatalogDashboard (ECharts charts, auto-classified attribute breakdowns, computed alerts, reorderable cards, theme switching) is the standard dashboard body for the industry editions (Tower/Milepost/Blueprint), falling back to representative KPI tiles where a module has no catalog data yet; Grid keeps its own chart-rich KPI dashboard bound to live /api/grid data; and a new CatalogKpiStrip pre-stocks the native module dashboards (Smart City, Emergency, Maritime, Grid) with real catalog feature counts. Two shell/auth fixes: the native Government KPI strip no longer leaks onto Grid/industry-edition modules (nativeModuleFromPath — it previously defaulted to Smart City's Abu Dhabi data and a "Dashboard" link that bounced back to /smart-city); the Grid/industry catalog stats bar (MapStatsBar) moved off the map into the shell's bottom footer slot alongside the native KPI strip; and the Keycloak realm's login-page displayName was fixed from the retired "Cartos Atlas" to "Cartos". Earlier: hard rebrand: this guide carries no affiliation with the former parent org — every prior parent-org name and the standalone former-partner-integration name are gone from this doc and its rendered artifacts; the retired external integration module and its dedicated embedding-doc reference dropped from the module catalog table and nav table; Government edition now referred to only as Cartos Atlas. Earlier: deployment-readiness hardening Phases A–D: JWKS live refresh loop + CARTOS_REQUIRE_TENANT_CLAIM, migration 0033 RLS on 5 previously-uncovered tables + opt-in cartos_app non-superuser DB role, CI gate ci.yml + cargo test 4/4, DB pool 8→50 + entitlement cache + shared HTTP clients + router timeout/concurrency limits + 15 s KPI cache, FlatGeobuf debounce + code-splitting + tab-visibility polling, GET /readyz health probe + compose healthcheck, iframe-bridge origin pinning, JSON logs + request-ID, migration 0034 dedup guard. Earlier: PR #123 — real connector adapter seam: crates/cartos-api/src/connectors/ — RealConnector trait, is_real() config-driven dispatch, real_sync() registry; connectors/esri_un.rs reference implementation verified live against a public ArcGIS Feature Server; cartos-data additions: get_config + upsert_real_assets; grid::sync now routes to real adapter when config.service_url is set, otherwise mock feed unchanged. Earlier: PR #120 — Admin → Integrations tab: point-and-click CRUD for Grid SoR connector registry (tech_admin-gated), migration 0032 unique-kind index, IntegrationsConfig.tsx, new POST/PATCH/DELETE /api/grid/integrations{/:kind} routes. Earlier: PRs #113–#117 — cloud-native data layer spikes: serverless PMTiles vector tiles from MinIO, in-browser DuckDB-WASM analytics over GeoParquet, FlatGeobuf bbox-streamed vector, COG range-read raster, Turf.js client-side geoprocessing, and broad layer export — all on the existing MinIO object store, no new services; spiked / proof-of-concept, production hardening TBD. Earlier: PRs #111 fix mock SoR labels; PRs #102–#109 Cartos Grid all seven SoR connectors end-to-end; PR #103 AIS analytics pushed to Cesium MDA globe). This is the single orientation doc for everything built so far — platform, modules, features, how to run it, the marketing site, and the GTM artifacts.

Contents

1. What Cartos is
2. Live URLs & quick links
3. Architecture at a glance
4. Repository layout
5. The platform (Phase 1 substrate)
   • §7.5 Cartos Field — Phase 3A
6. The modules
   • §8.1 Cartos Grid — Electric Utility edition
   • §8.2 Historic AIS analytics — Maritime module
   • §8.3 Cartos Tower, Milepost & Blueprint — Airport, DOT & AEC editions
   • §8.4 Cartos Africa — the One Africa edition
   • §8.5 Cartos Guardian — Critical-Infrastructure Protection
   • §8.6 Cartos Sentry — Reactive Crisis Monitoring
   • §8.7 Cartos Harvest — Agriculture Intelligence
7. Cross-cutting features every module inherits
   • §9.1 Agent intelligence surface — Cartos overhaul
   • §9.2 Map Export & Mapbook
   • §9.3 3D Data — Point Clouds & Gaussian Splats
   • §9.4 Platform theme system
   • §9.5 Cloud-native data layer — object-storage format spikes
   • §9.6 Operational Data & Layer Catalog — real data, symbology, ask-the-map
   • §9.7 Dashboards — per-edition & catalog-driven
   • §9.8 Map tools — Time of Day & Measure
   • §9.9 Map tools UI — Widget kit, Draw & Annotate, Navigate rail
   • §9.10 Mapillary — Street Imagery overlay
   • §9.11 Cost gate — nothing priced runs without explicit acceptance
   • §9.12 Risk symbology & rich feature popups
8. Data sources, integrations & keys
9. HTTP API reference
10. The marketing website & GTM artifacts
11. Phase 2 — Analyst Intelligence Layer (Wave 2A built)
    • §13.1 M03 Derived-dataset graph (the moat)
    • §13.2 M02 Comprehensive reporting
    • §13.3 Async model-job tier & model sidecar
    • §13.4 M01 Temporal change detection — real model
    • §13.5 Phase 2 web UI — Analysis overlay
    • §13.6 MCP server — Cartos as an AI tool host
    • §13.7 Roadmap — remaining Phase 2 waves
12. Phase 3 — Cartos Field
13. Reference docs

Jump to: §7.4 Tenant Capability System · §7.5 Cartos Field — Phase 3A · §8.1 Cartos Grid — Electric Utility · §8.2 Historic AIS analytics · §8.3 Cartos Tower/Milepost/Blueprint · §8.4 Cartos Africa — One Africa edition · §8.5 Cartos Guardian · §8.6 Cartos Sentry · §8.7 Cartos Harvest · §9.1 Cartos agent overhaul · §9.2 Map Export & Mapbook · §9.3 3D Data — Point Clouds & Gaussian Splats · §9.4 Platform theme system · §9.5 Cloud-native data layer spikes · §9.6 Layer Catalog — ask the map · §9.7 Dashboards · §9.8 Time of Day & Measure · §9.9 Draw & Navigate rail · §9.10 Mapillary street imagery · §13 Phase 2 Analyst Intelligence Layer · §13.4 Real segmentation model · §13.6 MCP server

1. What Cartos is

Cartos is a sovereign geospatial vertical-AI platform: ingest, serve, and visualize geospatial data inside your own territory, with an AI analyst wired in from the first click. Every "vertical" (city, port, emergency services…) is a slice over one shared data fabric, one agent, and one shell — not a separate product.

Engine + Editions + Instances model

Cartos is the horizontal ENGINE — the data fabric, agent, capability system, shell, and all cross-cutting features. Industries are licensed EDITIONS of that engine. An edition can be licensed as multiple INSTANCES by different organisations.

Ownership & licensing (reworked 2026-07-28 — see EarthWatch3D-PRD/PRD.md §20 for the full language). Cartos — the engine and every one of its editions — is the sole and exclusive property of Steven P. Santovasi (the "Owner"). The Owner grants Solution Strategy Partners ("SSP") a single unrestricted, perpetual, irrevocable, worldwide, royalty-free, sublicensable master license to the whole Cartos platform and every edition — SSP may use, host, deploy, modify, commercialize, distribute, and sublicense Cartos for any purpose, at no cost, but the license does not transfer ownership. Every downstream edition instance below is delivered as a non-exclusive sublicense under SSP's master license, not a direct grant from the Owner — e.g. Cartos Atlas (the owner-held, first Government-edition instance) and Cartos Grid (the RAiN Partners instance of the Electric-Utility edition) are sublicensed instances, each the first, not the sole instance of its edition, provided "as-is" at the state existing at handoff.

A new industry segment gets a new edition; a new customer within that segment gets a new sublicensed instance of the existing edition. All nine editions above are now built and merged to main; eight are also live, each on its own subdomain of cartosatlas.com (edition detected from hostname — see §8.3 for Tower/Milepost/Blueprint, §8.1 for Grid, §8.4 for Africa, §8.5 for Guardian, §8.6 for Sentry); the ninth, Cartos Harvest, is LIVE at harvest.cartosatlas.com (deployed 2026-07-29, Caddy vhost, or Keycloak redirect origin yet) — see §8.7. Guardian and Sentry are a deliberate pair — proactive protection feeding a reactive monitor — not two independent verticals; see the Guardian → Sentry handshake in §8.6.

The three phases

This guide covers Phase I (§7), Phase II Wave 2A (§13), and Phase III (§7.5 + §14). Cartos Grid (the first vertical edition) is documented in §8.1; Cartos Tower, Milepost & Blueprint (three live vertical editions) in §8.3; Cartos Africa (the sixth live edition) in §8.4; Cartos Guardian (the seventh live edition) in §8.5; Cartos Sentry (the eighth live edition) in §8.6; Cartos Harvest (the ninth live edition) in §8.7.

Two different things are called "Phase 2": the RLS / group-access work (shipped — §7) and the Analyst Intelligence Layer (Wave 2A now built — §13). When in doubt, ask which is meant. "Phase 3A/3B" in this guide means the complete Cartos Field stack — sync backend, web config console, analyst module, media backend, module assignment, portable overlay, and the Flutter mobile app (CI-compiled, Android APK live via Firebase App Distribution; iOS pending Apple Developer enrollment).

2. Live URLs & quick links

The marketing site is hosted on Cloudflare Pages (push main = publish). The app also runs on a small stakeholder-demo VM — one Caddy origin, one edition per subdomain, hostname-detected (deploy/Caddyfile.prod) — with demo/seed data only, not sovereign infrastructure (per deploy/DEPLOY.md); it is also locally and §12 for the site.

3. Architecture at a glance

            ┌──────────────────────────────────────────────────┐

   Browser  │  cartos-web — React + Vite shell                  │

            │  MapLibre (2D) · Cesium iframe (3D) · Dockable    │

            │  panels · AI agent chat · GeoWizard · overlays    │

            │  AnalysisOverlay · CompareOverlay (swipe)         │

            └───────────────┬──────────────────────────────────┘

                            │  HTTPS (Bearer JWT)

            ┌───────────────▼──────────────────────────────────┐

   Rust     │  cartos-api (axum)  — JWT validated vs Keycloak    │

   workspace│  JWKS. Routes per module + agent + admin + layers  │

            │  ├─ cartos-agent  LLM tool registry (Anthropic)    │

            │  ├─ cartos-data   Postgres queries + RLS session   │

            │  ├─ cartos-core   TenantContext (tenant/tier/roles/groups)

            │  └─ model-job worker (SKIP-LOCKED → sidecar loop) │

            └───────┬───────────────────────────────────────────┘

                    │           │ POST /infer (tier routing)

        ┌───────────┴──────┐   ┌───────▼────────────┐  ┌─────────────────┐

        │  Postgres+PostGIS│   │  model-sidecar      │  │  GPU sidecar    │

        │  (RLS tenant+team│   │  FastAPI :8300       │  │  (Dockerfile.gpu│

        │  derived dataset │   │  SegFormer-b0/ADE   │  │  CUDA 12.4 +    │

        │  graph + job Q)  │   │  real imagery fetch  │  │  SegFormer-b5)  │

        └──────────────────┘   │  change.detect (real)│  │  MODEL_GPU_SIDECAR_URL

                               └────────────────────-─┘  └─────────────────┘

        ┌──────────────────┐   ┌──────────────────────┐  ┌─────────────────┐

        │  Keycloak        │   │  MinIO + Caddy        │  │  mcp-server/    │

        │  (SSO/JWT)       │   │  object store + proxy │  │  stdio → AI host│

        └──────────────────┘   └──────────────────────┘  └─────────────────┘

• Rust workspace carries the data fabric, agent, API, and the Phase 2 model-job worker; a React shell renders MapLibre 2D and Cesium 3D (the latter via an iframe bridge to the sibling ../cesium_project_SPS app).
• Phase 2 model sidecar (model-sidecar/, FastAPI :8300) is stateless — it never touches the DB. The Rust worker owns the Postgres SKIP-LOCKED queue, claims jobs, calls POST /infer, and writes outputs as lineage-tracked derived datasets. The sidecar relocates CPU → GPU cluster with zero code change. A GPU sidecar variant (Dockerfile.gpu, CUDA 12.4 + SegFormer-b5) is the deployable artifact for a Full GPU tier; the API routes to it when MODEL_GPU_SIDECAR_URL is set.
• MCP server (mcp-server/, Node + @modelcontextprotocol/sdk, stdio transport) exposes a curated read-only tool surface over cartos-api so any MCP-capable AI host (Claude Desktop/Code, Copilot, Gemini via a bridge) can "ask Cartos" directly.
• Everything ships in containers you run in-territory (deploy/).
• Tenant- and team-isolation is enforced at the database with row-level security across all tenant tables, not just in the app layer.

4. Repository layout

7. The platform (Phase 1 substrate)

Every vertical inherits these. They are the moat.

Sovereign data fabric + team isolation (group access)

• Keycloak groups claim → TenantContext.groups → query filter owning_team IS NULL OR owning_team = ANY($groups) → Postgres RLS policy tenant_team_isolation as a second layer.
• New customer tables almost always need owning_team TEXT + a (tenant_id, owning_team) index.
• Admin writes set data scope via PATCH /api/admin/scope (also exposed as the set_owning_team agent tool); both set a cartos.bypass session var inside the transaction.
• Migration 0033 closes the RLS gap on five tables that previously lacked ENABLE + FORCE ROW LEVEL SECURITY + the tenant_team_isolation policy: field_apps, field_features, derived_dataset, analysis_session, model_job. session.rs save/get/list paths now go through set_tenant_session.
• Migration 0087 does the same for the three Cartos Harvest tables added by migrations 0083–0085 — crop_calendars, field_parcels and farmer_registry. Each described itself as scoped "per the platform convention" but carried no RLS policy, so the only boundary was the explicit WHERE filter in cartos-data; farmer_registry holds PII (name / national_id / phone). 0087_harvest_rls.sql applies the same ENABLE + FORCE + tenant_team_isolation treatment, and all nine set_tenant_session call sites in cartos-data/src/harvest.rs now forward the caller's real groups instead of &[], so cartos.groups is actually populated (insert_field_candidates and create_farmer gained a groups parameter for exactly this — their RETURNING clauses are evaluated against the read-side policy). Shipped + deployed 2026-07-29; verified on prod that all three report relrowsecurity and relforcerowsecurity.

  ⚠ The two halves must ship together. With RLS on and an empty groups slice, INSERT … RETURNING raises "new row violates row-level security policy", and every already-stored row with a non-NULL owning_team becomes invisible. Do not cherry-pick the migration without the cartos-data change, or vice versa.

• Opt-in non-superuser DB role (cartos_app) — postgres/03-app-role.sh creates the role; set CARTOS_APP_DB_PASSWORD and the CARTOS_APP_DB_USER compose var so the API runs as cartos_app (not postgres) in production, making FORCE ROW LEVEL SECURITY actually bite. See DEPLOY.md §3a. In dev the postgres role bypasses RLS by design; the WHERE filters carry the boundary.
• Canonical contract: docs/group-access-design.md — read it before adding queries, write paths, RLS policies, or detail-panel UI.

Authentication & access control

• Keycloak SSO, roles, and team-scoped data. JWT is RS256-validated against Keycloak's JWKS. The JWKS is now live-refreshed: on an unknown key-id the API refetches immediately (rate-limited to once per 30 s) and a 10-minute background loop keeps the cache warm — eliminating the fleet-wide auth outage that a Keycloak key rotation previously caused.
• CARTOS_REQUIRE_TENANT_CLAIM=1 — when set, the auth layer rejects (401) any JWT that lacks the cartos_tenant_id custom claim. Fails closed. Flip only after adding the Keycloak protocol-mapper that emits the claim; leaving it unset preserves the existing behaviour (claim optional).
• Realm roles in deploy/keycloak/cartos-realm.json:
  • admin — superuser, implies all three sub-admin tiers.
  • provider_admin — which modules a client deployment has.
  • tech_admin — which features per module.
  • user_admin — users' teams + per-user module access.
  • user, viewer — standard end-user tiers.
• The three sub-admin roles are additive to admin — is_provider_admin() returns true for both admin and provider_admin, and so on. A dedicated tier role scopes a delegate to just their surface.
• Native Admin module manages users, group membership, and capabilities in-app via the Keycloak Admin REST API + the capabilities API. 503s unless CARTOS_KEYCLOAK_ADMIN_CLIENT_SECRET is set.
• Realm displayName (deploy/keycloak/cartos-realm.json) is now "Cartos" — Keycloak's "Sign in to …" login header previously still read the retired "Cartos Atlas" name; fixed and applied live to the production realm via kcadm.
• For the planned model of federating Keycloak to a client's own IdP/AD per sovereign deployment see docs/identity-federation-design.md (design, not built).

The AI agent (agent-native from click one)

• Conversational control: ask a question, focus the map, run a workflow — the agent orchestrates the platform's own tools. POST /api/agent/chat (503 when ANTHROPIC_API_KEY is unset).
• Opus 5 extended-thinking round-trip fix (2026-07-28, ships with the Cartos Harvest merge, platform-wide): the Anthropic client's ContentBlock enum (crates/cartos-agent/src/llm.rs) now has Thinking (thinking + signature) and RedactedThinking (data) variants that serialize back unchanged — Anthropic requires a thinking block to be echoed verbatim in the assistant turn that carries a tool_use, or the follow-up request is rejected. Previously the parser didn't recognize these blocks, causing intermittent 502s on reasoning-heavy turns since the app agent was upgraded to Claude Opus 5; fixed for every module's tool calls, not just Harvest's.
• Module-namespaced tool registry (crates/cartos-agent/src/builtin/):
  • Core: who_am_i, current_time, viewport_focus
  • Smart City: list_incidents, find_assets, nearest_sensors, list_jurisdictions
  • Maritime: list_vessels, find_vessels, list_ports, list_port_incidents
  • Emergency Services: list_emergency_units, list_emergency_incidents, nearest_available_unit, incidents_in_window, traffic_conditions, list_cameras
  • Overlays: add_satellite_layer, list_satellite_layers
  • Admin: set_owning_team
  • Field (cross-module): list_field_apps (optional module arg to scope to apps assigned to that module), summarize_field_captures
  • Cartos Grid (cross-module — work on any Grid department surface): grid_kpis (aggregate KPI summary: assets total/at-risk by kind, active outages + customers out, open work orders by kind, vegetation risk segments, parcels + encroachment count, CIP projects total/active/budget $M), grid_active_outages (list active/restoring outages sorted by customers affected; optional limit), grid_open_work_orders (list open work orders by kind, priority, crew; optional kind filter + limit)
  • Layer Catalog — "ask the map" (cross-module, over every accessible module): catalog_layers (discover every map layer the caller can see, scope-filtered by tenant/group/role/user-type, with module/label/render_type/feature_count; optional module filter) and query_catalog_layer (resolve a layer by layer_key, re-authorize by scope, then attribute-equality filter, proximity filter (near_lon/near_lat/radius_m), group-and-count, a coordinate sample, or a One Africa countries (ISO3) scope filter — always returns matched_count). See §9.6.
  • Street imagery (cross-module, external call): mapillary_street_imagery — searches Mapillary's public Graph API for crowd-sourced street-level photos inside a bbox or near a point+radius, with pano_only/since_year/limit filters; returns each image's lon/lat, capture month, compass heading, is_pano, a thumbnail URL, and a Mapillary deep link. configured: false when the server has no MAPILLARY_TOKEN. See §9.10.
  • One Africa (cross-module, module() returns None, built on branch map-africa): africa_scope — resolves country names, ISO3 codes, or an AU region (or whole_continent) into the canonical scope_iso3 list plus each country's name/region/population and the combined population, reading the loaded adm0_countries registry; feed scope_iso3 straight into query_catalog_layer's new countries argument so "ask the map" answers stay in scope. Not gated to a single Africa module by design — a country-scope tool has to reach all nine. See §8.4.
  • Cartos Guardian (cross-module, edition-wide): guardian_strike_risk — ranks the UAE critical-infrastructure inventory by the per-site strike-risk model, filtered by category/min_tier/min_score/within_hormuz_km/shipping_only/limit; returns matched_count + tier_distribution + ranked targets. See §8.5.
  • Cartos Harvest (cross-module, edition-wide, crates/cartos-agent/src/builtin/harvest.rs, merged to main): five tools. crop_calendar — planting/peak/harvest month windows and the current phenology stage (planting/vegetative/harvest/off-season) for a country's crops, optionally filtered by country (ISO3) / crop; harvest_country_profile — a country's crop-calendar summary for right now (which crops are planting, growing, or being harvested), keyed by iso3 (both read crop_calendars, migration 0083, FAO GIEWS-seeded for KEN/NGA); parcel_fabric_summary — how many field parcels are delineated (candidate/approved/rejected, area) plus farmer-registry linkage coverage; harvest_products — the persisted derived-product catalog (crop-type/health/yield/water/risk runs saved via "Save to products"), optional product filter, PNG bytes stripped; farmer_lookup — search the farmer registry by name/national-id substring, returns cooperative/region/crops/linked-parcel-count (PII, in-scope callers only). See §8.7.
• Tools requiring the DB are disabled gracefully if Postgres is unreachable (server still starts; /healthz reports honestly).
• Capability gating of the tool surface: the /api/agent/chat handler loads the calling user's effective enabled modules (tenant enables minus per-user denials) and passes them into respond_with_history as enabled_modules. The registry's to_anthropic_tools_filtered drops any tool whose module() maps to a module not in that set; cross-module tools (who_am_i, current_time, viewport_focus, satellite tools) are always exposed. When the DB is unreachable the gate fails open.
• Agent + data-source panel now scope to the real module (fixed on branch map-africa, applies to every edition): the shell used to derive the agent's module focus from moduleFromPath(), which only knows the native trio and fell through to smart_city for every Grid/industry/Africa route — so on a non-native map the agent claimed to be "in the Smart City module" and leaked Smart City's tools while the External Data Sources drawer loaded Smart City's source set. AppShell.tsx now derives agentFocusFromPath() (native routes keep their focus; Grid/industry/Africa send their own module id so the tool filter drops native tools and keeps the cross-module ones) and moduleIdFromPath() (the catalog-canonical kebab id for the drawer); verified on africa-health — agent panel reads "Health & Immunization", the drawer reads "africa-health · 49 live · 33 hidden", and Smart City's tools are gone.
• Cartos agent overhaul (see §9.1 Agent intelligence surface for full detail): rich Markdown + inline SVG chart rendering, voice input (Web Speech API), resizable/fullscreen panel, and a conversation export menu (Print/PDF · Word/DOCX · HTML).

7.4 Tenant Capability System

Status: built and wired; merged to main.

What it is: per-client sovereign configuration — a declarative, in-repo catalog of what modules and features can exist on the platform, plus per-tenant DB enable-state and per-user access overrides, with a three-tier admin surface to manage them.

The catalog (crates/cartos-core/src/catalog.rs)

Two static constructs compiled into the binary:

• FEATURES — global feature registry. Seventeen reusable capabilities:

  id	Label	What it is
  external-overlays	External overlays	ArcGIS REST catalog + custom URL + identify popups
  satellite	Satellite imagery	NASA GIBS WMTS layer catalog
  stac	STAC catalog	STAC item discovery + on-map preview
  mobility	Global Mobility	Live ADS-B aircraft, AIS vessels, TomTom traffic
  overture	Overture Maps	Overture vector overlay: places, transportation, buildings, divisions
  buildings-3d	3D buildings	Overture extrusion + wireframe + Esri I3S photoreal mesh
  live-weather	Live Weather	Animated weather on the Cesium globe: GPU wind-particle streamlines, wind-speed colour wash, direction arrows (live NOAA GFS; extensible). Surfaced in Cesium-backed modules via the iframe bridge.
  analysis	Analyst Intelligence	Phase 2 GeoAI: run segmentation / change detection over the current view as async jobs, render the lineage-tracked derived dataset, export an auditable report (HTML/DOCX). Panel appears in the left dock, gated per module.
  compare	Swipe Compare	Before/after comparison of two raster layers (A vs B), camera-synced to the host module's map. Two view modes: Swipe (draggable divider wipes B over A) and Side-by-side (edge-to-edge panes, divider resizes the split). Both panes are fully interactive and bidirectionally camera-synced — pan or zoom from either side and both move together (a guard flag prevents the feedback loop). Each side (A/B) picks from a "Current map" option (clones the live host module's full map style — basemap plus active data/overlay layers — so you can compare what is actually on screen against any other source), a full grouped layer catalog — Basemap (OpenStreetMap, Carto Light/Dark), Esri (Imagery, Streets, Terrain, Topographic, Ocean, NatGeo), Satellite/GIBS (MODIS Terra/Aqua + VIIRS true color) — or a Custom URL (XYZ / WMS / WMTS / Esri REST tile template). Companion to two-epoch change detection. See §9.
  map-export	Map Export & Mapbook	Consolidated left-dock sidebar panel. Create Map mode: four single-page layout templates (Classic Visual, Operational Briefing, Field Map, Compact A4 Brief); one-click PNG capture; OGC GeoPDF (server-side GDAL, georeferenced EPSG:3857). Mapbook mode: multi-page atlas (cover + labeled tile-grid index, one sheet per tile, optional appendix). Full plotter paper sizes: Letter, A4/A3/A2/A1/A0, Tabloid, ARCH A–E and E1, wide formats up to 42×60 and 48×60, plus a user-defined Custom width×height. Landscape or portrait. Data (CSV) section for per-module data exports. See §9.2.
  point-cloud	3D Data — Point Clouds & Gaussian Splats	GPU-free client-side 3D data viewer in MapLibre native modules. Point clouds / 3D Tiles: deck.gl MapboxOverlay + Tile3DLayer / PointCloudLayer; local LAS/LAZ (georeferenced or center-of-map), density slider, 90° pitch. Gaussian splats: three.js overlay canvas + @mkkellogg/gaussian-splats-3d DropInViewer; load from URL or local file (.splat / .ksplat / .ply / .spz); SuperSplat SOGS importer (.ssog / .sog / .zip — LOD-aware, decoded by fflate). Anchor, scale, heading, and flip controls. Pitch the map to 90° for a ground-level view. See §9.3.
  dashboard	Configurable KPI Dashboard	An in-module KPI dashboard, admin-gated and on/off per module. Add/remove KPI cards from a metric catalogue, choose the chart type (stat / bar / line / pie / gauge via Apache ECharts), and drag to arrange layout — all editable live from inside the dashboard. Layout persists per user + module in localStorage. Metrics are sample data today — structured to bind to the module's live map data (asset/work-order/outage/vegetation layers) as those data layers ship. Currently the default feature in every Cartos Grid department module.
  catalog	Layer Catalog	Admin-managed datasources + map layers persisted per tenant/edition/module and scoped by group/role/user-type: add, hide, or remove hosted GIS layers (internal PostGIS, ArcGIS REST, WMS/WMTS/XYZ, GeoJSON, PMTiles, COG, FlatGeobuf), with credentials for private sources (write-only — never returned to clients). Renders in the module's map via a shared portable overlay + reconciler, with attribute-driven symbology (incl. 3D) and two cross-module "ask the map" agent tools. See §9.6.
  time-of-day	Time of Day	Sun-position lighting: scrub apparent solar time (or animate it) for the map center + date to drive 3D building shading, hillshade illumination, and a day/twilight/night sky. Dependency-free solar engine; sunrise/golden/noon/sunset presets, a sun-elevation timeline, and a directional-shadow-approximation toggle. See §9.8.
  measure	Measure	3D-aware measurement panel: distance (polyline), area (polygon), and height (two points), in metres or feet. Per-vertex terrain elevation gives 3D slope length, per-segment horizontal/Δh/bearing, and a live results table; degrades to 2D when no terrain is loaded. See §9.8.
  draw	Draw & Annotate	Sketch + annotate on the map: points, lines, polygons, and rectangles with per-feature stroke/fill/width styling and optional text labels. Select-and-delete editing, a live feature list, Clear all, and Copy/Download of the drawing as GeoJSON. Persists per module + user in localStorage. See §9.9.
  mapillary	Mapillary Street Imagery	Crowd-sourced street-level imagery from Mapillary as a map overlay: a vector coverage layer (drive-path sequences + image points) with a captured-since filter and a 360°-panoramas-only toggle; click an image point to view the dated street-level photo with its compass heading in a floating popup. External community data (© Mapillary contributors, CC-BY-SA); requires a Mapillary access token. See §9.10.

  Features are not owned by any module — any feature can be attached to any module, either as a default or as an advanced cross-add.

• CATALOG — installable modules. Platform modules, Cartos Grid's nine department modules, and (as of 2026-07-07, see §8.3 for the full write-up) 29 more department modules across three industry editions — Cartos Tower (Airport, 10), Cartos Milepost (Transportation/DOT, 10), Cartos Blueprint (AEC, 9) — each with a min_tier and a default_features list (ids referencing FEATURES). Canonical kebab-case ids match the route slugs and the DB module_id column:

  Platform modules (all editions):

  id	Label	Vertical	Min tier	Default features
  smart-city	Smart City	urban	Starter	external-overlays, satellite, stac, mobility, overture, buildings-3d, analysis, compare, map-export, point-cloud, time-of-day, measure, draw, mapillary
  situational-awareness	Situational Awareness	defense	Enterprise	(none) — EarthWatch3D Cesium-iframe; external-layer and satellite pushes go via the bridge, not capability features.
  emergency-services	Emergency Services	public-safety	Growth	satellite, mobility, analysis, compare, map-export, point-cloud, time-of-day, measure, draw, mapillary
  maritime	Maritime	maritime	Growth	satellite, mobility, analysis, compare, map-export, point-cloud, time-of-day, measure, draw, mapillary
  maritime-domain-awareness	Maritime Domain Awareness	maritime	Enterprise	satellite, live-weather
  energy	Energy	energy	Enterprise	(none — not yet built)
  agriculture	Agriculture	agriculture	Enterprise	(legacy placeholder — superseded by the seven harv-* Cartos Harvest modules below; no route, unreachable, kept only because catalog.rs hasn't dropped the ModuleDef)
  field	Cartos Field	field-ops	Growth	satellite

  Cartos Grid — Electric Utility edition (nine department modules):

  id	Label	Department	Min tier	Default features
  grid-command	Grid Command	Executive cockpit	Enterprise	external-overlays, satellite, analysis, compare, map-export, dashboard
  grid-operations	Network & Asset Operations	Grid operations	Enterprise	external-overlays, satellite, stac, buildings-3d, analysis, compare, map-export, point-cloud, dashboard
  grid-capital	CIP & Major Projects	Capital improvement	Enterprise	external-overlays, satellite, analysis, compare, map-export, point-cloud, dashboard
  grid-storm	Storm Response	Emergency / storm ops	Enterprise	external-overlays, satellite, mobility, analysis, compare, map-export, dashboard
  grid-fleet	Fleet & Field	Fleet / field ops	Enterprise	external-overlays, satellite, mobility, map-export, point-cloud, dashboard
  grid-vegetation	Vegetation Management	Vegetation / forestry	Enterprise	external-overlays, satellite, stac, analysis, compare, map-export, point-cloud, dashboard
  grid-realestate	Real Estate Management	Real estate / ROW	Enterprise	external-overlays, satellite, overture, analysis, compare, map-export, dashboard
  grid-environmental	Environmental Management	Environmental / permitting	Enterprise	external-overlays, satellite, stac, analysis, compare, map-export, dashboard
  grid-stakeholder	Stakeholder Management	Stakeholder / public affairs	Enterprise	external-overlays, satellite, map-export, dashboard

  Cartos Tower — Airport edition (ten department modules): every module carries the same five default features (analysis, compare, map-export, dashboard, mapillary) — the lean IndustryModule surface, see §8.3.

  id	Label	Department
  air-lighting	Tarmac Lighting	Airfield · lighting
  air-surface	Surface Condition	Airfield · pavement
  air-striping	Lane Striping	Airfield · markings
  air-signage	Signage	Airfield · signage
  air-lease	Property Lease	Real estate
  air-projects	Major Projects	Capital projects
  air-emergency	Emergency Services	ARFF / SMS
  air-vehicle	Vehicle Traffic	Landside / ramp
  air-airtraffic	Air Traffic	Airside ops
  air-weather	Weather	Meteorology

  Cartos Milepost — Transportation/DOT edition (ten department modules): same five default features; dot-executive is the portfolio surface, the rest are project-scoped (see the RBAC model in §8.3).

  id	Label	Department	Scope
  dot-executive	Executive Overview	Executive · portfolio	portfolio
  dot-pavement	Pavement Management	Project · pavement	project
  dot-facility	Facility Management	Project · facilities	project
  dot-striping	Lane Striping	Project · markings	project
  dot-traffic	Live Traffic	Project · traffic	project
  dot-roadwork	Current Roadwork & Obstructions	Project · work zones	project
  dot-projects	Major Projects	Project · major projects	project
  dot-crew	Crew Status	Project · field crews	project
  dot-snow	Snow Removal & Treatment	Project · winter ops	project
  dot-emergency	Emergency Response	Project · emergency	project

  Cartos Blueprint — Infrastructure PM/AEC edition (nine department modules): same five default features; aec-portfolio is the portfolio surface, the rest are project-scoped.

  id	Label	Department	Scope
  aec-portfolio	Portfolio View	Executive · portfolio	portfolio
  aec-design	Design Status	Project · design	project
  aec-site	Site Selection	Project · site selection	project
  aec-constructability	Constructability Review	Project · constructability	project
  aec-environmental	Environmental & Cultural	Project · environmental	project
  aec-inspection	Construction Inspections	Project · inspection	project
  aec-safety	Safety Report	Project · HSE	project
  aec-stakeholder	Stakeholder Management & Access	Project · stakeholder	project
  aec-traffic	Live Traffic	Project · traffic	project

  Helper functions module(id), feature(id), is_known_module, is_known_feature, and is_default_feature are exported for use by the API write-path validators.

DB schema — enable state

Two migrations add the persistence layer:

• 0007_capability_system.sql (tenant_modules, tenant_features):

  • tenant_modules (tenant_id, module_id, enabled, updated_at) — Provider Admin level; which modules the client has switched on.
  • tenant_features (tenant_id, module_id, feature_id, enabled, updated_at) — Tech Admin level; which features within each module.
  • The dev tenant (tnt_dev_local) is seeded with all live modules enabled and all Smart City features on.
  • 0016_enable_analysis_feature.sql — enables analysis as a default feature for the dev tenant on Smart City, Maritime, and Emergency Services. (live-weather is seeded for Situational Awareness and Maritime Domain Awareness by the same migration.)
  • 0017_enable_compare_feature.sql — enables compare (Swipe Compare) for the dev tenant on Smart City, Maritime, and Emergency Services.
  • 0018_enable_map_export_feature.sql — enables map-export (Map Export & Mapbook) for the dev tenant on Smart City, Maritime, and Emergency Services.
  • 0019_enable_point_cloud_feature.sql — enables point-cloud (3D Data — Point Clouds) for the dev tenant on Smart City, Maritime, and Emergency Services.
  • 0020_enable_grid_modules.sql — enables the five front-line Cartos Grid modules (grid-command, grid-operations, grid-capital, grid-storm, grid-fleet) and their default features for the dev tenant.
  • 0021_grid_modules_phase2.sql — enables the four remaining department modules (grid-vegetation, grid-realestate, grid-environmental, grid-stakeholder) and their default features for the dev tenant.
  • 0022_grid_modules_reenable.sql — re-enables any Grid module/feature rows that were not yet present after the split into two migrations.
  • 0023_grid_operational_data.sql — five Grid operational tables (grid_assets, grid_outages, grid_work_orders, grid_veg_segments, grid_parcels), each with tenant_id + owning_team + GiST geometry index + the tenant_team_isolation RLS policy. Seeded with representative rows for the dev tenant (Charlotte NC for assets/work orders/parcels, central Florida for outages, central California for vegetation segments).
  • 0024_vessel_positions.sql — vessel_positions time-series table (MMSI, name, ship type, SOG/COG/heading, timestamp, PostGIS Point) + port_aois polygons (Jebel Ali, Khalifa Port, Port Rashid); both tenant + team scoped with the standard RLS policy. Seeded with 48 h of synthetic tracks (12 vessels × 96 fixes at 30-min intervals) so the historic AIS endpoints have data immediately.
  • 0025_grid_integrations_oms.sql — grid_integrations connector registry table (RLS, seeded with five connectors); adds source/external_ref/ est_restoration/feeder columns to grid_outages + partial unique index for idempotent upserts; seeds OMS/ADMS as connected, others configured.
  • 0026_grid_maximo_sync.sql — adds source/external_ref to grid_work_orders + upsert index; promotes Maximo connector to connected.
  • 0027_grid_sap_sync.sql — promotes SAP PM connector to connected.
  • 0028_grid_esri_un_sync.sql — adds source/external_ref to grid_assets + upsert index; promotes Esri UN connector to connected.
  • 0029_grid_projects_p6.sql — creates grid_projects table (CIP capital projects — phase/status/budget_musd/pct_complete/schedule + RLS + GiST index + upsert index); promotes P6 connector to connected targeting grid_projects.
  • 0030_grid_msproject_sync.sql — expands the kind CHECK constraint to include msproject; registers Microsoft Project connector as connected.
  • 0031_grid_file_csv.sql — registers the file_csv connector (uses the existing grid_work_orders upsert index from 0026; no schema change needed).
  • 0032_grid_integrations_unique_kind.sql — unique (tenant_id, kind) index on grid_integrations; prevents duplicate connector registrations for the same kind within a tenant.
  • 0033_rls_remaining_tenant_tables.sql — closes the RLS gap: adds ENABLE ROW LEVEL SECURITY + FORCE ROW LEVEL SECURITY + the tenant_team_isolation policy to field_apps, field_features, derived_dataset, analysis_session, and model_job. Combined with the opt-in cartos_app non-superuser DB role, FORCE RLS is enforced end-to-end in production.
  • 0034_grid_integrations_dedup_guard.sql — self-healing deduplication guard on the migration tracking index (drop→dedup→rebuild; no-op when clean).
  • 0035_enable_industry_modules.sql / 0036_industry_project_access.sql / 0037_industry_access_levels.sql — enable + per-project RBAC for the three industry editions, Cartos Tower/Milepost/Blueprint. See §8.3 for the full write-up.
  • 0038_catalog_datasources_layers.sql — the Datasource + Layer Catalog foundation (Phase 1): datasources (a connection to data — internal PostGIS or an external ArcGIS/WMS/WMTS/XYZ/GeoJSON/PMTiles/COG/FlatGeobuf source; auth JSONB credentials, never serialized to clients) and map_layers (a renderable layer bound to a datasource or standalone, with a visibility tri-state on/off/hidden and a style JSONB slot for the Phase-3 symbology engine). Both carry tenant_team_isolation RLS extended with role + user-type axes (visible_roles / visible_user_types, NULL/empty = visible to all) on top of the standard tenant + owning_team scope. Additive — a disjoint cat- source/layer prefix sits alongside overlay_layers (STAC) and Grid layers; nothing existing changes.
  • 0039_enable_catalog_seed.sql — enables the catalog feature for smart-city + grid-command (dev tenant) and seeds two public demo datasources/layers (Esri World Imagery raster; USGS 24h earthquakes GeoJSON) so the render path is exercisable with no credentials.
  • 0040_catalog_features.sql — Phase 2A: catalog_features (layer_id FK → map_layers ON DELETE CASCADE, props JSONB, geom GEOMETRY(4326), GiST index, tenant-isolation RLS) — lets a postgis-internal datasource host real feature data ingested by the region loader (cartos-cli load-geojson) instead of a live external service. Features inherit their parent layer's visibility (checked by the serving endpoint), so this table needs only tenant isolation plus the FK cascade.
  • 0041_enable_catalog_more_modules.sql — Phase 2B rollout: enables catalog for maritime, emergency-services, and the three industry-edition modules that received real data (air-airtraffic, dot-executive, aec-portfolio).

• 0008_user_module_access.sql (user_module_denials):

  • user_module_denials (tenant_id, user_id, module_id, created_at) — User Admin level; a row here means the user is denied that module even though the tenant has it enabled (deny-override model: no row = default allowed, so admins configure only exceptions rather than every user × module pair).

Effective entitlements (crates/cartos-data/src/capabilities.rs)

load_entitlements(pool, tenant_id, user_id) returns an Entitlements struct: modules (tenant_modules enabled, minus user_module_denials) + features (tenant_features enabled, as "module_id/feature_id" strings). Helpers set_module_enabled, set_feature_enabled, and set_user_module_access are the write paths called by the admin API handlers.

Cross-pollinating features

The global feature registry decouples features from modules: a Tech Admin can attach any catalog feature to any module as an "advanced" add-on, beyond that module's defaults. For example, overture can be cross-added to the Maritime module so that maritime operators see Overture POI and road data alongside their vessel tracks. The API write-path (PATCH /api/admin/features/{module}/{feature}) validates the module id and feature id independently (not checking membership) for exactly this reason.

The Overture overlay is now a portable feature component (cartos-web/src/features/overture/OvertureOverlay.tsx) that owns its own layers, 3D buildings logic, and control panel. It is mounted by any module that has the <module>/overture capability enabled, passing in the module's map ref and a namespaced panel id. Smart City and Maritime both mount it.

Three admin tiers

All three are Keycloak realm roles in deploy/keycloak/cartos-realm.json; the full admin role is a superset:

Enforcement — three gates

1. Launcher nav (ModuleNav): AppShell fetches /api/capabilities on mount and stores the result in a CapabilitiesContext (useCapabilities()). ModuleNav receives enabledModules from the shell; items not in the enabled set are hidden entirely. If the fetch fails, null is left in context and the nav shows everything (fail open; hard enforcement is server-side).

2. Per-module feature panels: modules read useCapabilities() and gate their dockable panels behind enabled.features.includes("<module>/<feature>"). For example, Smart City wraps its Overture panel in a capability check for smart-city/overture. The OvertureOverlay is not even mounted when the feature is off. The analysis panel (Analyst Intelligence) is gated the same way — smart-city/analysis, maritime/analysis, emergency-services/analysis — and its dock button is hidden when the feature is disabled for that module.

3. Agent tool surface: as described in §7.3, the /api/agent/chat handler narrows the tool set to modules the calling user has enabled. A module whose tools are removed from the surface is invisible to the LLM.

   Hard data-route enforcement (HTTP 403 from module data routes when the module is disabled) is not yet implemented — the capability system currently gates the nav + panels + agent surface; the underlying REST routes for module data remain accessible to any authenticated user with a valid JWT.

Web admin surface (cartos-web/src/modules/admin/)

The Admin module (AdminModule.tsx) is a tabbed config with five tabs rendered based on the caller's roles:

• Modules (provider_admin) — CapabilityConfig mode="modules": toggle each catalog module on/off for this tenant. Shows vertical, min tier, and default feature count.
• Features (tech_admin) — CapabilityConfig mode="features": for each enabled module, toggle its default features and cross-add any advanced feature from the global pool (e.g. add overture to Maritime).
• Field Apps (tech_admin) — FieldAppsConfig: build bespoke field-capture apps (see §7.5).
• Integrations (tech_admin) — IntegrationsConfig: register and configure Cartos Grid system-of-record connectors in the grid_integrations registry. Capabilities: add a connector (kind, display name, target table, initial status), change status (configured / connected / syncing / error), retarget it to a different Grid table (grid_assets / grid_outages / grid_work_orders / grid_projects / africa_parcels), update its config JSON (endpoint / credentials — write-only, not read back), or delete the registration. The known connector kinds (oms_adms, esri_un, maximo, sap, p6, msproject, file_csv, plus parcel_fabric and featureserver added by migration 0088 for the Cartos Africa cadastre ingest — see §8.4) are validated by a DB CHECK; arbitrary new kinds are a future follow-up. Config/operation split: this tab owns connector configuration; operating a connector (Sync / Import CSV) is done from the Grid dashboard "Systems of record" chip strip.

Admin console usability pass (2026-07-29). The Modules and Features tabs gained module and feature filters — with nine editions and 67 department modules the ungated lists had become long enough to be hard to work in. The Catalog and Integrations tabs gained a Test button with a coloured status badge (modules/admin/TestBadge.tsx, backed by a probe route in crates/cartos-api/src/grid.rs), so a datasource or connector endpoint can be checked in place instead of by triggering a sync and reading the outcome afterwards.

• Users & Teams (user_admin) — existing team/group management plus a per-user UserModulesEditor (expandable inline): shows which tenant modules the user may access and lets an admin revoke specific ones (deny-override).

Changes take effect on each user's next page load (capabilities are fetched on mount).

Identity federation

docs/identity-federation-design.md documents the planned model for sourcing users, teams, roles, and credentials per sovereign deployment by federating Keycloak to the client's own IdP or Active Directory. This is design only, not built — it is the natural next step after the capability system for clients who require that identity stays under their own control.

7.5 Cartos Field — Phase 3A/3B

Status: built and merged to main. The full loop — config → capture → sync → analyst map — is in place, the Flutter mobile app compiles in CI and distributes Android APKs via Firebase App Distribution. Remaining work: on-device Android test (APK is live), iOS TestFlight (pending Apple Developer enrollment), and a minor definition-version reconciliation.

What it is: the full Cartos Field stack — a configurable, offline-first mobile field-capture platform that extends the sovereign data fabric to the field edge. What is built:

1. Sync/field backend — DB tables, data layer (cartos-data), and API routes.
2. Web config console — a "Field Apps" tab in Admin · Configuration.
3. Capability integration — Field is a first-class catalog module, route-gated.
4. Analyst web module — captured ground truth on the map (/field).
5. Agent tools — cross-module; the agent can discover apps + summarize captures.
6. Media backend — photos and signatures upload and download via /api/field/media.
7. Field Apps → Modules — field apps are assignable to platform modules; their captures surface on those modules' maps via a portable overlay.
8. Demo seeds — two published apps (Asset Inspection → Smart City; Port & Vessel Inspection → Maritime) with sample captures.
9. Flutter mobile app — schema-driven capture, geometry editor, photos + signatures, offline queue, offline basemap caching, background sync, OIDC/PKCE auth, CI-compiled on Android (APK distributed via Firebase App Distribution).
10. CI/distribution — Android CI workflow; iOS CI workflow (signed upload to TestFlight gated on Apple secrets).
11. Git infra fix — .gitattributes (*.sql text eol=lf) preventing sqlx checksum failures from Windows autocrlf.

Data model (migration 0009_field_init.sql)

Two new tables join the data fabric:

field_apps — a versioned field-app definition authored by a Tech Admin:

field_features — captured ground truth synced from the mobile app:

Both tables carry (tenant_id, owning_team) indexes and follow the same owning_team IS NULL OR owning_team = ANY($groups) group-access filter as all other Cartos tenant data (see docs/group-access-design.md).

Field types supported in the definition schema: text, number, choice (comma-separated options), date, boolean, photo, signature.

Data layer (crates/cartos-data/src/field.rs)

• list_apps(pool, tenant_id, groups) — tenant + group-filtered list.
• get_app(pool, tenant_id, slug) — single app by slug (no group filter — slug is needed by the mobile pull regardless of owning_team).
• create_app(pool, tenant_id, slug, name, description, owning_team) — insert.
• update_app(pool, tenant_id, slug, name?, description?, status?, definition?) — partial update; bumps version only when definition is supplied (via CASE WHEN $6::jsonb IS NOT NULL THEN version + 1 ELSE version END).
• delete_app(pool, tenant_id, slug) — hard delete (cascades to features).
• sync_features(pool, tenant_id, app_id, captured_by, captures) — inserts a batch of CaptureInputs inside a single transaction; each row uses ON CONFLICT (tenant_id, client_id) DO NOTHING so the call is idempotent and safe to replay. Returns the count of newly inserted rows.
• list_features(pool, tenant_id, app_id, groups, limit) — group-filtered, ordered by captured_at DESC, capped at 5 000.

API routes (crates/cartos-api/src/field.rs, src/media.rs)

Config operations require tech_admin (or full admin); capture sync, feature reads, and media endpoints are open to any authenticated tenant user.

ApiError::NotFound was added to the error enum to produce clean HTTP 404 responses on unknown slugs.

Web config console (cartos-web/src/modules/admin/FieldAppsConfig.tsx)

A Field Apps tab appears in Admin · Configuration alongside Modules, Features, and Users & Teams. It is gated on tech_admin (the same check as the Features tab). The component presents a two-pane layout:

• Left pane — app list: shows every field app (slug · vN · status) for this tenant. An inline create form takes a slug and a display name.
• Right pane — definition editor: shown when an app is selected. Editable fields: name, description, and status (draft / published) via a dropdown. The current version number is displayed read-only. A Save button issues a PATCH and shows the new version number on success.
  • Layers: add/remove layers; per-layer: key, label, geometry type (point / line / polygon — switches the default colour swatch), and a colour picker.
  • Fields per layer: add/remove schema fields; per-field: key, label, type (text / number / choice / date / boolean / photo / signature), a required checkbox, and a comma-separated options input (shown only for choice).
  • Delete app: guarded by a confirm dialog; hard-deletes the app and all its captured features.
  • Surfaces in modules: a multi-select listing every catalog module. Selections call PUT /api/field/apps/{slug}/modules and persist via field_app_modules. Apps assigned here appear in those modules' FieldCapturesOverlay and in the list_field_apps agent tool when scoped to that module.

The mobile app pulls the published definition from GET /api/field/apps/{slug} and submits captures (with media keys already resolved) to POST /api/field/apps/{slug}/sync.

Capability integration

Cartos Field is a first-class catalog module (field, "Cartos Field", vertical field-ops) — not a bolt-on. It plugs into all four capability gates:

• Catalog (cartos-core): the field module ships with satellite as a default feature; new catalog modules are off by default until a Provider Admin enables them.
• Route gate (cap_guard): every /api/field/* route requires the field module enabled for the caller's tenant (403 otherwise), except /api/field/captures/{module_id} which cap_guard exempts — that route gates in-handler by the host module instead, so users of Smart City, Maritime, etc. can read their module's field data without the field module.
• Nav gate (cartos-web): the "Cartos Field" nav entry + /field route are auto-filtered against /api/capabilities enabled.modules.
• Seeds: migration 0010_enable_field_module.sql enables field + satellite for the dev tenant. migration 0011_field_app_modules.sql adds the field_app_modules many-to-many table (tenant_id, app_id, module_id).

Analyst web module (cartos-web/src/modules/field/FieldModule.tsx)

A native MapLibre module at /field that closes the loop config → capture → sync → analyst map. It lists the tenant's published apps, and for the selected app renders its captured field_features on the map — points, lines, and polygons coloured by their layer's definition colour — with a click popup showing each feature's attributes (including photo/signature thumbnails via authenticated blob fetch using api().getBlob) plus capture lineage (who / when / device / accuracy). A DockablePanel lists apps and per-layer capture counts; the map fits bounds to the data.

Portable captures overlay (cartos-web/src/features/field-captures/FieldCapturesOverlay.tsx)

A self-contained portable React component that renders a host module's assigned field captures on that module's MapLibre map. It calls GET /api/field/captures/{module_id}, colours features by their layer definition colour, and provides click-to-detail with attribute table and photo/signature thumbnails (using MediaImage, same authenticated getBlob pattern as the analyst module). It is currently mounted in Smart City, Maritime, and Emergency Services. The component is namespaced (stable DockablePanel id per module) and is self-contained — no coupling to the host module beyond a map ref and the module id.

Media backend (crates/cartos-api/src/media.rs)

Photos and signatures flow through the API rather than directly to object storage, so the mobile contract is storage-backend-agnostic:

• Upload (POST /api/field/media): raw body (one file per request, up to 25 MB). Extension is resolved from ?ext= query param or the Content-Type header (jpeg/png/webp/heic/gif/pdf). File is written to $CARTOS_MEDIA_DIR/{tenant_id}/{uuid}.{ext} and the response carries {key, url, bytes, content_type}. Storage is swappable to MinIO/S3 without changing the mobile contract.
• Download (GET /api/field/media/{key}): streams the file back with the correct MIME type. Tenant isolation + path-traversal guard: the key must start with the caller's tenant_id/ and .. is rejected (403 otherwise).

Both routes sit under /api/field/ and are therefore field-module gated (except the captures/{module} carve-out described above).

Field Apps → Modules (migration 0011_field_app_modules.sql)

A many-to-many table field_app_modules (tenant_id, app_id, module_id) lets a Tech Admin assign each field app to one or more platform modules. Data-layer helpers:

• set_app_modules(pool, tenant_id, app_id, modules) — replaces the full set (delete + re-insert in one transaction).
• app_modules(pool, tenant_id, app_id) — list modules for one app.
• all_app_modules(pool, tenant_id) — used by list_apps to graft modules onto every app response in one query.
• apps_for_module(pool, tenant_id, module_id, groups) — used by the GET /api/field/captures/{module} handler and the list_field_apps agent tool.

Seed assignments: asset-inspection → smart-city; port-inspection → maritime.

Agent tools (cartos-agent)

Two cross-module tools (module returns None — always exposed regardless of which module is active) let the agent reason about field data:

• list_field_apps — discover configured apps (slug, name, version, status, layer count). Accepts an optional module argument (e.g. "smart-city") to scope the list to apps assigned to that module — useful when the user is working in a specific module context.
• summarize_field_captures(slug) — total synced features + a per-layer breakdown (with defined labels) + the latest capture time.

Demo seed (cartos-cli seed)

seed_field adds two published apps with captured features, both idempotent via deterministic UUIDs:

• Asset Inspection (asset-inspection, assigned to smart-city): inspection point layer (condition choice + notes + photo) + defect-run line layer (severity choice). Four captures around Reem Island (3 × inspection, 1 × defect line).
• Port & Vessel Inspection (port-inspection, assigned to maritime): vessel check point layer (vessel name + flag + status choice + photo) + spill area polygon layer (severity + notes). Four captures at Khalifa Port (3 × vessel points, 1 × spill polygon).

Flutter mobile app (cartos-field-mobile/)

The native client is a Flutter app (com.cartos.field). It is CI-compiled and the Android APK is live. Key source files:

• lib/models.dart — FieldApp, LayerDef, FieldDef, Capture, PendingMedia (photos/signatures queued for upload on sync).
• lib/api/field_api.dart — typed client for all /api/field/* endpoints including uploadMedia.
• lib/db/local_store.dart — sqflite offline capture queue; captures are written locally first and marked synced only after the server confirms.
• lib/sync/sync_service.dart — store-and-forward sync: uploads pending media files first (writing returned keys into properties), then pushes the capture batch (idempotent via device-generated client_id). Safe to replay.
• lib/sync/background_sync.dart — workmanager periodic task (15-min on Android; opportunistic BGTaskScheduler on iOS). Drains the offline queue from a headless isolate using a stored refresh token — no UI needed.
• lib/auth/auth_service.dart — OIDC Authorization-Code + PKCE against the same Keycloak realm (cartos-mobile client). Sovereign IdP federation drops in upstream for free when that design is implemented.
• lib/screens/capture_screen.dart — schema-driven capture form: layer picker, schema-typed field inputs (text / number / choice / date / boolean / photo via image_picker / signature via the signature pad), geometry section. Point layers offer "Capture here" (current GPS fix) or "Pick on map"; line/polygon layers require the map geometry editor. Capture is written to the local queue first, surviving offline.
• lib/screens/capture_map_screen.dart — maplibre_gl geometry editor. Tap to add vertices (point: one tap replaces; line: ordered polyline ≥ 2 vertices; polygon: closed ring ≥ 3 vertices, auto-closed). Undo / Clear toolbar. "Cache this area offline" button triggers a basemap tile download for the current view.
• lib/offline/offline_maps.dart — OfflineMaps wraps the MapLibre offline-region API: downloadArea(bounds, name, minZoom=10, maxZoom=15) with a progress callback. A progress dialog is shown in-app. Regions are listed and deletable from the Offline maps manager screen (offline_maps_screen.dart).

CI / distribution:

• .github/workflows/field-mobile-ci.yml (Android, ubuntu-latest): runs on every push to cartos-field-mobile/**. Generates the Android platform shell (flutter create --platforms=android), injects the flutter_appauth redirect scheme, bumps Kotlin to 1.9.22 (required by maplibre_gl), adds runtime permissions (INTERNET, ACCESS_FINE_LOCATION, CAMERA), runs flutter pub get + flutter analyze (non-blocking), then flutter build apk --debug. Publishes app-debug.apk as a build artifact. Firebase App Distribution step (using wzieba/Firebase-Distribution-Github-Action) distributes to the field-testers group on merge-to-main or manual dispatch when repo secrets FIREBASE_ANDROID_APP_ID and FIREBASE_SERVICE_ACCOUNT are set. Skips silently until both are present.
• .github/workflows/field-ios-testflight.yml (iOS, macos-14): runs a no-signing compile check (flutter build ios --release --no-codesign). Signed build + TestFlight upload (via apple-actions/upload-testflight-build) are gated on Apple secrets (APPSTORE_ISSUER_ID, APPSTORE_KEY_ID, APPSTORE_API_PRIVATE_KEY, IOS_DIST_CERT_P12, IOS_DIST_CERT_PASSWORD, IOS_TEAM_ID). TBD pending Apple Developer enrollment. Run on demand only (workflow_dispatch) as of 2026-07-29 — a macos-14 runner costs 10× a Linux one and the compile step is not gated on the secrets, so it was billing a full iOS release build on every mobile push while unable to ship anything. Trigger it with gh workflow run "Field mobile — iOS / TestFlight" --ref main; restore the push trigger once the six secrets are set and one manual run is green. The Android job below still runs on every mobile push.

Remaining 3B items: on-device Android field test (APK distributable now); iOS TestFlight (pending Apple enrollment); minor definition-version reconciliation.

8. The modules

The canonical nav lineup (reorderable — see §9):

Overture Maps overlay (portable feature)

The Overture overlay is a portable feature component (cartos-web/src/features/overture/OvertureOverlay.tsx) mounted by any module that has the <module>/overture capability enabled. It currently appears in Smart City (default feature) and can be cross-added to Maritime or any other module by a Tech Admin. The component owns its own MapLibre layers, 3D buildings logic, and dockable control panel; the mounting module only passes a map ref and a namespaced panel id.

Architecture: a Python/DuckDB FastAPI sidecar (overture-sidecar/main.py, port :8200) queries the public Overture GeoParquet directly from S3 via DuckDB spatial, snaps the viewport bbox to a ~2 km grid for cache reuse, and returns GeoJSON. cartos-api proxies it at GET /api/overture/{theme} (auth required). The sidecar is the first instance of the "Python sidecar" shape the platform anticipates for heavy data work (DuckDB + parquet kept out of the Rust hot path). In production it runs as the overture-sidecar service in docker-compose.prod.yml; the API is pointed at it via OVERTURE_SIDECAR_URL.

Four themes (independent toggles, each with a per-theme zoom gate below which the panel doesn't load):

All themes respond to click-for-attributes, showing a floating popup with the feature's Overture properties.

Smart City — 3D buildings

The Buildings theme exposes a 3D buildings sub-panel with three independent, simultaneously-togglable rendering modes:

Overture extrusion (MapLibre fill-extrusion):

• Footprints extruded by height in metres using the Overture height attribute; falls back to num_floors × 3, then a default of 8 m.
• Live controls: fill colour, opacity, outline toggle + outline colour.
• "Extrude" toggle switches between a flat fill and the 3D extrusion.

Overture wireframe (deck.gl LineLayer):

• True 3D box edges — base ring, roof ring, and vertical edges — built from the same footprint GeoJSON, rendered as discrete 3D line segments via a deck.gl LineLayer overlay. Only the structural edges are drawn (no cap triangulation), giving a clean wireframe without spaghetti artefacts.
• Uses the same height logic as the extrusion so the wireframe is always aligned with the solid.
• Independent controls: edge colour, line width (pixels), and a "wireframe only (hide fill)" mode that disables the MapLibre extrusion layer while leaving the wire on.

Esri 3D Buildings (deck.gl Tile3DLayer + I3SLoader):

• Photoreal 3D mesh from Esri's free global I3S Building Scene Layer service (basemaps3d.arcgis.com/arcgis/rest/services/Esri3D_Buildings_v1).
• Rendered via a MapboxOverlay (non-interleaved, i.e. deck.gl's own canvas above MapLibre's). A coordinate-system compatibility shim remaps @loaders.gl/i3s 4.4 numeric enum values to the string enum expected by @deck.gl/core 9.3.
• Controls: opacity and an optional tint colour (when disabled, mesh uses its own natural materials).
• Gated at zoom ≥ 15. Below that, Esri streams coarse merged-mesh LODs rather than per-building geometry — the gate prevents users from seeing indistinct blobs. Even at zoom ≥ 15, mesh quality varies by region: well-covered urban areas look detailed; sparse regions may be flat extruded masses.
• Esri 3D and the Overture Buildings theme are independent — both can be enabled simultaneously to compare the photoreal mesh against the Overture extrusion.

New web dependencies added: deck.gl ^9.3.3, @loaders.gl/i3s ^4.4.2, @loaders.gl/core ^4.4.2 (cartos-web/package.json).

Source files: cartos-web/src/lib/overture.ts (theme catalogue, colour expressions, fetch helper), cartos-web/src/lib/buildings-3d.ts (deck.gl overlay handle — createBuildings3D → Buildings3DHandle), cartos-web/src/features/overture/OvertureOverlay.tsx (the portable component), cartos-web/src/modules/smart-city/SmartCityModule.tsx (mounts it).

Native module shape: <Module>Module.tsx (MapLibre + DockablePanels) + <Module>Dashboard.tsx. Iframe modules use lib/iframe-bridge.ts.

8.1 Cartos Grid — Electric Utility edition

Status: built and merged to main (PR #67 surfaces; PRs #92–#95 live operational data; PRs #102, #104–#109 all seven SoR connectors). Nine department module surfaces, configurable KPI dashboard, capability-gated; plus six live operational data tables (assets, outages, work orders, vegetation segments, parcels, CIP projects) with real PostGIS geometry, tenant/team RLS, live map layers in every department, KPI API, three Grid agent tools, and a full connector registry for seven system-of-record integrations (OMS/ADMS, IBM Maximo, SAP PM, Esri Utility Network, Primavera P6, Microsoft Project, File/CSV import) — all wired end-to-end.

What it is: the first vertical edition of the Cartos engine, licensed to RAiN Partners for the US electric utility market. Nine department-level module surfaces are delivered via one shared config-driven component (cartos-web/src/modules/grid/GridModule.tsx) driven by the config table in modules/grid/modules.ts (GRID_MODULES). Adding a new department is a new entry in that config — no new component needed.

The nine department modules

Each module renders a HUD bar (module label + department badge) across the top of the map. The PanelDock shows only the panels declared for that module (the panels array in GridModuleConfig); the dashboard panel is in every module's default set.

Configurable KPI Dashboard (GridDashboard.tsx)

A new dashboard capability feature (registered in catalog.rs) that is the default on every Grid module. The dashboard component:

• Loads a metric catalogue (METRICS) of ~18 utility KPIs scoped per department (SAIDI, SAIFI, customers-out, open work orders, crew/fleet utilization, asset health, CapEx vs plan, projects status, hardening miles, vegetation risk, ROW encroachments, environmental permits, stakeholder items, and more).
• On mount, loads the persisted card layout from localStorage (key: cartos.grid-dashboard.<moduleId>.<userId>). Falls back to the top-6 department-relevant metrics.
• Edit mode (toggle with the "Edit" button): add a KPI from a dropdown picker (scoped to the current module), remove a card (✕), switch its chart type via an inline <select>, and drag-to-reorder cards. "Reset" returns to the default 6 cards.
• Five chart types via Apache ECharts (echarts-for-react): stat (headline number + delta vs prior period, colour-coded by good/bad direction), bar, line, pie (donut), gauge.
• The toolbar always shows a note: "Sample KPIs — bind to live map data as layers ship" (values are representative sample data; the metric structure is ready to accept live API data when operational layers arrive).
• Layout (card order + chart type choices) persists per user + module in localStorage; a different user or a different Grid module gets an independent dashboard.

Engine reuse

All nine Grid modules inherit every engine cross-cutting feature via the shared GridModule.tsx: theme-matched basemaps, the analysis / compare / map-export / point-cloud / dashboard overlays from PanelDock, the full capability-gate system (gated per grid-<dept>/<feature>), the agent chat panel, and the platform theme switcher. Three Grid-specific agent tools are now registered (cross-module — module() returns None so they surface on every Grid department): grid_kpis, grid_active_outages, and grid_open_work_orders (see §7 — The AI agent, for descriptions).

Live operational data (PRs #92–#95)

Migration 0023_grid_operational_data.sql adds five operational tables; migration 0029_grid_projects_p6.sql adds a sixth. Together these six tables make every department map surface live:

All five tables are tenant + team scoped (owning_team IS NULL OR owning_team = ANY($groups)) with the tenant_team_isolation Postgres RLS policy (same pattern as all other Cartos data). GiST indexes on geom and compound indexes on (tenant_id, owning_team) and (tenant_id, <status-key>). Seeded for tnt_dev_local with representative rows at each department's map centre (Charlotte NC, central Florida, central California).

API endpoints (crates/cartos-api/src/grid.rs, registered in main.rs):

All endpoints require a Bearer JWT; they are not gated by a specific Grid module capability (any authenticated tenant user can read). Each query runs inside a set_tenant_session transaction (RLS session vars) with a belt-and-braces owning_team IS NULL OR owning_team = ANY($groups) WHERE filter. Limit: 5 000 rows.

Frontend — Grid Data panel (lib/grid-data.ts, GridModule.tsx):

• GRID_LAYER_META maps each of the five GridLayerKeys (assets, outages, work_orders, vegetation, parcels) to its endpoint URL and a swatch colour.
• DEPT_LAYERS declares which data layers each department surfaces by default: e.g. grid-command defaults to ["assets","outages"], grid-vegetation to ["vegetation"], grid-environmental to ["parcels","vegetation"], grid-capital to ["projects","assets"].
• fetchGridLayer fetches a layer endpoint and builds a GeoJSON.FeatureCollection (parses each row's geojson string).
• reconcileGridLayers adds/removes MapLibre grid-* sources and layers to match the active set, with per-layer paint expressions: assets → health-coded circles (#e2607a critical / #e9a23b at_risk / #2ecc96 healthy) + conductor lines; outages → status-coded circles with radius proportional to customers_affected; work orders → priority-coded circles; vegetation → risk-coded lines; parcels → encroachment-coded fill + outline polygons.
• fetchGridKpis calls GET /api/grid/kpi and returns the GridKpis struct. The dashboard KPI cards in GridDashboard.tsx are now bound to this live data — customers_out, outages_active, work_orders_open, projects_total, projects_active, projects_budget_musd, etc. map directly to the API response fields.
• A Grid Data panel in the PanelDock lists the available layers with toggle checkboxes and colour swatches; toggling a layer adds/removes it from the active set and triggers a fetch if the data has not yet been loaded for that department.
• Clicking a grid-* circle or polygon on the map opens a detail popup with the row's key attributes.

Cloud-native data layer — object-storage format spikes (Grid Data panel, PRs #113–#117)

Status: spikes / proofs-of-concept. Demo data only (synthetic Grid assets + CIP projects). Public-read MinIO bucket in dev; not yet access-gated or hardened. See §9.5 for the full implementation reference.

The Grid Data panel has a second group of toggles below the live operational layer checkboxes, labelled "Cloud-native (spike)". These drive five object-storage-native format experiments — zero new services; the browser range-reads everything directly from MinIO:

• PMTiles · MinIO (assets): checkbox toggle — addPmtilesAssets/removePmtilesAssets from lib/pmtiles-layer.ts; renders grid-assets.pmtiles via the pmtiles:// protocol.
• FlatGeobuf · MinIO (bbox-streamed): checkbox toggle — loadFgbAssets/removeFgbAssets from lib/flatgeobuf-layer.ts; re-reads on map moveend (only the viewport bbox is fetched).
• COG · MinIO (raster): checkbox toggle — addCog/removeCog from lib/cog-layer.ts; renders demo-surface.tif via cog://.

The DuckDB-WASM panel is launched from the grid-capital (CIP & Major Projects) module (distinct launcher button in the panel dock). It loads grid-projects.parquet from MinIO into an in-browser DuckDB instance and presents a SQL query input; results render in a table. No analytics server; PostGIS is untouched.

The Geoprocessing panel (buffer / convex hull / centroid via Turf.js) and Export panel (GeoJSON / Shapefile / FlatGeobuf / CSV client-side + GeoPackage from MinIO) are available on all Grid modules via the panel dock, as portable features/ components following the standard DockablePanel contract.

Systems-of-record (SoR) integrations (PRs #102, #104–#109)

All seven connectors are now wired end-to-end. A new grid_integrations registry table tracks each connector's status, last sync timestamp, and last sync result. Six connectors run realistic mock/synthetic feeds that demonstrate the live-integration pattern (ready for production credential swap); the seventh (File/CSV) ingests real uploaded data today. Every sync is idempotent — upsert keyed by (tenant_id, external_ref) — and tenant/RLS scoped.

Connector registry table — grid_integrations (migration 0025):

The seven connectors:

CSV import (connector 7 — file_csv):

Operator uploads a work-order CSV via the "Import CSV" file-picker on the dashboard SoR chip. The API (crates/cartos-api/src/grid.rs → import_csv) parses a header-driven comma-separated file and batches a single UNNEST upsert into grid_work_orders.

Required CSV columns: external_ref, lon, lat. Optional columns: kind, status, priority, crew, due_date — defaulted/normalised if absent or outside the allowed value set.

A column template is available at docs/samples/grid-work-orders.csv:

external_ref,kind,status,priority,crew,due_date,lon,lat

CSV-1001,inspect,open,high,Crew 7,2026-07-15,-80.84,35.23

Re-uploading the same file updates existing rows (upsert on external_ref) rather than creating duplicates. The API response carries {imported, created, updated, skipped}.

New grid_projects table (migration 0029):

CIP capital-improvement projects table, fed by both P6 and MS Project schedulers:

The grid_projects table carries the full tenant_team_isolation RLS policy (same pattern as all other Grid tables). GiST index on geom; compound indexes on (tenant_id, status) and (tenant_id, owning_team).

New Grid KPIs from grid_projects:

The GET /api/grid/kpi response now includes three additional fields:

CIP projects map layer (grid-capital module):

DEPT_LAYERS["grid-capital"] now defaults to ["projects", "assets"]. Project features are rendered as status-coded circles on the map: delayed → red, at_risk → amber, complete → grey, on_track → violet (#a78bfa). Clicking a project circle opens the standard Grid detail popup. This makes the grid-capital (CIP & Major Projects) module live.

Frontend — dashboard SoR strip (GridDashboard.tsx):

The GridDashboard component loads connectors via fetchIntegrations and renders a "Systems of record:" chip strip below the KPI cards:

• Each chip shows the connector's short name + a status badge ("● live" or "pending").
• A chip tooltip shows the target table and last sync time.
• Clicking the sync button on a connected mock chip calls syncIntegration → POST /api/grid/integrations/{kind}/sync and refreshes both the KPI panel and the chip strip.
• The file_csv chip shows an "Import CSV" label that triggers a <input type="file"> file-picker; the selected file is read as text and passed to importGridCsv → POST /api/grid/integrations/file_csv/import. The result message (e.g. "Imported 5 (+3 ~2)") is shown inline for a few seconds.

API surface (SoR endpoints):

Calling sync on file_csv returns a 400 Bad Request with a clear message directing the caller to the import endpoint instead.

Opt-in continuous mock schedulers (crates/cartos-api/src/oms_sync.rs):

Six background tasks — one per mock connector — can be enabled individually via env vars to make map layers and KPIs evolve continuously as if receiving live feeds. file_csv has no scheduler (it is upload-driven).

All tenant vars default to tnt_dev_local; all interval vars have a minimum of 30 s.

Real connector adapter seam (PR #123)

PR #123 ships the seam that lets any connector flip from mock feed to live system-of-record without any schema or UI change. connectors/esri_un is the reference implementation — verified against a public ArcGIS Feature Server (fetched and upserted 25 point features into grid_assets). The other five connectors (oms_adms, maximo, sap, p6, msproject) are still mock feeds; they go live once an operator pastes a service_url into their config. file_csv is upload-driven and does not use this seam.

How it works — crates/cartos-api/src/connectors/:

The grid::sync handler reads the connector's stored config via gi::get_config once up front, then calls connectors::is_real(&config). If config.service_url is a non-empty string the handler routes to connectors::real_sync(kind, …); otherwise the existing mock feed runs unchanged. The gap is explicit: if a connector has a service_url set but no real adapter is wired yet, real_sync returns a 400 with a clear message rather than silently falling back.

// grid::sync (simplified)

let config = gi::get_config(pool, &ctx.tenant_id, &kind).await?;

if connectors::is_real(&config) {

    return Ok(Json(connectors::real_sync(&kind, pool, &ctx.tenant_id, &config).await?));

}

// … existing mock feeds below …

RealConnector trait (connectors/mod.rs):

pub trait RealConnector {

    async fn sync(

        &self,

        pool: &PgPool,

        tenant_id: &str,

        config: &serde_json::Value,

    ) -> Result<serde_json::Value, ApiError>;

}

Adding a new real adapter = implement RealConnector for a new struct + add one arm to real_sync. No migration, no UI change.

connectors/esri_un.rs — reference implementation:

Queries any ArcGIS Feature/Map Server layer (config.service_url) for its point features as GeoJSON and upserts them into grid_assets. Config keys (set via Admin → Integrations → ⚙):

Scope today: only point features are mapped (line/polygon geometries are skipped). external_ref is formatted UN-{id}. The sync response includes {source, mode:"real", service_url, fetched, upserted, created, updated}.

cartos-data additions (PR #123):

• get_config(pool, tenant_id, kind) — reads a connector's config JSONB column; returns {} if the connector is not registered. Called once by grid::sync before the real-vs-mock branch.
• RealAsset struct — {external_ref, kind, name, lon, lat} — the minimal shape every real adapter assembles before calling the shared upsert.
• upsert_real_assets(pool, tenant_id, source, rows) — generic batch UNNEST upsert into grid_assets keyed by (tenant_id, external_ref) partial unique index; same idempotent pattern as the mock feeds; returns {created, updated}. Source-tagged so real and mock rows coexist without collision.

Operator workflow — flipping a connector mock → real:

1. In Admin → Integrations, click ⚙ on the target connector (e.g. esri_un).
2. Set {"service_url": "https://…/FeatureServer/0", "token": "…"} in the config field and save (PATCH /api/grid/integrations/{kind}).
3. Click Sync on the dashboard SoR chip — grid::sync now detects service_url and runs the real adapter instead of the mock feed.
4. To revert: clear service_url from the config and sync — the mock feed resumes.

Data layer (crates/cartos-data/src/grid_integrations.rs):

• list_integrations(pool, tenant_id, groups) — tenant + group-filtered list, connected-first sort.
• create_integration(pool, tenant_id, kind, name, target, status, config) — register one connector; duplicate kind hits the unique (tenant_id, kind) index added by migration 0032.
• update_integration(pool, tenant_id, kind, name?, target?, status?, config?) — partial patch via COALESCE; NULL args leave existing values unchanged; returns rows-affected (0 = unknown kind).
• delete_integration(pool, tenant_id, kind) — remove a connector row; returns rows-affected (0 = unknown kind).
• sync_oms(pool, tenant_id) — OMS/ADMS mock upsert into grid_outages.
• sync_work_orders(pool, tenant_id, source, ref_prefix, n) — shared helper for Maximo + SAP PM.
• sync_maximo(pool, tenant_id) → sync_work_orders(…, "maximo", "MAX-", 60).
• sync_sap(pool, tenant_id) → sync_work_orders(…, "sap", "SAP-", 50).
• sync_esri_un(pool, tenant_id) — Esri UN mock upsert into grid_assets (~80 devices).
• sync_projects(pool, tenant_id, source, ref_prefix, n) — shared helper for P6 + MS Project.
• sync_p6(pool, tenant_id) → sync_projects(…, "p6", "P6-", 40).
• sync_msproject(pool, tenant_id) → sync_projects(…, "msproject", "MSP-", 30).
• import_csv_work_orders(pool, tenant_id, rows) — single-batch UNNEST upsert of pre-validated CsvWorkOrder rows into grid_work_orders; updates file_csv connector's last_sync / last_result.

Every function runs inside a set_tenant_session transaction (RLS session vars) and updates the grid_integrations row's status, last_sync, and last_result on completion, so the dashboard chip strip reflects the outcome immediately.

Source files:

crates/cartos-data/src/grid_integrations.rs · crates/cartos-api/src/grid.rs (SoR handlers: integrations, create_integration, update_integration, delete_integration, sync, import_csv) · crates/cartos-api/src/oms_sync.rs (six background schedulers) · cartos-web/src/lib/grid-data.ts (fetchIntegrations, syncIntegration, importGridCsv, createIntegration, updateIntegration, deleteIntegration; CONNECTOR_KINDS / GRID_TARGET_TABLES / INTEGRATION_STATUSES constants; projects layer meta, GridKpis.projects_*) · cartos-web/src/modules/admin/IntegrationsConfig.tsx (Admin → Integrations tab UI) · cartos-web/src/modules/grid/GridDashboard.tsx (SoR chip strip + Import CSV picker) · crates/cartos-data/migrations/0025_grid_integrations_oms.sql · crates/cartos-data/migrations/0026_grid_maximo_sync.sql · crates/cartos-data/migrations/0027_grid_sap_sync.sql · crates/cartos-data/migrations/0028_grid_esri_un_sync.sql · crates/cartos-data/migrations/0029_grid_projects_p6.sql · crates/cartos-data/migrations/0030_grid_msproject_sync.sql · crates/cartos-data/migrations/0031_grid_file_csv.sql · crates/cartos-data/migrations/0032_grid_integrations_unique_kind.sql · docs/samples/grid-work-orders.csv (CSV column template) · crates/cartos-api/src/connectors/mod.rs (RealConnector trait + is_real + real_sync registry) · crates/cartos-api/src/connectors/esri_un.rs (Esri UN reference real adapter).

Source files (all §8.1): cartos-web/src/modules/grid/GridModule.tsx · modules/grid/modules.ts · modules/grid/GridDashboard.tsx · modules/grid/GridDashboard.css · modules/grid/GridModule.css · cartos-web/src/lib/grid-data.ts · crates/cartos-data/src/grid.rs · crates/cartos-data/src/grid_integrations.rs · crates/cartos-api/src/grid.rs · crates/cartos-api/src/oms_sync.rs · crates/cartos-api/src/connectors/mod.rs · crates/cartos-api/src/connectors/esri_un.rs · crates/cartos-agent/src/builtin/grid_kpis.rs · grid_active_outages.rs · grid_open_work_orders.rs · crates/cartos-core/src/catalog.rs (vertical "utility", nine ModuleDef entries) · crates/cartos-data/migrations/0020_enable_grid_modules.sql · crates/cartos-data/migrations/0021_grid_modules_phase2.sql · crates/cartos-data/migrations/0022_grid_modules_reenable.sql · crates/cartos-data/migrations/0023_grid_operational_data.sql · crates/cartos-data/migrations/0025_grid_integrations_oms.sql – 0031_grid_file_csv.sql · cartos-grid-PRD/ (PRD + Capability Brief — deep-integration roadmap).

8.2 Historic AIS analytics — Maritime module

Status: built and merged to main (PRs #96–#98). Vessel track replay, density heatmap, and port-call analytics are live in the Maritime module via the MaritimeAnalyticsOverlay. The opt-in live AIS ingester (ais_ingest.rs) can continuously append fixes from the VesselFinder feed. MDA (the Cesium iframe module) is a noted gap — it receives live vessels via the iframe bridge but does not yet use the new historic endpoints.

What it is: a portable DockablePanel overlay (features/maritime-analytics/MaritimeAnalyticsOverlay.tsx) mounted in the Maritime module that surfaces three views of the accumulated vessel_positions time-series:

Time window options: 24 h, 48 h, 7 days (168 h). All queries are scoped by the calling user's tenant_id and groups.

Data model (migration 0024_vessel_positions.sql)

Two tables follow the standard Cartos tenant/team-scoped shape:

vessel_positions — append-only AIS time-series:

Indexes: (tenant_id, mmsi, ts) (track queries), (tenant_id, ts) (window scans), (tenant_id, owning_team), GiST on geom (port-call spatial join).

port_aois — named polygon AOIs for port-call detection:

Both tables carry the tenant_team_isolation RLS policy. Seeded with 12 vessels × 96 fixes (48 h at 30-min intervals) routed toward three UAE Gulf ports (Jebel Ali, Khalifa Port, Port Rashid) so port-call queries return populated results immediately.

API endpoints (/api/mobility/history/*)

Registered in main.rs alongside the existing /api/mobility/* live feeds:

mmsi is required for the track endpoint; all others are optional. hours clamps to 1–720. cell clamps to 0.005–1.0.

Opt-in live ingester (crates/cartos-api/src/ais_ingest.rs)

maybe_spawn(db) is called from main at startup. It no-ops unless CARTOS_AIS_INGEST=1 is set in the environment, keeping the default deployment quiet. When enabled:

The ingester samples fetch_vesselfinder (same function used by the live Global Mobility feed) and calls ais::insert_positions to append the current fixes into vessel_positions. Over time this builds a real historic dataset that the analytics endpoints can query.

AIS analytics in the MDA Cesium globe (PR #103):

The previously documented gap — "historic AIS not yet surfaced in the Cesium MDA iframe" — is now closed. PR #103 extends the iframe bridge with a cartos.ais.set message and adds a new portable component AisBridgeControls.tsx that surfaces the same three analytics views (Tracks / Density / Port calls) in any Cesium-backed module:

• AisPayload type in lib/iframe-bridge.ts carries one of four modes: track (ordered {lon,lat} polyline + scrubber head + label), density (binned {lon,lat,count} cells), ports (named {lon,lat,vessels} markers), or clear (removes all AIS entities).
• bridge.setAis(payload) sends cartos.ais.set to the iframe host. The EarthWatch3D Cesium app (../cesium_project_SPS) handles the message and renders tracks, density heatmap, and port markers on the globe.
• AisBridgeControls.tsx (mounted in the MDA module) replicates the Maritime module's analytics panel controls — vessel picker, time window, mode toggle, time scrubber, Play button — but calls bridge.setAis instead of drawing MapLibre layers. On unmount it sends {mode: "clear"} to clean up globe entities.

The MDA module now has full feature parity with the native Maritime module for historic AIS analytics, running on the photoreal 3D Cesium globe.

Source files: cartos-web/src/features/maritime-analytics/MaritimeAnalyticsOverlay.tsx · MaritimeAnalyticsOverlay.css · cartos-web/src/features/maritime-analytics/AisBridgeControls.tsx · cartos-web/src/lib/ais.ts · cartos-web/src/lib/iframe-bridge.ts (AisPayload type, bridge.setAis) · crates/cartos-data/src/ais.rs · crates/cartos-api/src/ais.rs · crates/cartos-api/src/ais_ingest.rs · crates/cartos-data/migrations/0024_vessel_positions.sql.

8.3 Cartos Tower, Milepost & Blueprint — Airport, DOT & AEC editions

Status: built and merged to main 2026-07-07, live on their own subdomains on the stakeholder-demo VM — tower./milepost./blueprint.cartosatlas.com (deploy/Caddyfile.prod; see §2). 29 department module surfaces across three editions, a shared config-driven IndustryModule component, per-project/portfolio-wide access-grant RBAC for the two project-scoped editions (Milepost, Blueprint), and real OpenStreetMap data seeded into each edition's flagship surface (air-airtraffic / dot-executive / aec-portfolio — see §9.6). Live operational data + connectors (mirroring the Cartos Grid path in §8.1) are the next increment.

What it is: three more vertical editions of the Cartos engine — the same "one shared component + a config table" pattern that built Cartos Grid, applied to three new verticals in one pass:

All three ship from one config file, cartos-web/src/modules/industry/modules.ts — TOWER_MODULES, MILEPOST_MODULES, and BLUEPRINT_MODULES (each a Record<string, IndustryModuleConfig> keyed by module id), merged into INDUSTRY_MODULES for route generation + lookup. Each IndustryModuleConfig carries an id (also the route slug + catalog/DB module_id — the air- / dot- / aec- prefixes are retained even though the edition brand is Tower/Milepost/Blueprint), a label, a department HUD badge, a one-line blurb, a map center/zoom, a panels list, 2–4 useCases bullets, sample kpis, and an optional scope: "portfolio" | "project" (unset = flat, as on every Tower module).

The module lineup (from modules.ts — do not hand-maintain elsewhere)

Cartos Tower (Airport) — ten airfield/landside departments, DFW-anchored: Tarmac Lighting (air-lighting), Surface Condition (air-surface), Lane Striping (air-striping), Signage (air-signage), Property Lease (air-lease), Major Projects (air-projects), Emergency Services (air-emergency, ARFF/SMS), Vehicle Traffic (air-vehicle, landside/ramp), Air Traffic (air-airtraffic, airside ops), Weather (air-weather). Flat — no portfolio/project split; every module is its own independent surface.

Cartos Milepost (Transportation/DOT) — an Executive Overview portfolio tab + nine project surfaces, Indiana-anchored: Executive Overview (dot-executive, portfolio — every DOT project on one map, status/health/cost/schedule roll-up by district), then project-scoped: Pavement Management (dot-pavement), Facility Management (dot-facility), Lane Striping (dot-striping), Live Traffic (dot-traffic), Current Roadwork & Obstructions (dot-roadwork), Major Projects (dot-projects), Crew Status (dot-crew), Snow Removal & Treatment (dot-snow), Emergency Response (dot-emergency).

Cartos Blueprint (Infrastructure PM/AEC) — a Portfolio View + eight project surfaces, Las Vegas-anchored: Portfolio View (aec-portfolio, portfolio — every capital project's status/health + assignable view rights), then project-scoped: Design Status (aec-design), Site Selection (aec-site), Constructability Review (aec-constructability), Environmental & Cultural (aec-environmental), Construction Inspections (aec-inspection), Safety Report (aec-safety, HSE), Stakeholder Management & Access (aec-stakeholder), Live Traffic (aec-traffic, construction/haul routes).

Full per-module tables (id / label / department, plus scope for Milepost and Blueprint) are in §7.4.

The IndustryModule surface (cartos-web/src/modules/industry/IndustryModule.tsx)

A lean cousin of GridModule — one shared, config-driven component renders every department in all three editions. Adding a department is a new entry in modules.ts, not a new component. Per instance it renders:

• A themed MapLibre map (default basemap holographic-theme, so it tracks the active platform theme) + a HUD header showing the module's department badge, label, and blurb.
• The engine's portable overlays, each capability-gated per module (<module-id>/<feature>): Analyst (AnalysisOverlay), Compare (CompareOverlay), Map Export (MapExportOverlay), and the Layer Catalog (CatalogLayersOverlay) — plus a Basemap switcher panel.
• A per-module KPI dashboard (IndustryDashboard, docked or full-screen via /<moduleId>/dashboard — see §9.7): prepends live tiles from GET /api/catalog/kpi when the module has real catalog data, then the config's representative kpis tiles and its useCases bullets. Every industry module now renders the reusable CatalogDashboard (ECharts, attribute breakdowns, computed alerts) with IndustryDashboard as the fallback for modules without catalog data yet (mirroring Cartos Grid's own dashboard, §9.7).
• On a scope: "project" surface: a HUD Project dropdown, populated from GET /api/industry/projects?edition= — only the projects the caller has been granted (default-deny; see the RBAC model below). Selecting a project flies the map to its lon/lat/zoom. The selected project shows a status pill + health dot; a caller with edit or admin access sees an inline ✎ Edit control to change status/health via PATCH /api/industry/projects/:id (server re-checks the access level; view-only is rejected).
• On a scope: "portfolio" surface: a "⚙ Manage project access" button visible to User-Admins, opening ProjectAccessPanel in a dockable panel right on the map — the same grant-management UI as the User-Admin console tab (below).

Edition selection (cartos-web/src/lib/edition.ts)

The same Edition type used by Cartos Atlas/Grid now includes tower, milepost, and blueprint. Selection precedence: a VITE_CARTOS_EDITION build flag → a ?edition= query override (persisted in sessionStorage, so a splash link survives the SPA redirect) → the hostname (tower. / milepost. / blueprint.<domain>) → full. Each edition preset carries a brand wordmark, its modules nav lineup (the same ids listed above), a home default route, and a defaultTheme:

editionOrigin(target) derives the URL for the in-app edition switcher (dev: the target's Vite port; prod: <target>.<domain>), so the header switcher and the splash page can link straight to any edition from any other.

Industry project RBAC — per-project & portfolio-wide access grants

Cartos Milepost and Cartos Blueprint are project-scoped editions: an executive sees the whole portfolio, but individual departments/agencies/teams (or specific users) should only see the projects relevant to them. This is the same group concept as docs/group-access-design.md — extended from row-level owning_team scoping to an explicit grants table, because portfolio access needs to be assignable (an admin decision), not just inherited from a Keycloak group membership.

**Data model — crates/cartos-data/migrations/0036_industry_project_access.sql

• 0037_industry_access_levels.sql:**

Both tables carry the standard tenant_isolation RLS policy (FORCE RLS); this is the second layer — the primary boundary is the query's WHERE clause, per the fabric's convention (docs/group-access-design.md).

Access is default-deny. list_projects (crates/cartos-data/src/industry.rs) returns a project only when the caller is an admin (see_all — any of the three admin tiers), or a grant — portfolio-wide or project-specific — matches one of the caller's groups or their username. Each returned row is annotated with the caller's effective access_level: the strongest matching grant (admin > edit > view), computed in SQL via a CASE max(...) over every matching grant row.

Access levels (0037) and delegation:

API — crates/cartos-api/src/industry.rs, /api/industry/*:

edition is a closed set (milepost, blueprint — Tower carries no project-access model, since it has no portfolio/project split) validated in-handler; an unknown edition 400s rather than accepting free text.

UI — two places, one component: features/industry-access/ProjectAccessPanel.tsx lets an admin grant the entire portfolio or a single project to a group (dept/agency/team) or an individual user, pick the access level, and revoke any existing grant (split into "Portfolio-wide" and "By project" lists). It's reused in two places:

1. In-map, on the Portfolio surface (dot-executive / aec-portfolio) via the "⚙ Manage project access" button, for User-Admins.
2. User-Admin console — a new "Project Access" tab (modules/admin/ProjectAccessConfig.tsx) with an edition switch (Milepost / Blueprint), for managing the whole tenant's grants in one place without hunting through the map.

Dev seed (0036): sample projects for both editions (e.g. I-465 Reconstruction, SR-37 → I-69 Upgrade for Milepost; Terminal C Expansion, Water Reclamation Upgrade for Blueprint) plus demonstrable grants — the whole Milepost portfolio → city_planning (promoted to admin in 0037), one Milepost project → the restricted user (default-deny demo), Terminal C → maritime_ops (promoted to edit in 0037), the whole Blueprint portfolio → demo.

Deployment — dedicated subdomains

All five Cartos editions (Atlas, Grid, Tower, Milepost, Blueprint) are served by one production build behind one Caddy origin (deploy/Caddyfile.prod) — the app resolves its edition from the request hostname, so there is no per-edition build or deploy. The 2026-07-07 change added three DNS A records (tower. / milepost. / blueprint.<domain>) and three redirect URIs/web origins on the shared cartos-web Keycloak client; login always happens against the Atlas Keycloak realm and redirects back to whichever host started it. See §2 for the live URLs and

Source files: cartos-web/src/modules/industry/modules.ts (TOWER_MODULES / MILEPOST_MODULES / BLUEPRINT_MODULES / INDUSTRY_MODULES), IndustryModule.tsx, IndustryModule.css, IndustryDashboard.tsx, IndustryDashboard.css, IndustryDashboardPage.tsx · cartos-web/src/lib/edition.ts · cartos-web/src/lib/industry-projects.ts (typed API client + editionOfModule) · cartos-web/src/features/industry-access/ProjectAccessPanel.tsx + .css · cartos-web/src/modules/admin/ProjectAccessConfig.tsx · crates/cartos-data/src/industry.rs · crates/cartos-api/src/industry.rs · crates/cartos-data/migrations/0035_enable_industry_modules.sql, 0036_industry_project_access.sql, 0037_industry_access_levels.sql · crates/cartos-core/src/catalog.rs (the 29 ModuleDef entries) · deploy/Caddyfile.prod.

8.4 Cartos Africa — the One Africa edition

Status: merged to main (PR #127) and LIVE at https://africa.cartosatlas.com. Cartos Africa stands alongside the other five live editions on its own sovereign subdomain — a dedicated Caddy vhost + Let's Encrypt cert + Keycloak redirect origin (deploy/Caddyfile.prod, deploy/render-realm.py), hostname → edition detection selects it automatically like every other edition, and it's reachable directly (not only via ?edition=africa). Real data is loaded in prod across all 9 modules and symbology is applied (real-counts table below). africa-parcel now also has a real cadastral ingest — a LADM-aligned parcel + party store (migration 0086, deployed + verified on prod) fed by an Esri Parcel Fabric adapter and a generic ArcGIS FeatureServer adapter — see the parcel-fabric subsection below. The remaining honest data caveat (the flood module's raster/COG/SAR layers are license-flagged references) is still accurate — read it before demoing this edition.

What it is: a sixth Cartos edition — Cartos Africa, a standalone continental-scale Government edition for African governments, national mapping agencies (NMAs), and ministries. It provides an operational layer over a free/open national base-map substrate — the same "one shared data fabric, one agent, one shell" pattern as every other edition, scoped to a continent instead of a single national government. Driven end-to-end from a prompt package (prompts/map-africa/00-master-prompt.md + 01–09 per-module prompts + 10-prd-update.md + a normative 99-data-sources-appendix.md license-posture appendix).

The nine modules

All nine are config entries in cartos-web/src/modules/africa/modules.ts (AFRICA_MODULES: Record<string, AfricaModuleConfig>, AfricaModuleConfig is a type alias of IndustryModuleConfig — same id/label/department/blurb/ center/zoom/panels/useCases/kpis/optional scope shape as Tower/ Milepost/Blueprint). africa-command renders scope: "portfolio" (a continental view); the other eight are flat (no per-module scope split — the country scope, below, is the cross-cutting equivalent). Registered in crates/cartos-core/src/catalog.rs as nine ModuleDefs (vertical: "government") with a rich shared default feature set (analysis, compare, map-export, dashboard, catalog, satellite, stac, overture, external-overlays, buildings-3d, time-of-day, measure, draw, mapillary, point-cloud) — no new FeatureDef was introduced; Africa modules just opt into features every other edition already has. Migration 0052_enable_africa_modules.sql enables the modules + default features for the dev tenant (new catalog modules are OFF by default; mirrors 0035 for Tower/Milepost/Blueprint).

The AfricaModule surface (cartos-web/src/modules/africa/AfricaModule.tsx) rides the shared IndustryModule component without forking it — it injects edition-specific overlays through IndustryModule's new overlays render-prop ({ mapRef, mapReadyRef, mapEpoch, storageKey, moduleId }): the country-scope boundary/mask layer, the CountryScopePanel selector, and the FoundationLayersPanel, all wrapped in a <CountryScopeProvider> so every Africa module shares one country-scope state. Default theme: Desert (sand & amber dusk — the same palette Cartos Blueprint uses, since Blueprint is also defaultTheme: "desert"; each edition lives on its own subdomain (hostname detection picks the theme per-session), so both being live at once is a cosmetic palette reuse, not a UI collision).

Edition selection

cartos-web/src/lib/edition.ts's Edition type gained "africa". The preset: brand: "ONE AFRICA", home: "/africa-command", defaultTheme: "desert", dev port 5178. Same precedence as every other edition — VITE_CARTOS_EDITION build flag → ?edition= query override → hostname (africa.cartosatlas.com in prod, live). Also selectable in prod via the header edition-switcher pulldown (§9 — shipped 2026-07-18 platform-wide, replacing the old pill row).

Country-scope system — the edition's signature cross-cutting state

The one interaction unique to a continental edition: which countries (and optionally which subnational units) are in scope, filtering every module's map layers, KPIs, dashboards, and agent answers at once.

• CountryScopeContext (cartos-web/src/lib/country-scope.tsx) — a {iso3: string[], adm1?: string[]} scope, empty iso3 = whole continent. Persisted per edition origin in sessionStorage (cartos.africa.scope) so it survives the SPA catch-all redirect. toggle/setCountries/addRegion (AU-region quick-add) /toggleAdm1/clearAdm1/clear. Any country-level change resets the ADM1 drill-down (an ADM1 selection belongs to one country).
• CountryScopePanel (features/africa/CountryScopePanel.tsx) — an always-visible 🌍 HUD chip (label shows flags for ≤3 countries, else a count, else "All Africa") that opens a DockablePanel: a search box, five AU-region quick-group buttons (North/West/Central/East/Southern — lib/africa-countries.ts's AU_REGIONS), a scrollable country list with flags + checkmarks, and — when exactly one country is selected — a sub-national drill-down listing that country's ADM1 units (fetched via lib/africa-adm1.ts's fetchAdm1/adm1UnitsFor) as toggleable chips.
• The reference data: lib/africa-countries.ts is the canonical all 54 African Union member states (ISO3, name, flag emoji, AU region, ~2024 population in millions, a centroid) — the source of truth for the selector, independent of the loaded boundary geometry. The boundary geometry itself is geoBoundaries (CC-BY 4.0, explicitly not GADM per the license appendix): ADM0 (all 54 countries, data/catalog/africa_adm0.geojson) and a priority-country ADM1 set (147 subnational units across Kenya, Nigeria, Egypt, Ghana, Ethiopia, and South Africa — the countries with the richest loaded use-case data — data/catalog/africa_adm1_priority.geojson), built by tools/build_africa_countries.py / tools/build_africa_adm1.py and loaded into the catalog under africa-command (layer keys adm0_countries / adm1_priority) via tools/load_demo_catalog.sh's --tag-country and --tag-adm1 mechanism (below).
• Rendering: features/africa/AfricaScopeLayer.tsx (afr- prefixed sources/layers) draws the country boundary outline, a selection highlight, and a mask that dims out-of-scope territory, re-adding on style.load (mig 0053/0057 hide the raw ADM0/ADM1 catalog layers from the generic Catalog panel's auto-render so AfricaScopeLayer is the only thing drawing them, and the Foundation panel's rasters insert below the mask so selection stays legible).
• Server-side propagation: the scope isn't just a client-side map filter. GET /api/catalog/layers/:id/features gained optional country_iso3/adm1 query params, and GET /api/catalog/kpi gained countries/adm1 — both parsed by new parse_iso3/parse_csv helpers in crates/cartos-api/src/catalog.rs and threaded into cartos-data's list_layer_features/module_kpi, so a country selection also narrows the KPI numbers and the dashboard charts, not just what's drawn on the map. crates/cartos-cli/src/loader.rs's load-geojson gained the tagging flags: --tag-country point-in-polygons every loaded feature against ADM0 to stamp an iso3 property, --tag-adm1 does the same against the priority ADM1 set — this is what makes the countries/adm1 filters (client and server) actually work on the loaded use-case data.
• The agent: the africa_scope tool (§7) resolves free-form country/region input to the canonical scope_iso3, which feeds query_catalog_layer's new countries argument (§9.6).

The foundation-layer fabric

FoundationLayersPanel (features/africa/FoundationLayersPanel.tsx) is the continental imagery/terrain/land-cover/boundary substrate every module rides on — a 🗺️ HUD chip opening a DockablePanel grouped by category (Imagery/Terrain/Land Cover/Buildings & 3D/Transport/Boundaries/Population), driven by a typed registry (lib/africa-data-catalog.ts's FOUNDATION_LAYERS). Each entry carries a license badge — open / view-only / open·nc / licensed / derived — and a mechanism: xyz/wms entries render live (the afr-fnd- raster reconciler adds/removes a MapLibre raster source+layer below the country-scope mask, per-layer opacity slider, prefs persisted in localStorage); reference entries (Overture Buildings, Google Open Buildings 2.5D, Overture Transportation, WorldPop population, Vantor/Maxar premium imagery) are documented upgrades, not rendered here — they'd need a server-side proxy (never a client-keyed premium source). The same renderable subset is also seeded into the standard Layer Catalog as africa-command datasources/map-layers (migration 0054, visibility off by default) so it's admin-configurable and agent-queryable like any other catalog layer, in addition to living in this dedicated panel. Normative license posture (prompts/map-africa/99-data-sources-appendix.md): geoBoundaries, not GADM; GLO-30 DSM is the default terrain story, not FABDEM (FABDEM is non-commercial; a licensed FABDEM+ is offered only as a reference upgrade); Esri imagery is view-only under Esri's ToS; commercial sources are never client-keyed — always a server-proxied datasource.

The Continental Command dashboard

features/africa/AfricaCommandDashboard.tsx — the bespoke dashboard body for africa-command (routed via AfricaDashboardPage.tsx, which gives the eight use-case modules the standard CatalogDashboard instead, same fallback pattern as Tower/Milepost/Blueprint — §9.7). Reads the same cartos.africa.scope sessionStorage key the map/panel write, so the command view reflects whatever the operator has focused on (falls back to the whole continent). Rolls up:

• Initiative KPIs — countries onboarded (of 54), foundation layers live, population covered, SDI-harmonized percentage (representative tiles, not yet bound to a real onboarding-tracking table).
• A country-onboarding board — per-country rows (flag, name, region, population) cross-referenced against countriesWithAdm1 (does this country have a loaded subnational fabric) and live per-country counts pulled from the real catalog data (health facilities via countByIso3 over the africa-health layer's iso3 property, ports via the africa-port layer).
• Cross-module roll-up charts (ECharts, reusing CatalogDashboard's chart theme system) — real GET /api/catalog/kpi feature/layer counts for each of the eight use-case modules, scoped by the current country selection via the new countries/adm1 KPI params above.

The parcel fabric — cadastral ingest (mig 0086)

Status: merged to main and deployed + verified on prod (migration 0086 applied; live-ingest tested end-to-end against a real public Esri parcel service).

africa-parcel went from a Natural-Earth built-up-extent reference (below) to a real, source-agnostic, LADM-aligned (ISO 19152) parcel + party store — both a real Esri Parcel Fabric and a generic ArcGIS parcel/cadastre FeatureServer map INTO it, so an operator can "go back and forth" between sources on one schema.

• The store (africa_parcels + africa_parcel_parties, migration crates/cartos-data/migrations/0086_africa_parcels.sql) — africa_parcels ≈ LADM LA_SpatialUnit + LA_BAUnit (the parcel + its administrative attributes) + an LA_RRR tenure_type (freehold/leasehold/customary/ public/informal/unknown); africa_parcel_parties ≈ LA_Party (owner/ occupant/lessee/customary-holder/administrator) linked to a parcel. A fabric record's lineage (CreatedByRecord/RetiredByRecord) collapses into record_name/record_type/recorded_date plus a status lifecycle (candidate | active | historic | rejected — RetiredByRecord set ⇒ historic, IsSeed ⇒ candidate). Geometry is GeoJSON JSONB + a centroid clon/clat bbox-filter pair, per the platform convention; rows are tenant + owning_team scoped. Ingest is idempotent on (tenant_id, source, external_id) — a re-sync upserts geometry/attributes in place but a CASE WHEN reviewed_at IS NOT NULL guard preserves any human review of status/tenure_type/use_class across re-ingest. (Distinct from Cartos Harvest's field_parcels — crop-field polygons for the agriculture edition, a different table entirely; see §8.7.)
• Two ingest adapters, one store (crates/cartos-api/src/africa_parcel.rs, POST /api/africa/parcels/ingest, tech_admin-gated) — fetch mirrors the ArcGIS REST pattern already used by connectors/esri_un.rs (/query?f=geojson, an optional server-held token, CORS handled server-side so the browser never talks to ArcGIS directly):
  • parcel_fabric — the resolved FieldMap defaults match Esri's documented Parcel Fabric information model: GlobalID (external id), Name (parcel ref + label), Type, StatedArea/StatedAreaUnit, CalculatedArea, CreatedByRecord/RecordType/RecordedDate, IsSeed, RetiredByRecord. Ready to point at any real ArcGIS Enterprise Parcel Fabric's Parcels/Records feature layers.
  • featureserver — a config-driven field_map for any generic ArcGIS parcel/cadastre FeatureServer (an NMA's own cadastre feed, for example); defaults are tuned to Esri's public Tax_Parcels LRM sample schema (OBJECTID/PAN/PARCEL_POLY_NAME/PARCEL_TYPE/PARCEL_BLOCK/ PARCEL_LOT/PARCEL_SUB/LRM_GEOM_DOC_AREA/Shape__Area/LRM_GEOM_DOC/ RecordDate), every field name overridable per-call.
  • Every ingested feature also gets a best-effort infer_tenure() guess (substring match on the source parcel-type string against lease/customary/freehold/public/informal) when no explicit tenure field is mapped — anything unrecognized stays unknown for a human reviewer.
• Routes (crates/cartos-api/src/main.rs) — POST /api/africa/parcels/ingest (pull a service into the store, tech_admin); GET /api/africa/parcels (list, scope + bbox/status/iso3/source_kind filters); GET /api/africa/parcels/summary?by= (group-by rollup on status|tenure_type|source_kind|use_class); GET /api/africa/parcels/:id (one parcel + its parties); PATCH /api/africa/parcels/:id (human review — status/tenure/use-class, stamps reviewer+reviewed_at); GET /api/africa/parcels/export — the LADM-shaped GeoJSON tenure export (LA_SpatialUnit/LA_RRR-named properties: su_id, upi, rrr_tenure_type, su_lifecycle, …) for GeoPackage/Shapefile conversion downstream — the "LADM-aligned tenure export" use case, now real.
• Web (features/africa/ParcelFabricPanel.tsx, lib/africa-parcel.ts, mounted in AfricaModule.tsx on africa-parcel only) — a 🧾 draggable chip opening a panel: a tech_admin-only ingest form (mode toggle Esri Parcel Fabric / ArcGIS parcel service, service URL, token, ISO3 tag), "Load parcels in view" (bbox-scoped fetch → map fill/line overlay, afr-parcel- prefixed), colour-by Tenure or Lifecycle, click-to-open a parcel's detail + review form (tenure/use/status dropdowns, linked parties), and an Export LADM button that downloads the GeoJSON tenure package.
• Honesty (read before demoing): no public live Esri ParcelFabricServer exists — a real fabric is an ArcGIS Enterprise deployment, typically secured — so the parcel_fabric adapter is real code mapped against Esri's documented fabric schema and is ready to point at a real Enterprise fabric the moment a customer has one; it hasn't been exercised against a live fabric instance. The working live demo runs on the featureserver adapter — verified end-to-end on prod against a real public Esri Tax_Parcels service (8 parcels ingested → summary → LADM export, then cleaned up). Both adapters land in the identical LADM store, so switching a tenant from the demo path to a real Enterprise fabric later is a configuration change, not a rebuild.
• Now a saved connector, not just an ad-hoc call (migration 0088_africa_parcel_integrations.sql, shipped + deployed 2026-07-29). The ingest above is a one-shot POST with the service URL and token in the request body — fine for a demo, wrong for an operational feed. It is now also registered in the Admin → Integrations tab (see §7.4) as a credentialed, re-syncable connector on the existing RealConnector seam — the same registry that backs Cartos Grid's systems-of-record, and its only other consumer, so there is no Grid-dashboard leakage. Migration 0088 relaxes the grid_integrations.kind CHECK to admit parcel_fabric and featureserver and seeds both for the dev tenant as configured · pending endpoint. The ingest core was extracted to run_parcel_ingest(pool, tenant, owning_team, body) in africa_parcel.rs, shared by the ad-hoc handler and connectors/parcel_fabric.rs, which deserializes the stored config (service_url + token held server-side, plus iso3/where/max/ field_map/source) and runs it; the connector kind selects the ingest mode. grid.rs returns a graceful "set service_url first" for an unconfigured cadastre connector rather than failing opaquely. Net effect: an NMA's cadastre becomes a scheduled, re-syncable feed whose credentials never reach the browser, and the idempotent-upsert + human-review-preservation guarantees above hold across every re-sync.

Real data — what's actually loaded, and the honest caveats

tools/load_demo_catalog.sh's One Africa section (loads after the Tower/Milepost/Blueprint sections) tags every feature against ADM0/ADM1 as it loads (--tag-country --tag-adm1), so country-scope filtering works on all of it. Symbology (categorical/graduated colour, sized markers, legends) is applied by migrations 0055/0056/0059 (health/port point styling — 0059 fixes a malformed SizeSpec in 0055/0056 that silently broke marker rendering) and 0060 (the five remaining use-case layers). Real, verifiable feature counts as loaded on dev:

Two things this table is deliberately honest about, so nobody mistakes a demo slice for a finished capability:

1. The builtup_reference row above is a background layer, not the parcel fabric. It's Natural Earth's urban-area polygons, loaded once as a backdrop showing where a parcel fabric roughly sits — it was never meant to be one, and it isn't touched by the real ingest below. africa-parcel now has a separate, real cadastral pipeline: the parcel-fabric subsection above — a LADM-aligned parcel + party store fed by either a real Esri Parcel Fabric or a generic ArcGIS cadastre FeatureServer (migration 0086, deployed + verified on prod). That covers the ingest half of the fabric — an existing authoritative cadastre flowing in. The other half — the SAM2 segmentation pipeline that generates parcel candidates from imagery (prompts/map-africa/07-parcel-fabric-development.md) — is still not built; it remains the module's roadmap item for countries without a digitized cadastre to ingest from.
2. africa-flood's raster/COG/SAR layers are license-flagged references, not rendered rasters. Migration 0058 seeds two renderable base rasters (Esri World Ocean Base, GLO-30 DSM hillshade — both visibility: off until toggled) plus four reference: true COG placeholders — Digital Earth Africa surface-water (WOfS), Copernicus GloFAS flood hazard, FABDEM+ bare- earth DTM (licensed), and Sentinel-1 SAR (flood-extent mapping) — each correctly attributed and captioned as needing the catalog's COG render path (§9.5) or a licensed/authenticated feed before they can render. Only the rivers/lakes vectors are live today.

Real geographies are pre-fetched for the countries listed above because the public Overpass API was unreachable for an extended stretch during the build (noted in CLAUDE.md); acquired datasets are committed under data/catalog/africa_*.geojson for provenance and reproducible reload, same convention as the other six editions' OSM data (§9.6).

Known gotchas (for the next session that touches this edition)

• Symbology migrations (0055/0056/0059/0060) must run after the loader on a fresh deploy — migrate alone no-ops the UPDATE map_layers statements if the rows the loader creates don't exist yet.
• Natural Earth's populated_places_simple layer uses lowercase property keys — a schema trap the settlements loader had to account for.
• sqlx embeds migrations at compile time — a new migration file needs crates/cartos-data/src/lib.rs touched + cartos-cli rebuilt before migrate will pick it up (same gotcha noted for the Grid connectors work).

What's next

The SAM2 segmentation pipeline that generates africa-parcel candidates from imagery (the ingest side — an existing cadastre flowing in — is now built, above); pointing the parcel_fabric adapter at a real ArcGIS Enterprise fabric once a customer has one (it's been verified end-to-end only against the documented schema replayed through a public FeatureServer, not against a live ParcelFabricServer); wiring the foundation panel's reference-only COG/SAR layers to the catalog's COG render path; deeper per-country data beyond the six priority countries (tracked separately, see memory/africa_deeper_country_data_tbd.md); a real country-onboarding tracking table behind the Continental Command KPIs (today representative tiles).

Source files: cartos-web/src/modules/africa/modules.ts, AfricaModule.tsx, AfricaDashboardPage.tsx · cartos-web/src/lib/edition.ts · cartos-web/src/lib/country-scope.tsx, africa-countries.ts, africa-adm1.ts, africa-data-catalog.ts · cartos-web/src/features/africa/AfricaScopeLayer.tsx, CountryScopePanel.tsx, FoundationLayersPanel.tsx, AfricaCommandDashboard.tsx, ParcelFabricPanel.tsx (+ their .css) · cartos-web/src/lib/africa-parcel.ts · crates/cartos-agent/src/builtin/africa_scope.rs · crates/cartos-agent/src/builtin/query_catalog_layer.rs (countries arg) · crates/cartos-data/src/africa_parcel.rs · crates/cartos-api/src/africa_parcel.rs · crates/cartos-data/migrations/0086_africa_parcels.sql · crates/cartos-api/src/catalog.rs (parse_iso3/parse_csv, KPI/features query params) · crates/cartos-data/src/catalog.rs (africa_countries, AfricaCountryRow, FeatureQuery.countries) · crates/cartos-cli/src/loader.rs (--tag-country/--tag-adm1) · crates/cartos-core/src/catalog.rs (the nine ModuleDef entries) · crates/cartos-data/migrations/0052–0061 · tools/build_africa_countries.py, build_africa_adm1.py · tools/load_demo_catalog.sh (One Africa section) · data/catalog/africa_*.geojson · prompts/map-africa/00–10, 99-data-sources-appendix.md · deploy/Caddyfile.prod (africa. vhost) · deploy/render-realm.py (Keycloak redirect/web-origin for the africa host).

8.5 Cartos Guardian — Critical-Infrastructure Protection

Status: merged to main (PR #133/#134) and LIVE at https://guardian.cartosatlas.com (2026-07-22). Documented here for the first time in this guide (it shipped between the 2026-07-18 and 2026-07-26 refreshes). Deployed the same way as every other edition — its own Caddy vhost + Let's Encrypt cert + Keycloak redirect origin, hostname-detected.

What it is: a seventh Cartos edition — Cartos Guardian — for identifying and protecting UAE civil infrastructure that could be a strike target, with a transparent per-site strike-risk score. Raised 2026-07-22 in response to the UAE infrastructure-strike threat context; covers all UAE, with the immediate view concentrated on the Strait of Hormuz (~56.0°E, 26.0°N). A pure IndustryModule clone (the One Africa pattern — GuardianModule wraps IndustryModule and injects the risk panel through the overlays render-prop; modules live in cartos-web/src/modules/industry/modules.ts). Guardian is the proactive half of a pair with Cartos Sentry (§8.6) — Guardian scores what could be hit, Sentry watches whether it has been.

The five modules

Home /guard-command. Default theme Red (Crimson · tactical). Camera centre [56.0, 26.0] zoom 6.6 (the Hormuz view). Every module carries the same rich default feature set: mobility, Overture, External Data Sources, Mapillary, satellite, STAC (the SAR/Sentinel-1 path), plus analysis / compare / map-export / dashboard / catalog / buildings-3d / time-of-day / measure / draw / point-cloud — 16 features, no new FeatureDef needed. Registered in crates/cartos-core/src/catalog.rs as five ModuleDefs (vertical: "critical-infrastructure"); migration 0069 enables the modules

• features for the dev tenant.

The strike-risk model — the differentiator

Every site carries a transparent 0–100 strike-risk score, computed once offline and baked into the GeoJSON so map, popups, panel, and the agent tool all read the same number (no live re-scoring):

risk = 100 · (0.45 · criticalityN + 0.30 · hormuzExposure + 0.25 · categoryWeight)

hormuzExposure is a haversine proximity to the strait chokepoint (56.45°E, 26.55°N; decays to 0 at 550 km), +0.12 if the site ships via the strait. Tiers: Critical ≥80 / High ≥65 / Elevated ≥50 / Moderate ≥35 / Low. Computed in tools/build_guardian_infra.py; the Fujairah cluster tops the UAE ranking (oil terminal, naval base, power/desal, the ADCOP pipeline terminus — the closest strategic node to Hormuz on the Gulf-of-Oman side). features/guardian/GuardianRiskPanel.tsx (a floating "⚠ Strike Risk" surface) shows a threat summary, a tier bar, ranked Top Targets (click → fly-to + pin), a per-site factor breakdown, and a model explainer; migration 0071 recolours the Command COP layer by risk_tier (crimson→green threat map, radius scaled by risk_score). GuardianRiskKpis (features/guardian/) replaces the placeholder "—" dashboard tiles on every guard-* module (both the in-map dashboard and the full-screen /guard-*/dashboard) with live headline tiles (assessed / Critical / High≥65 / mean / peak / strait-exposed ≤200 km) + a tier bar + a top-6 targets table.

Real data — what's actually loaded

103 curated UAE critical-infrastructure sites across the five modules, each with criticality (1–5), category/subtype/operator/emirate/ hormuz_shipping attributes — curated, not exhaustive Overpass (for critical infrastructure the known strategic targets beat a bulk OSM pull). Layer breakdown: guard-energy/energy_petroleum (22 — power plants + petroleum ports + 3 pipelines), guard-utilities/utilities_transport (15), guard-emergency/emergency_services (11), guard-defense/military_sites (5), guard-command/critical_sites (50, the union COP). Symbology (categorical colour + feature-type glyphs — bolt/flame/droplet/triangle/med-cross/alert — radius graduated by criticality) via migration 0070.

A deeper-data build (also merged + live) added five more capabilities, all license-verified (a Fable-model source deep-dive; OSM data joins on our own osm_id, so ODbL share-alike never touches the produced map):

1. Grid vulnerability — guard-energy/grid_network (migration 0072): 1,309 OSM substations + 1,342 HV transmission lines, voltage-weighted risk — 2,651 features.
2. Strategic vector layers (migration 0073): generation_plants (131 OSM power=plant), bridges_tunnels (827), government_sites (988 — government buildings + embassies/diplomatic missions).
3. POI collateral — guard-command/poi_risk (2,500 soft-targets within 5 km of a critical site, scored sensitivity × proximity × target-risk, including 1,030 fuel/chemical storage tanks as a secondary-hazard layer) — drives a dedicated "POI Risk" tab in the Strike-Risk panel.
4. Historical imagery overlay (GuardianImageryOverlay) — a NASA GIBS time-slider: MODIS TrueColor + Fire/Burn (dated) and VIIRS Black Marble night-lights (static — a power-outage read).
5. Live traffic overlay (GuardianLiveOverlay) — reuses the existing /api/mobility/vessels (AIS) and /api/mobility/aircraft (ADS-B) feeds, same-origin, no new key or infra; tankers highlighted.

The agent tool

guardian_strike_risk (crates/cartos-agent/src/builtin/, cross-module, edition-wide like africa_scope) ranks the UAE inventory by the risk model — filters on category/min_tier/min_score/within_hormuz_km/ shipping_only/limit — and returns matched_count + tier_distribution + ranked targets. Backed by cartos_data::catalog::guardian_targets (reads the guard-command/critical_sites union, scope-gated, ranked by risk_score).

Known gotchas

• Prod data isn't shipped by ship-deploy.sh (SHIP_PATHS covers crates/cartos-web/deploy/config/Cargo*, not data//tools/) — a fresh deploy needs the guard_*.geojson files scp'd + docker cp'd into the API container, then cartos-cli load-geojson run in-container, then the symbology migrations (0070/0071) re-applied via psql — migrate before load, same trap as every other edition's loader-vs-migration sequencing.
• Prod RUST_LOG=cartos_api=info suppresses cartos-cli load logs — a successful load prints nothing and exits 0; don't grep for a "complete" string under set -e.
• Overpass area queries time out; bbox + out geom/out center with a descriptive User-Agent works (a 406 without one) — used for the grid/ strategic-vector pulls in tools/build_guardian_{grid,extra}.py.
• Keycloak redirect URIs for a new subdomain must be added live via kcadm (docker exec deploy-keycloak-1 → kcadm.sh -s "redirectUris+=...") — Keycloak's --import-realm skips existing realms, so re-running render-realm.py alone does not update a live realm.

What's next

GEM Global Integrated Power Tracker (CC-BY, email-gated) for authoritative plant data; a Sentinel-2 titiler for 10 m historical imagery; Overture Places POI enrichment; SAR/Sentinel-1 change-monitoring via STAC — this is exactly what Cartos Sentry now does, watching Guardian's highest-risk sites (see §8.6); an aisstream/ADS-B- Exchange procurement upgrade for contract-grade live traffic feeds.

Source files: cartos-web/src/modules/industry/modules.ts (GUARDIAN_MODULES) · cartos-web/src/modules/guardian/GuardianModule.tsx · cartos-web/src/features/guardian/ (GuardianRiskPanel.tsx, GuardianRiskKpis.tsx, GuardianImageryOverlay.tsx, GuardianLiveOverlay.tsx) · cartos-web/src/lib/guardian-risk.ts · crates/cartos-agent/src/builtin/guardian_strike_risk.rs · crates/cartos-data/src/catalog.rs (guardian_targets) · crates/cartos-core/src/catalog.rs (five guard-* ModuleDefs) · crates/cartos-data/migrations/0069–0074 · tools/build_guardian_infra.py, build_guardian_grid.py, build_guardian_extra.py · tools/load_demo_catalog.sh (guardian section) · data/catalog/guard_*.geojson · guardian-PRD/ (PRD + Capability Brief, build.py → HTML/PDF/DOCX) · deploy/Caddyfile.prod (guardian. vhost) · deploy/render-realm.py (Keycloak redirect/web-origin for the guardian host).

8.6 Cartos Sentry — Reactive Crisis Monitoring

Status: merged to main and LIVE at https://sentry.cartosatlas.com (2026-07-23, still actively shipping features through 2026-07-26 — every item below is browser-verified live). Own sovereign subdomain, same pattern as every other edition (Caddy vhost + Let's Encrypt cert + Keycloak redirect origin, hostname-detected).

What it is: an eighth Cartos edition — Cartos Sentry — the reactive counterpart to Cartos Guardian (§8.5). Guardian scores what could be hit; Sentry watches whether it has been. Optical + SAR + thermal satellite change detection for critical-infrastructure crisis monitoring: watch Guardian's highest-risk assets → autonomously detect an event (fire / structural damage / flood / blast / spill) → open a scored incident with cross-modality confidence and before/after evidence → report + alert. Raised 2026-07-23 from an SSP concept mockup; PRD scaffolded in sentry-PRD/ (mirrors the Guardian/Cartos Atlas PRD pipeline — build_sentry.py → internal/public × md/html/pdf/docx). ~60% of Sentry reuses shipped Cartos (the Phase-2 change-detection pipeline — job queue, model sidecar, derived datasets — STAC incl. sentinel-1-rtc SAR, the Compare swipe tool, reports, the asset catalog, the IndustryModule shell, measure/draw/annotate/ export/dashboard); four things are genuinely new and described below: (1) a monitoring daemon — the platform's first background ingestion loop, (2) real model-free detectors, (3) an incident state machine + alert dispatch — the platform's first outbound alert channel, (4) commercial tasking connectors.

Ethos: no fake certainty. Every honest limit below is intentional, not an oversight — Sentry ships confidence bands, not invented percentages, and a degraded model never fabricates an incident (the "mock guard," below).

The three modules

Home /sentry-command. Default theme Camo (field olive, #a3b635 — flipped from an initial Ember/orange during the build per Steven's direction; brand chrome, the AOI-draw tool, and the watchlist/control accents all swept olive; the P1/P2/P3 priority ramp stayed semantic red/amber/grey). Registered in crates/cartos-core/src/catalog.rs as three ModuleDefs (vertical: "crisis-monitoring"); migration 0075 enables the modules for the dev tenant.

1 · The monitoring watchlist + daemon

The daemon's source of truth is an editable monitoring watchlist (sentry_watchlist, migration 0076) — name / asset_key / category / lon / lat / priority (P1/P2/P3) / risk_score / interval_hours / modalities (optical/SAR/thermal) / enabled / owning_team. Seeded from Guardian's top-10 strike-risk sites (ORDER BY risk_score DESC LIMIT 10 against guard-command/critical_sites; priority + scan interval derive from the Guardian tier: risk ≥80 → P1/12h, ≥65 → P2/24h, else P3/72h) — this is the Guardian → Sentry handshake: a strike-risk score becomes a watch priority, which later sizes the tasking spend a P1 incident can defensibly justify. CRUD via /api/sentry/watchlist (tenant + group-scoped) and features/sentry/WatchlistPanel.tsx (inline-editable table: enabled toggle, priority, interval hours, per-modality toggles, risk, delete, click-to-fly, add-at-map-centre, and a relative-time "Scanned" column).

crates/cartos-api/src/sentry_monitor.rs — the platform's first background ingestion loop — is an opt-in tokio interval task (CARTOS_SENTRY_MONITOR=1, mirrors the AIS ingester's pattern) that on each tick finds watchlist rows due for a scan (sentry::due_for_scan, interval_hours elapsed since last_processed_at) and, per due asset+modality: STAC-searches Planetary Computer over a small AOI (crates/cartos-api/src/sentry_screen.rs, ±0.02° box, 60-day window), picks two well-separated epochs (newest = post; earlier, ≥10 days apart = pre; optical filters cloud cover ≤40%), resolves a per-epoch tilejson XYZ URL, and calls the sidecar's change.detect directly (synchronous — no job-queue polling; daemon detections don't persist a derived dataset the way an analyst-run job does). Optical routes to sentinel-2-l2a, SAR to sentinel-1-rtc; thermal is handled separately via FIRMS (below). Dedup: sentry_incident::has_open_incident skips an asset that already has an open incident. A MAX_ROWS_PER_TICK cap bounds the work per tick, and every modality fails independently and gracefully (a transient STAC network error on one source doesn't block the others).

⚠ The mock guard. Only a detection whose model_version starts s1- or s2- is trusted as real; a degraded/misconfigured sidecar that would otherwise fall back to the mock detector never raises a fabricated incident. This is the load-bearing honesty check for the whole daemon.

Tunables (prod compose): CARTOS_SENTRY_MONITOR_INTERVAL_SECS (tick period), CARTOS_SENTRY_MONITOR_SCREEN (0 = heartbeat only, no real detection), CARTOS_SENTRY_AOI_HALF_DEG (default 0.02), CARTOS_SENTRY_WINDOW_DAYS (default 60), CARTOS_SENTRY_MIN_CHANGE_PCT (default 5, tuned to 10 in prod to quiet residual coastal noise — see precision hardening below), CARTOS_SENTRY_MAX_ROWS_PER_TICK (default 6), CARTOS_SENTRY_THERMAL_DAYS (1–5, FIRMS NRT's hard cap).

2 · Real model-free detectors

The sidecar's change.detect (model-sidecar/) routes on the STAC collection to two model-free, CPU detectors (numpy + Pillow, no torch — distinct from the Phase-2 SegFormer path used for uploads, below):

• S1 backscatter log-ratio (s1_change.py, model_version s1-backscatter-logratio-0.1) — Δσ⁰ dB per cell over VV polarization; ≥4 dB → new_structure/removed, ≥2 dB → modified.
• S2 NBR·NDWI (s2_change.py, model_version s2-nbr-ndwi-0.1) — asks the Planetary Computer titiler to render the index expression as grayscale and recovers it linearly; dNBR > 0.15 → burn, NDWI+ΔNDWI → flood.

Plus FIRMS VIIRS active-fire (crates/cartos-api/src/firms.rs — NASA FIRMS VIIRS_SNPP_NRT 375 m near-real-time area-CSV client, header-mapped parse → GeoJSON, unit-tested). Thermal is a hotspot feed, not a two-epoch comparison — any active fire inside a watched AOI is a candidate regardless of %-change; needs CARTOS_FIRMS_MAP_KEY (degrades gracefully — "no key configured" — without one).

Multi-image baseline masking (optical_change_baseline in s2_change.py) samples a per-cell mean/σ (μ/σ z-score) across several prior epochs to suppress ordinary seasonal/tidal swings before flagging a cell as changed — the false-positive-suppression backbone the precision hardening below builds on. ⚠ GET /healthz still advertises mock-change-0.1 (a static registry string) — the mock only actually fires when neither S1 nor S2 is selected for the collection in play.

3 · Incident state machine + alerts

The reactive core. Migration 0078: sentry_incident + sentry_incident_event (audit timeline) + sentry_alert_channel (webhook config) + sentry_alert (dispatch log). crates/cartos-data/src/sentry_incident.rs implements a validated state machine — new → acknowledged → investigating → resolved | dismissed, with resolved/dismissed reopening back to investigating — plus derive_severity (change % + detection class + watchlist priority → critical/high/medium/low), full CRUD, timeline, channels, and record_alert. Routes (crates/cartos-api/src/sentry_incident.rs): /api/sentry/incidents (+/:id, /transition, /assign, /confirm, /note), /api/sentry/alerts, /api/sentry/alert-channels (create/delete, tech_admin, http(s)-only webhooks). Alert dispatch fires on incident open: in-app is always logged; webhook channels whose min_severity is met get the incident POSTed (non-fatal — a failed webhook is logged, not fatal to the incident). Web: features/sentry/IncidentsPanel.tsx (severity-sorted, open-first alert feed + a detail view with transition buttons, assign, notes, and the audit timeline, camo-accented) on sentry-incidents and sentry-command; a "Raise incident" button appears in the shared Analysis result panel when EDITION === "sentry", turning any analyst-run change.detect result (dominant class, mean confidence, AOI centroid) into an incident.

4 · Fusion confidence bands

The PRD's "no fake 87%." Incidents carry a Low / Medium / High / Confirmed band fused from independent cross-modality corroboration — optical, SAR, and thermal each fail independently, so ≥2 agreeing modalities → High; a lone detection tops out at Medium unless very strong — combined with detector strength (derive_confidence_band, unit-tested, cartos-data). The daemon now collects detections from every configured modality per screen, not just the first hit, storing per-modality detection.evidence alongside the fused band. "Confirmed" is analyst-only (POST /api/sentry/incidents/:id/confirm → sets the band + writes a timeline event). Migration 0079 (confidence_band column). UI: a band chip + a confidence block (per-modality evidence bars + the Confirm button) on the incident detail.

5 · Incident Ops View — the canvas compositor

From an incident, a 🛰 Ops View renders pre/post satellite scenes over the AOI in a canvas compositor (features/sentry/OpsViewPanel.tsx + ImageCompare.tsx) with tabs Optical (O) / SAR (S) / Thermal (T) / Δ Change / 🏚 Damage / ⌆ Coherence. Four compare modes over static AOI crops (the Planetary Computer titiler's item/bbox/{minx,miny,maxx,maxy}.png, CORS * so canvas getImageData works): Swipe (draggable divider), Side-by- side, Overlay (per-side colourise natural/grey/red/blue/green + independent opacity), and Change (per-pixel composite — grey=unchanged, red=appeared/post-brighter, blue=removed/pre-brighter, with a sensitivity control). GET /api/sentry/incidents/:id/imagery?modality= resolves the epoch pair on demand (sentry_screen::resolve_view, reusing the same STAC+tilejson machinery as the daemon); the AOI comes from the incident's stored detection.imagery.bbox (daemon incidents) or the incident point. The Thermal tab resolves a Landsat surface-temperature pair (landsat-c2-l2 lwir11, inferno colormap, 120-day window) through the same compositor, plus FIRMS hotspots as a map overlay with a count and a last-1/3/7/10-day selector (⚠ over a small ±0.02° AOI, Landsat's 100 m thermal resolution reads coarse — a wider AOI resolves more detail).

6 · Commercial tasking connectors

The crisis-hour escalation surface — open imagery is 24–72h latency, so an incident that needs a fresh, higher-resolution look now tasks a commercial vendor over the AOI; the Guardian strike-risk → priority handshake is what makes the spend defensible (a P1 asset justifies a priority order). Migration 0080 (sentry_tasking_order) + crates/cartos-data/src/sentry_tasking.rs + crates/cartos-api/src/sentry_tasking.rs:

Web features/sentry/TaskingPanel.tsx (AOI from the viewport or an incident, P1/P2/P3 selector, reactive vendor cost cards, an open-archive search with thumbnails, and the order log) on sentry-command/sentry-detect/ sentry-incidents; a "🛰 Task imagery" button on the incident detail hands over the AOI + severity-derived priority. Honest by design: the credentialed vendors (Capella/ICEYE/Maxar/Planet) are reported as "requires vendor API credentials," never fabricated; an order records intent, it does not fly a collect; cost figures are illustrative anchors, consistent with the cartos-pricing convention. Umbra's open archive is a deep year → month → day → item tree with no spatial extent on interior nodes, so the crawl uses a recency-first depth-first search (date-sorted, newest-first, a 90-fetch/ 12-second budget) plus a live proof-of-life sample of the latest collects (unfiltered by AOI, clearly labelled) — the archive's ~20 sites rarely cover the Gulf demo AOIs, so the sample keeps the panel honestly "live" without pretending coverage that isn't there.

7 · InSAR coherence context layer

Done the infra-fit way, not the expensive way: not a live coherence-loss detector (that needs SLC imagery + SNAP/GPU, or an async HyP3/Earthdata connector — the documented v2 path) but a pre-computed expected-coherence context layer from the open Global Seasonal Sentinel-1 Coherence dataset (Kellndorfer et al., AWS sentinel-1-global-coherence-earthbigdata, seasonal 2019–2020 median, 3 arcsec). Sidecar POST /render/coherence crops the global VRT over the AOI via GDAL /vsicurl + -projwin (fetches only the AOI's bytes) → mean/median/low-fraction stats + a colourised RGBA PNG (red = decorrelated, green = coherent). GET /api/sentry/incidents/:id/coherence picks the season from the AOI's hemisphere + month and adds a High/Moderate/ Low interpretation. The ⌆ Coherence Ops-View tab drapes the PNG over Esri. It qualifies the amplitude detectors — change over normally-coherent ground is more likely real; change over already-decorrelated ground is more likely noise — it is a surface-stability layer, not a live-event detector, and bridges into the precision hardening below (the principled path to a sand mask, since NBR/NDWI/NDVI genuinely can't separate bare sand from built surfaces).

8 · Thermal colour ramps + change-over-Esri

Two Ops-View refinements: (a) selectable thermal colour ramps (inferno/magma/plasma/viridis/turbo/hot/jet/rainbow) via a colormap query param on the imagery endpoint, a 🎨 Ramp selector in the T tab. (b) "⧉ Change over Esri" for SAR/optical/thermal — sidecar POST /render/change-raster derives per-pixel appeared(red)/removed(blue) rasters from a tab's pre/post AOI crops as two georeferenced RGBA PNGs; GET /api/sentry/incidents/:id/change-raster?modality= resolves the crop URLs; a toggle drapes both over the high-res Esri basemap with independent appeared/removed transparency sliders.

9 · Local + GeoTIFF/COG imagery upload → change.detect

An analyst uploads their own before/after scenes and compares them in the same compositor as the satellite Ops View. POST /api/sentry/uploads (raw body, tenant-scoped, reuses the Field media seam) for plain images (PNG/JPEG/WebP) — features/sentry/LocalImageryPanel.tsx on sentry-detect and sentry-command. Georeferenced GeoTIFF/COG uploads go through the sidecar POST /render/raster-preview (GDAL CLI: gdalinfo -json for the WGS84 extent bounds, gdal_translate -scale for a 1024 px web PNG — no Python GDAL bindings needed, CLI only) → POST /api/sentry/geo-uploads (80 MB) stores the rendered PNG + returns {url, bbox}. Uploaded imagery also feeds real SegFormer change detection (POST /render/local-change, the Phase-2 model, base64) — for a georeferenced pair the change cells (appeared=red, removed=blue) drape over Esri on the map at their real AOI and can raise a genuinely georeferenced incident. ⚠ Added a persistent media-data volume (/data/media, CARTOS_MEDIA_DIR) in prod — cartos-api previously had no media volume, so uploads (and Field media) were lost on container recreate; see memory/prod_deploy_postgres_safety.md.

10 · xBD damage assessment

Per-building 4-class damage (no-damage / minor / major / destroyed) over an incident's AOI. Honest by design: this is a change-magnitude classifier, not a trained xView2 CNN (a real xBD model needs the xBD dataset, a GPU, and sub-metre imagery; Sentinel's 10 m resolution is triage-grade, not building- grade). Sidecar POST /render/damage-assess fetches the pre/post AOI crop, samples each building footprint's change, and classifies it; GET /api/sentry/incidents/:id/damage pulls the footprints from the overture-sidecar (/overture/buildings?bbox=) and runs the assessment. The 🏚 Damage Ops-View tab colours buildings by class over Esri with per-class counts.

11 · Precision hardening — killing the two documented false-positive sources

The daemon's first prod runs autonomously raised two incidents ("Surface change · AUH" 34% and "Burn scar · Das Island" 27.8%) that were almost certainly false positives — S2 NBR/NDWI swings 25–35% between two dates over heterogeneous coastal AOIs (water + sand + built) with no real event, and Gulf gas flares light up FIRMS across nearly every energy asset. Two masks, tuned against live data:

• Persistent-water masking (s2_change.py) — cells that are open water in every epoch (baseline NDWI > 0.10) are masked; tidal/wave/sun-glint NDWI swings over standing water were the #1 coastal false positive, while a real flood rises from a dry baseline and survives the mask. Returns a water_masked count surfaced as a KPI + summary note.
• Persistent gas-flare masking (sentry_screen.rs) — FIRMS hotspots are grouped by proximity clustering (connected components at ≤3.5 km, reuniting a facility's stacks regardless of any grid-cell boundary); a cluster is a persistent flare iff it recurs on ≥3 distinct days and spans ≤10 km (a bounded footprint, not a spreading wildfire) — only non-persistent hotspots raise a thermal incident, and a ≥120 MW FRP escape lets a genuine major fire/explosion through even inside a known flare cluster (routine Gulf flares peak ~68 MW). Tuned and verified against the UAE's actual live flares — Das Island (68 hotspots/4 days), Zakum (9/4), and the multi-stack Ruwais terminal (10/3, which required the switch from a fixed grid to proximity clustering to reunite spatially-spread stacks) — all correctly suppressed, while an isolated 1-day Jebel Ali detection and synthetic spreading-wildfire/anomalous-FRP guards correctly still raise.

Prod also tuned CARTOS_SENTRY_MIN_CHANGE_PCT from 5 → 10 once baseline masking landed.

12 · Sentry operations dashboard

features/sentry/SentryDashboard.tsx (ECharts, camo-themed) — Sentry has no catalog layers, so it doesn't fall back to the generic CatalogDashboard like Tower/Milepost/Blueprint do; it's driven by the real Sentry data plane (incidents/watchlist/alerts/tasking orders): a KPI strip (open incidents + critical/high, confirmed, assets watched + enabled, P1 assets, scans overdue, alerts sent, tasking spend), an incidents-raised-over-14-days line, severity and confidence-band donuts, a status funnel, detection-modality and watchlist-priority bars, a recent-incidents table (severity/band/status/age), and an alert-dispatch log. SentryDashboardPage.tsx wraps the shared DashboardPage; routed for every sentry-* module.

13 · Incident report/export

One-click auditable record from the incident detail: 📄 Report opens a self-contained, print-ready styled HTML report (dark camo + a print media query) and DOCX ↓ downloads the same via the sidecar's /render/markdown-docx (reusing the M02 §13.2 render path). sentry_report.rs renders header, severity + confidence-band chips, detection metrics, a per-modality evidence table, KPIs, and the full audit timeline. The report embeds the actual pre/post AOI crop thumbnails (built from the incident's stored tile URL + bbox, not just dates) — HTML as <img> tags, DOCX via an extended sidecar build_markdown_docx that resolves ![alt](url) lines to add_picture. GET /api/sentry/incidents/:id/report.{html,docx} (tenant + group scoped, read-only — no migration).

HTTP API reference

Migrations 0075–0080: 0075 enables the three modules; 0076 sentry_watchlist; 0077 adds last_processed_at + sentry_scan; 0078 sentry_incident/sentry_incident_event/sentry_alert_channel/sentry_alert; 0079 confidence_band; 0080 sentry_tasking_order.

Honest limits (read before demoing this edition)

• Open imagery has a 24–72h detection latency. FIRMS active-fire is the only hours-class open feed (~30 min–3h) — and it's fire-only. Crisis-hour reactivity needs commercial tasking (§6 above); the strategic v2 headline is a sovereign SAR constellation JV — an in-house feed no open-data competitor has.
• xBD damage is triage, not a trained model (§10) — Sentinel resolution, change-magnitude classification, not xView2.
• The coherence layer is a stability baseline, not an event detector (§7).
• Sand is honestly not index-separable from built surfaces with NBR/NDWI/ NDVI alone — the coherence layer is the principled mitigation path, not yet wired as a hard gate.
• /healthz still advertises mock-change-0.1 as a registry string even though S1/S2 are the real, live-verified detectors for their collections.

Known gotchas

• CARTOS_SENTRY_MONITOR=1 (and its _SCREEN/_AOI_HALF_DEG/etc. siblings) must be in the compose environment: block, not just .env.prod — the latter only feeds interpolation, it doesn't reach the container.
• MODEL_SIDECAR_URL unset defaults to http://localhost:8300, which is unreachable from the cartos-api container itself — this silently broke both the daemon's change.detect calls and the Analysis-panel job worker until fixed to http://model-sidecar:8300 in docker-compose.prod.yml.
• FIRMS's NRT area-CSV day range is 1–5 (a 7 or 10-day request 400s) — the handler, the daemon, and the compose default all clamp to this.
• Deploying any Ops-View/sidecar feature (coherence, change-raster, raster-preview, damage-assess) needs a model-sidecar rebuild, not just cartos-api — those endpoints live in the Python image.

Source files: cartos-web/src/modules/sentry/ (SentryModule.tsx, SentryDashboardPage.tsx) · cartos-web/src/features/sentry/ (SentryControl, WatchlistPanel, IncidentsPanel, OpsViewPanel, ImageCompare, LocalImageryPanel, TaskingPanel, SentryDashboard + their .css) · cartos-web/src/lib/sentry.ts · crates/cartos-api/src/sentry.rs, sentry_monitor.rs, sentry_screen.rs, sentry_incident.rs, sentry_tasking.rs, sentry_report.rs, sentry_upload.rs, firms.rs · crates/cartos-data/src/sentry.rs, sentry_incident.rs, sentry_tasking.rs · model-sidecar/s1_change.py, s2_change.py, main.py (/render/coherence, /render/change-raster, /render/raster-preview, /render/damage-assess, /render/local-change) · crates/cartos-core/src/catalog.rs (three sentry-* ModuleDefs) · crates/cartos-data/migrations/0075–0080 · sentry-PRD/ (PRD + build_sentry.py) · deploy/Caddyfile.prod (sentry. vhost) · deploy/render-realm.py (Keycloak redirect/web-origin for the sentry host) · docker-compose.prod.yml (MODEL_SIDECAR_URL, CARTOS_SENTRY_MONITOR*, CARTOS_FIRMS_MAP_KEY, the /data/media volume).

8.7 Cartos Harvest — Agriculture Intelligence

Status: merged to main, tagged cartos-harvest-v1 (2026-07-28) — deployed 2026-07-29 and LIVE at https://harvest.cartosatlas.com. The harvest branch (scoping + Phase-0 skeleton + prompts 01–07 crop-pipeline slices + de-branding + H1–H4 depth passes) is merged, and Harvest now has its own Caddy vhost, Keycloak redirect origin and subdomain like every other edition in this guide. It is also reachable from within Cartos Africa. Every capability below is verified against real Kenya/Nigeria Sentinel-2 imagery — it can equally be run locally with ?edition=harvest (see §2). Scoping doc: docs/harvest-ai-scoping.md. Buildable prompt suite: prompts/harvest/ (mirrors prompts/map-africa/).

What it is: a ninth Cartos edition — Cartos Harvest (internally "HarvestAI") — STAC-native crop intelligence: crop type classification, crop health monitoring, yield forecasting, water-stress/drought detection, field-boundary delineation, and agri-risk/finance analytics, for ministries of agriculture, agri-insurers/lenders, and extension services. The scoping doc is explicit that this is a platform, not a map layer: "HarvestAI should be designed as a production-grade agricultural intelligence platform, not merely as a map layer or an imagery viewer." It reuses the Cartos Africa country-scope + foundation-layer fabric rather than rebuilding it (a CountryScopeProvider wraps every Harvest module; HarvestModule.tsx injects AfricaScopeLayer/CountryScopePanel/FoundationLayersPanel/ AvailableHerePanel from features/africa/ verbatim) and rides the same config-driven IndustryModule surface as every industry edition since Tower/Milepost/Blueprint. Anchor countries (Phase-0 pilot AOIs): Kenya and Nigeria — already seeded in the Africa edition's country-scope.

The seven modules

Home /harv-command. Default theme Verdant (#7cc945 — "cropland green & chlorophyll", a new palette in lib/themes.ts distinct from the tactical Emerald/the Africa Savanna gold). Module-id prefix harv- (disjoint from grid-/air-/dot-/aec-/africa-/guard-/sentry-). Map-overlay layer prefix hrv- (hrv-anom-, hrv-cls-, hrv-yield-, hrv-water-, hrv-parcel-, hrv-risk-, hrv-flags-). Registered in crates/cartos-core/src/catalog.rs as seven ModuleDefs (vertical: "agriculture", industry_of_vertical("agriculture") → "harvest"); the platform-level agriculture placeholder ModuleDef these supersede is now dead (no route — see §7.4) and the disabled "Agriculture" nav placeholder was removed from ModuleNav.tsx in favour of the seven real harv-* nav entries. Migration 0082 enables the seven modules + the platform's full default feature set (analysis, compare, map-export, dashboard, catalog, satellite, stac, overture, external-overlays, buildings-3d, time-of-day, measure, draw, mapillary, point-cloud) for the dev tenant, and grants the harvest edition via tenant_editions (the Access-tab machinery from §7.4) — no new FeatureDefs, Harvest reuses the existing capability catalog end to end.

The STAC crop pipeline — the moat

The scoping doc is normative about the engineering position: crop type is a temporal + spectral problem, not a resolution problem (classify from phenological signatures over a season, not single-date RGB); STAC/COG is the authoritative AI layer, tiles are UX only; and every output carries source + date + confidence — no fabricated certainty, the same discipline as Guardian's strike-risk score and Sentry's confidence bands. Concretely, the Rust API (crates/cartos-api/src/harvest.rs, 1,062 lines) does live STAC orchestration over Microsoft Planetary Computer's public, keyless STAC + titiler (https://planetarycomputer.microsoft.com/api/{stac,data}/v1) — sentinel-2-l2a for all seven slices below — and the model-sidecar (model-sidecar/main.py) does the numpy/GDAL compute. Seven pipeline slices, each its own /api/harvest/* handler + panel:

1. crop-index (GET /api/harvest/crop-index) — STAC-searches for the least-cloudy Sentinel-2 L2A scene over the AOI + date window and returns a keyless, CORS-enabled Planetary Computer titiler URL that band-maths a vegetation index on the fly via the expression param (no raw-COG read on our side, no client key): NDVI (B08-B04)/(B08+B04), NDRE (B08-B05)/(B08+B05) (red-edge/nitrogen), NDWI (B03-B08)/(B03+B08) (canopy/surface water), NDMI (B08-B11)/(B08+B11) (vegetation moisture). All are ratios → scale-invariant, no reflectance scaling needed. Rendered in CropTemporalPanel.tsx as a MapLibre image source with a date/index scrubber — the temporal-context view every other slice builds on.
2. crop-type (GET /api/harvest/crop-type) — fetches a season of grayscale NDVI AOI crops (single-band PNGs, rescale −1..1) and posts them to the sidecar's POST /render/crop-classify, which builds a per-pixel NDVI time series and, as of v0.2, KMeans-clusters pixels by the shape of their whole time-series (bounded 2–6 clusters, each labelled by its member pixels' mean peak-NDVI + amplitude — a step up from v0.1's flat per-pixel thresholds, since two pixels with the same peak but different seasonality now land in different clusters) into five classes (bare/built/water, sparse veg/grassland, mixed/low-vigor crop, annual cropland — the strong seasonal NDVI swing is the hallmark, dense/ perennial veg); model_version: "harvest-phenology-kmeans-0.2", with a graceful fallback to the v0.1 rule-based thresholds (model_version: "harvest-phenology-baseline-0.1") if scikit-learn is unavailable or the AOI has too few valid pixels. Both are the honest label-free baseline the scoping doc prescribes; a supervised classifier scaffold (model-sidecar/crop_classify_gpu.py + train_crop_classifier.py + requirements.gpu.txt — a Prithvi/Clay fine-tune seam, MODEL_GPU-gated) now exists but is unverified on the CPU dev box, not wired into the default handler — see "What's next". CropTypePanel.tsx renders the class PNG + a legend + per-class fraction/mean-peak-NDVI breakdown.
3. crop-health (GET /api/harvest/crop-health) — the target month's NDVI vs the same month's NDVI across up to N prior years (a real multi-year baseline, not a fixed threshold), diffed by the sidecar's POST /render/ndvi-anomaly into a diverging red(stressed)→pale→ green(vigorous) map plus stressed_frac/vigorous_frac. CropHealthPanel.tsx overlays it and adds a lightweight "flag for field visit" — drops a marker (hrv-flags-*) for ground-truthing, the honest bridge to Cartos Field.
4. crop-yield (GET /api/harvest/crop-yield) — season-mean NDVI (an established biomass proxy) relative to the prior-year mean, via POST /render/yield-proxy; uncertainty is the inter-annual coefficient of variation of the regional baseline mean (not per-pixel noise, which would blow the band up), clamped to a credible 5–35% CoV range. An optional illustrative t/ha reference per crop (Africa smallholder, FAOSTAT-order, explicitly not a quote) scales the index. YieldPanel.tsx shows the map, the area-index (expected-vs-normal %), and the uncertainty band; model_version: "harvest-yield-viproxy-0.1".
5. crop-water (GET /api/harvest/crop-water) — reuses the same index-agnostic anomaly differ against NDMI/NDWI instead of NDVI: a below-baseline moisture anomaly is the water-stress/drought signal, with a drought-severity tier derived from the dry-area fraction. WaterPanel.tsx; ET (WaPOR) and rainfall (CHIRPS) are foundation-layer reference rows, not yet wired into the score; SPI/VHI and a UAE greenhouse/CEA anchor are documented follow-ups.
6. field-candidates (POST /api/harvest/field-candidates) — the biggest departure from a pure raster render: fetches a season of NDVI crops, posts to POST /render/field-segment, which classifies the seasonal-phenology cropland mask then vectorises contiguous cropland via GDAL's gdal_polygonize into candidate field polygons (area_ha + centroid peak-NDVI), and persists them into the new field_parcels table (migration 0084) as status='candidate'. FieldBoundariesPanel.tsx shows the map + a review queue — PATCH /api/harvest/parcels/:id promotes a candidate to approved or rejected, the human-in-the-loop step that turns a label-free baseline into the authoritative parcel fabric. GET /api/harvest/parcels (+ /summary) reads the fabric back, ?bbox=-filterable.
7. portfolio-risk (GET /api/harvest/portfolio-risk) — composes three drivers from the above into a transparent 0–100 agri-risk score, explicitly modelled on Guardian's strike-risk formula:

   score = 100 · (0.45 · yield_risk + 0.35 · stress_risk + 0.20 · variability_risk)

   where yield_risk comes from the yield-proxy area-index, stress_risk from the NDVI-anomaly stressed fraction, and variability_risk from the yield-proxy's inter-annual CoV — each clamped 0–1 against a credible band. Tiers mirror Guardian's (Critical ≥80/High ≥65/Elevated ≥50/Moderate ≥35/Low). A transparent, auditable index-insurance parametric trigger fires when biomass < 80% of normal OR in-season stress > 25% of area — index_trigger.reason explains which. RiskPanel.tsx colours each field parcel by a per-parcel risk (the AOI base score modulated by that parcel's own NDVI vigor) and shows the driver breakdown + trigger status. This is portfolio risk analytics for insurers/lenders/ministries, explicitly NOT personalised financial advice (the same "no fabricated certainty" discipline as Sentry).

All seven POST/GET handlers share s2_search (STAC POST to /search), parse_bbox (rejects degenerate or >2° AOIs — a titiler/STAC cost guard), and date_window (YYYY-MM → whole month, YYYY-MM-DD → ±15 days, absent → last 45 days). Data layer: crates/cartos-data/src/harvest.rs (list_crop_calendars, season_stage, insert_field_candidates, parcel read/patch helpers) — same tenant + owning_team scoping convention as every other module.

Persisted products (M03) — the Saved Products panel

Every analytics run (crop-type, crop-health, crop-yield, crop-water, portfolio-risk) has a "Save to products" option; when ticked, the shared maybe_save helper (harvest.rs) persists the whole result body as a lineage-tracked derived_dataset row via the same M03 store every other edition's saved analyses use (§13.1 — reuses migration 0013, no new migration), naming it from the AOI centroid + target date and stamping tool_ref (crop_classify / ndvi_anomaly / yield_proxy / moisture_anomaly / portfolio_risk) and tool_version (the handler's model_version, e.g. harvest-phenology-kmeans-0.2). GET /api/harvest/products?bbox=&kind= lists them newest-first (PNG bytes stripped for the list view — see strip_png), scoped by tenant + owning_team; GET /api/harvest/products/:id returns one in full (incl. the rendered PNG). The Saved Products panel (SavedProductsPanel.tsx) browses the list with per-product headline stats (top crop-type class, mean NDVI-anomaly delta, yield-vs-normal %, drought severity, risk score/tier) and is mounted alongside the other harvest panels in HarvestModule.tsx. The harvest_products agent tool reads the identical store, so "what's the latest yield forecast we ran?" answers from what was actually saved, not a live re-run.

Crop-calendar / agro-ecological-zone model

crop_calendars (migration 0083) makes every module season-aware: country + agro-zone + crop rows carry plant_start/plant_end/peak/ harvest_start/harvest_end (months 1–12, cyclic — a window may wrap year end), a season_label (e.g. "Long rains", "Short rains"), and a source (seeded 'FAO GIEWS'). Seeded for the two Phase-0 anchors: Kenya (6 rows — long/short-rains maize, Rift Valley wheat, Mwea-scheme irrigated rice, semi-arid sorghum, highland beans) and Nigeria (6 rows — early/main-season maize, Fadama wet-season rice, Sudan-savanna sorghum, Sahel millet, perennial cassava). GET /api/harvest/crop-calendar?country=&crop= returns each row annotated with its current phenology stage (planting/vegetative/ harvest/off-season) computed from today's month — the same stage math backs both the crop_calendar agent tool and the HarvestCommandDashboard's season-aware KPI tiles and per-country stage board.

Harvest Command — the dashboard

harv-command gets a bespoke dashboard (HarvestCommandDashboard.tsx, not the generic CatalogDashboard) — food-security + crop-intelligence KPIs, a country-onboarding board, and ECharts charts, all driven live by /api/harvest/crop-calendar (reusing AfricaCommandDashboard.css's hero/ grid/board chrome for visual continuity with Continental Command). Every figure reflects the current month's phenology; crop-type/health/yield map tiles are marked pending until the STAC pipeline lands data for a given country (Phase-0 anchors only cover Kenya + Nigeria so far).

Foundation-layer catalogue

lib/harvest-data-catalog.ts follows the exact lib/africa-data-catalog.ts pattern — a typed registry rendered by the reused FoundationLayersPanel, grouped by category with license badges: Imagery (Esri World Imagery view-only, Sentinel-2 Cloudless EOX CC-BY-NC-SA — flagged open-nc/never embed, Sentinel-2 L2A + Sentinel-1 GRD SAR as STAC references), Indices (MODIS NDVI 16-day via GIBS, the derived NDVI-anomaly layer), Cropland (DE Africa Cropland Extent 10m CC-BY, ESA WorldCereal 10m CC-BY, the derived crop-type layer), Land Cover (ESA WorldCover 10m CC-BY, Esri/Impact Observatory Annual LULC view-only), Soils (iSDAsoil Africa 30m, SoilGrids 250m, both CC-BY), Water & Rainfall (FAO WaPOR v3 ET, CHIRPS rainfall — both open), Terrain (Esri World Hillshade over Copernicus GLO-30 DSM, OpenTopoMap contours), Boundaries (geoBoundaries ADM0/ADM1 — not GADM, same license posture as Africa), Population (WorldPop 100m CC-BY). The Africa edition's AvailableHerePanel ("Available Here" georeference-aware registry — see §8.4) is mounted verbatim too, so a country/zoom-narrowed candidate-source list surfaces automatically without any Harvest-specific registry work.

Farmer registry — completes harv-boundaries

farmer_registry (migration 0085) is a tenant-scoped table of farmers/ land-holders (name, national_id, phone, gender, cooperative, crops[], region, owning_team) — the PII fields (name/national-id/phone) are served only to in-scope callers, same convention as everywhere else in the platform. field_parcels.owner_ref (mig 0084) is the join that turns a delineated field polygon into an operational unit for extension, insurance, and subsidy workflows. Endpoints: GET/POST /api/harvest/farmers (list — optional q name/national-id search — and register), POST /api/harvest/parcels/:id/owner (link a parcel to a farmer, from the Field Boundaries review panel), GET /api/harvest/registry/coverage (farmer count, parcels owned, coverage %). FarmerRegistryPanel.tsx is the UI: search, register (with a crops comma-list input), and a coverage strip; it's mounted in harv-boundaries alongside FieldBoundariesPanel.tsx.

The agent tools

Five edition-wide tools (module() returns None, same pattern as africa_scope/guardian_strike_risk), all in crates/cartos-agent/src/builtin/harvest.rs:

• crop_calendar — planting/peak/harvest windows + current stage, filterable by country (ISO3)/crop substring, answers "what's the current crop season in Kenya?" / "when is maize planted in Nigeria?".
• harvest_country_profile — a per-country summary (iso3 required) of which crops are planting/growing/harvesting right now, answers "give me the agriculture picture for Kenya." Both crop_calendar and harvest_country_profile read cartos_data::harvest::list_crop_calendars and return a clean NotFound (not a crash) when crop_calendars isn't loaded for a tenant, or the queried country isn't one of the two anchors.
• parcel_fabric_summary — how many field parcels are delineated and their review-status breakdown (candidate/approved/rejected + area) plus registry coverage (farmers, parcels linked, % owned); NotFound if no parcels have been delineated yet.
• harvest_products — the persisted-product catalog (see "Persisted products" above), optional product filter (crop_classify / ndvi_anomaly / yield_proxy / moisture_anomaly / portfolio_risk) + limit; PNG bytes stripped; NotFound if nothing has been saved yet.
• farmer_lookup — search the farmer registry by name/national-id substring (or list all), returns cooperative/region/crops/linked-parcel count per match (max 25); PII, in-scope callers only.

Data & license posture

Same license-class convention as Africa (open/open-nc/view-only/ commercial), with the same two landmines flagged: geoBoundaries, never GADM (non-commercial) for boundaries; Copernicus GLO-30 DSM, never FABDEM (non-commercial) as the default terrain. Decision 2026-07-27 (locked in the scoping doc): ship Phase 0/1 fully open — Sentinel-1/2, DE Africa, WorldCereal, WaPOR, CHIRPS, WorldCover, geoBoundaries, GLO-30 — no commercial imagery licensed yet; Planet/Vantor/Airbus are a future opt-in with the server-side datasource-proxy seam (already shipped for Africa — §8.4) wired but nothing keyed. GPU: local GPU is available and targeted for the Phase-1 foundation-model classifier. A supervised-classifier scaffold now exists (model-sidecar/crop_classify_gpu.py — a Prithvi multi-temporal crop-classification fine-tune seam, MODEL_GPU-gated, defaults to a public HuggingFace checkpoint that's domain-mismatched for Africa until fine-tuned on local labels via train_crop_classifier.py + requirements.gpu.txt) but is unverified on the CPU dev box — not a shipped capability, a documented depth follow-up. The v0.2 KMeans temporal-phenology clustering (§ above) stays the graceful, label-free fallback (crop_classify_gpu.available() gates the GPU path; unset falls back to KMeans).

Relationship to Cartos Africa — africa-food

Cartos Africa already ships an africa-food module (cropland extent, crop health, soils, IPC food-security phase tracking — see §8.4). The scoping decision: Harvest owns the deep crop-ML stack; africa-food stays a light food-security teaser. Migration 0082 includes a commented-out module_industries cross-deploy block (harv-croptype/harv-health → africa) using the editions-as-first-class machinery from §7.4 — held deliberately until the crop modules carry real data beyond the two pilot countries, so an empty module doesn't show up in the Africa nav. Do it from the Access tab once ready, or uncomment the block.

Known gotchas (for the next session that touches this edition)

• Deployed 2026-07-29 — harvest.cartosatlas.com, its Caddy vhost and its Keycloak redirect origin are all live, following the deploy patterns from §§8.4–8.6. The remaining gotchas below still apply to any fresh environment.
• field-segment needs GDAL's gdal_polygonize CLI on the model-sidecar image — the sidecar shells out to it, so a Docker rebuild of model-sidecar (not just cartos-api) is required before field-boundary detection works in a deployed environment.
• The browser calls planetarycomputer.microsoft.com directly for the rendered index/class PNGs (CropTemporalPanel et al. set them as MapLibre image sources) — a production CSP needs planetarycomputer.microsoft.com in both img-src and connect-src, not just allow-listed server-side (the Rust STAC search is server-side, but the titiler PNG fetch is client-side).
• sqlx embeds migrations at compile time — crates/cartos-data/src/lib.rs needs 0082–0085 registered + cartos-cli rebuilt before migrate picks them up (the same trap every edition's migration set has hit).
• AOI size is capped at ~2° (parse_bbox) to bound STAC/titiler cost — a portfolio-wide harv-risk view over a whole country will 400; the panel needs to stay zoomed to a workable AOI, a UX gap not yet addressed.
• The GPU classifier scaffold is unverified — crop_classify_gpu.py / train_crop_classifier.py compile but have not been run against a CUDA host; don't represent Harvest as GPU-model-backed until that verification happens.

What's next

Real deploy (own subdomain, Caddy vhost, Keycloak redirect origin, migrate + data load in the sequence every other edition has learned the hard way — see the gotchas in §§8.4–8.6); verify the supervised Prithvi/Clay crop classifier scaffold on a CUDA host and fine-tune on local labels (the honest follow-up to the v0.2 KMeans phenology baseline, called out in every relevant model_version string); the UAE greenhouse/controlled-environment anchor + SPI/VHI drought indices for harv-water; per-AOI-product agent tools (today's tools are calendar/fabric/registry/products-catalog — a crop_index/crop_health agent tool over a named AOI is the natural next slice, matching query_catalog_layer's pattern); and the held Africa cross-deploy once crop coverage broadens past Kenya/Nigeria.

Source files: docs/harvest-ai-scoping.md · prompts/harvest/ (master + 7 build prompts + PRD-update + data-source appendix) · cartos-web/src/modules/harvest/ (modules.ts — HARVEST_MODULES, HarvestModule.tsx, HarvestDashboardPage.tsx) · cartos-web/src/features/harvest/ (CropCalendarPanel.tsx, CropTemporalPanel.tsx, CropTypePanel.tsx, CropHealthPanel.tsx, YieldPanel.tsx, WaterPanel.tsx, FieldBoundariesPanel.tsx, FarmerRegistryPanel.tsx, RiskPanel.tsx, SavedProductsPanel.tsx, HarvestCommandDashboard.tsx + harvest-panels.css) · cartos-web/src/lib/harvest.ts (fetch client) · cartos-web/src/lib/harvest-data-catalog.ts (foundation-layer registry) · crates/cartos-api/src/harvest.rs (17 route handlers) · crates/cartos-data/src/harvest.rs · crates/cartos-agent/src/builtin/harvest.rs (CropCalendar, HarvestCountryProfile, ParcelFabricSummary, HarvestProducts, FarmerLookup) · crates/cartos-core/src/catalog.rs (seven harv-* ModuleDefs, harvest IndustryDef) · crates/cartos-data/migrations/0082–0085 · model-sidecar/main.py (/render/crop-classify, /render/ndvi-anomaly, /render/yield-proxy, /render/field-segment) · model-sidecar/crop_classify_gpu.py, train_crop_classifier.py, requirements.gpu.txt (unverified GPU scaffold) · cartos-web/src/lib/edition.ts (harvest preset) · cartos-web/src/lib/themes.ts (verdant theme) · crates/cartos-agent/src/llm.rs (ContentBlock::Thinking/RedactedThinking — the Opus 5 fix, engine-wide not Harvest-specific).

9. Cross-cutting features every module inherits

• Dockable floating panels (DockablePanel / PanelDock): users arrange panels to taste (persisted in localStorage, ID-namespaced per module); an admin can snapshot the defaults for everyone via the user badge. This is the standard for all map-surface overlays. The PanelDock launcher rail includes named slots for analysis (icon: mini chart), compare, map-export, and pointcloud (icon: hexagon wireframe, label "3D Data"), each shown or hidden per the module's corresponding capability feature.
• Edition switcher (shell/EditionSwitcher.tsx): a header pulldown — accent dot + current edition name + caret, click-outside/Escape to close — that lists every edition (Atlas/Grid/Tower/Milepost/Blueprint/Africa) and jumps to its subdomain via editionOrigin(). Shipped 2026-07-18 as a compact pulldown (was a horizontal pill row) so the module-nav tabs fit on one header row.
• GeoWizard — data-source marketplace (shell/GeoWizard.tsx): tabs for UAE Data, Living Atlas / ArcGIS Online search (no account needed), ArcGIS Hub, and Custom URL. Results add as styled, persistable layers.
• Live raster overlays, added via a uniform reconciler pattern (a panel emits Active<X>Layer[]; the module adds/removes raster sources prefixed arcgis- / gibs- / stac- and re-adds on style.load):
  • ArcGIS REST services (ArcGisLayersPanel, AD-SDI catalog + custom URL + identify popups).
  • NASA GIBS satellite — a 22-layer curated WMTS catalog in every module's Satellite Data tab (SatelliteDataPanel, nasa-gibs-catalog); native maps render via MapLibre, iframe modules receive layers over the bridge.
  • STAC catalogs (StacCatalogPanel, lib/stac.ts) — now a two-tab panel:
    • Search tab: collection picker + viewport bbox search + "Add" to make a layer active.
    • Manage tab: lists every active overlay with on/off visibility toggle, per-layer opacity slider, delete, and a Save button (persists the set via /api/layers). The Manage tab also hosts the Image Boost controls (see below).
• Global Image Boost (lib/image-boost.ts): a single raster-quality control that applies to every active data layer simultaneously — STAC, ArcGIS imagery, and NASA GIBS. Controls exposed in the STAC panel's Manage tab:
  • Smooth tile boundaries (MapLibre raster-resampling: linear vs nearest).
  • Contrast × and Saturation × multipliers (mapped to MapLibre's raster-contrast / raster-saturation [-1,1] range; UI speaks human ×-multipliers).
  • Master Opacity % — multiplies each layer's own opacity.
  • Persisted in localStorage (cartos.image-boost); re-applied by the host module's raster reconciler after each basemap swap or style reload.
• Layer persistence: /api/layers (list/save/delete) so discovered overlays survive reloads.
• Layer styling on the fly (LayerStylePopover, lib/layer-style*).
• Map tools: export (lib/map-export.ts), camera/bookmarks (lib/map-camera.ts), geocoding (lib/geocode.ts), a Legend, and identify/floating-popup. Measure and Time of Day are full capability features with their own dock panels — see §9.8.
• Global Mobility live feeds (lib/mobility.ts → /api/mobility/*): live aircraft (adsb.lol, no key), vessels (VesselFinder/aisstream, no key), and traffic tiles (TomTom — needs a key; serves transparent tiles without one).
• Swipe Compare (features/compare/CompareOverlay.tsx, capability compare, PR #48 + refined in PR #56 + PR #58): A/B comparison of two raster layers, camera-synced to the host module's map. Opening the overlay places two additional synced MapLibre maps above the module map; closing restores the host map. Two view modes selectable in the panel:
  • Swipe — a draggable divider wipes layer B over layer A; drag handles are clamped 2–98 % of the viewport width.
  • Side-by-side — left and right maps fill edge-to-edge panes; the draggable divider resizes the split between them (left map clipped to its own pane). Bidirectional camera sync (PR #58): both panes are fully interactive in both modes. Pan or zoom from the left pane or the right pane — both maps move together. A syncing guard flag prevents the move → jumpTo → move feedback loop. (Previously the right pane was non-interactive and only followed the left.) Each side (A/B) now chooses from a full grouped layer catalog plus a "Current map" source (PR #58):
  • Current map: clones the live host module's complete map style (basemap + active data/overlay layers) at selection time via map.getStyle(). Use this to compare exactly what is on screen — with its active STAC, ArcGIS, GIBS, or Overture overlays — against any other source.
  • Basemap: OpenStreetMap, Carto Light, Carto Dark.
  • Esri: Satellite (World Imagery), Streets, Terrain, Topographic, Ocean, NatGeo.
  • Satellite (GIBS): MODIS Terra True Color, MODIS Aqua True Color, VIIRS SNPP True Color — near-real-time (~2 days back) from NASA GIBS.
  • Custom URL: an XYZ tile template, a WMS/WMTS GetTile URL, or an Esri REST tile URL with {z}/{x}/{y} (or {z}/{y}/{x}) placeholders. Companion to two-epoch change detection — set A/B to before/after imagery before running change.detect. Catalog feature compare; default on Smart City, Maritime, and Emergency Services (migration 0017). Gated per module the same way as analysis.
• Map Export & Mapbook (features/map-export/MapExportOverlay.tsx, capability map-export, PR #51 + PR #53 + refined in PR #56): consolidated into the left-dock sidebar panel (same pattern as Analysis and Compare). See §9.2 for full detail. Catalog feature map-export; default on Smart City, Maritime, and Emergency Services (migration 0018).
• Time of Day (features/time-of-day/TimeOfDayOverlay.tsx, capability time-of-day, 2026-07-10): a sun-position lighting panel — scrub or animate apparent solar time to drive 3D building shading, hillshade illumination, and a day/twilight/night sky. See §9.8. Default on Smart City, Maritime, and Emergency Services (no DB migration needed — a static catalog default, same as analysis/compare).
• Measure (features/measure/MeasureOverlay.tsx, capability measure, 2026-07-10): the measure tool upgraded to a 3D-aware Distance/Area/Height panel with terrain-derived slope length. Replaces the old inline Smart City distance/area button. See §9.8. Default on Smart City, Maritime, and Emergency Services.
• Draw & Annotate (features/draw/DrawOverlay.tsx, capability draw, 2026-07-11): sketch/markup panel — Select · Point · Line · Polygon · Rectangle, per-feature stroke/fill/width + optional label, a live feature list, Clear all, Copy/Download GeoJSON. Default on Smart City, Maritime, and Emergency Services. See §9.9.
• Navigate compass rail (features/navigate/NavWidget.tsx, 2026-07-11): the always-on, collapsible, drag + resizable HUD that replaced MapLibre's default zoom/compass/geolocate/fullscreen controls in every native, Cartos Grid, and industry-edition module — camera controls, a multi-CRS coordinate readout (WGS84/Web Mercator/UTM/MGRS/State Plane), and a toggleable UTM/MGRS grid overlay. Not capability-gated — always present. See §9.9.
• Widget kit (features/widgets/widget-kit.css, 2026-07-11): the shared wk-* holographic-HUD CSS language behind every map-tool panel (Measure, Time of Day, Draw, Navigate), theme-token-driven so a platform theme recolours the whole kit. See §9.9.
• KPI strip + sensor-readings charts (KpiStrip, SensorReadingsChart, chart-themes), with themeable dashboards (ops-floor dark / holographic).
• Module nav reordering: drag to reorder (persisted in localStorage), with a reset to the default lineup.
• Platform theme system — see §9.4.
• Cartos rebrand (shell/CartosMark.tsx): the Cartos inline SVG mark is now shown on the splash screen, login page, and app shell. Operator and edition logos have been removed from the engine default; editions re-skin the mark via their own branding configuration. This makes the engine identity neutral so any licensed edition can apply its own visual identity without forking the core.

9.1 Agent intelligence surface — Cartos overhaul

Status: built and merged to main (PRs #37, #40).

The agent panel (cartos-web/src/shell/AgentChatPanel.tsx) is a global sidebar in AppShell. It was overhauled to become a full intelligence surface:

Window presence

The agent sidebar is resizable: drag the left edge to set the width (300–900 px); the choice persists in localStorage. A fullscreen/expand toggle pops the panel out to cover the entire app for deep analysis work; a restore button returns to the sidebar layout.

"Ask the map" — voice input

A microphone button below the prompt textarea uses the browser's native Web Speech API (SpeechRecognition / webkitSpeechRecognition, Chromium-based browsers). Speaking transcribes into the prompt box; the user reviews the text and hits Enter. No backend is involved — purely client-side. Unavailable in non-Chromium browsers (an alert informs the user).

Rich response rendering

Assistant answers are rendered as GitHub-flavored Markdown via react-markdown + remark-gfm (AgentMarkdown.tsx). Supported in the panel:

• Headings, bold, bullet/numbered lists, inline code, fenced code blocks.
• Markdown tables — the primary format for tool results (vessels, incidents, sensors, KPIs).
• Links ([label](url)) and images (![alt](url)) when the agent returns real URLs.
• A custom fenced **```chart ** block: the agent emits a JSON payload and the client renders it as an **inline SVG chart** (bar / line / pie) — AgentMarkdown.tsx > Chart. The agent system prompt (crates/cartos-agent/src/agent.rs`) instructs the model to use chart blocks only when they add value and only with real tool-returned data.
• For non-trivial analytical answers, the system prompt directs the agent to append ## Summary (2–4 sentences) and ## Recommendations (bulleted, actionable list) — establishing a consistent report structure.

The same AgentMarkdown component is used for the export path (see below), so tables and SVG charts carry through to the rendered report faithfully.

Comprehensive export

An Export button (visible when the conversation has at least one turn) opens a three-option menu:

The export is titled from the first user question (truncated to 70 chars). Live map screenshots in the export are a known follow-up — the global agent panel has no handle to the active module's map ref; that bridge is planned once a map-ref context is added to AppShell.

Agent system prompt

crates/cartos-agent/src/agent.rs SYSTEM_PROMPT was updated to direct the agent to respond in GitHub-flavored Markdown, use tables for tabular data, optionally end with Summary/Recommendations sections, and emit chart code-fences for visual data — while staying strictly grounded in tool-returned data.

MCP server — built (PR #43)

The Cartos MCP server is built and operational. See §13.6 for full documentation.

9.2 Map Export & Mapbook

Status: built and wired as a first-class capability feature (PRs #51, #53, #56); merged to main. Migration 0018 enables it for the dev tenant on Smart City, Maritime, and Emergency Services.

Source: cartos-web/src/features/map-export/MapExportOverlay.tsx · cartos-web/src/lib/mapbook.ts

A recreation of the EarthWatch3D advanced export and mapbook, ported to the MapLibre native modules and refined to full EarthWatch3D parity (PR #56). It is a portable capability feature (map-export) that slots into the PanelDock rail alongside Analysis and Compare — wired identically, and addable to any native map module via Admin → Features.

Panel layout (PR #56 refinement)

Export is now consolidated into the left-dock sidebar panel — the same DockablePanel pattern as Analysis and Compare. The old top-bar "Export" menu that existed in Smart City has been removed; all export flows live in the panel. A Create Map | Mapbook mode toggle at the top of the panel selects which workflow is shown. A Data (CSV) section at the bottom of the panel exposes per-module data tables as CSV downloads (DataExport[] prop), portable across any host module.

Create Map mode

The Create Map tab exports the current view. It offers four EarthWatch3D-parity single-page layout templates, each with a preferred default paper size and orientation:

Selecting a template automatically seeds the paper size and orientation; both are still overridable. All templates include a bearing-aware north arrow, geodesic scale bar, neatline frame, optional classification banner (SEC/FOUO/CONFIDENTIAL/SECRET/TOP SECRET — auto-coloured), and a bounds/projection footer.

Three export buttons are always present in Create Map mode:

• Export cartographic PDF — builds the selected template via jsPDF (direct vector drawing; unit = inches) entirely in the browser.
• Export GeoPDF (georeferenced) — captures north-up + nadir and server-sides the georeferencing via GDAL (see below).
• Capture PNG — one-click canvas.toDataURL download.

Paper sizes

The full plotter paper range is now available (down from five sizes in the original build):

All sizes support landscape and portrait orientations (the panel swaps the longer and shorter dimension accordingly).

Mapbook mode

A multi-page atlas from the current view, assembled via jsPDF:

1. Cover page — AOI overview map + labeled tile-grid index showing which sheet covers which cell. A sheet-plate row records scale, sheet count, paper, and generation timestamp.
2. Sheet per tile — the map flies to each tile's bbox (fitBounds + 'idle' event), captures the canvas, and writes a sheet with a plate label (e.g. "Sheet B-3"), scale bar, north arrow, and a mini index grid indicating the current tile position. View is restored after the last sheet.
3. Appendix (optional) — free-text notes page.

The tile grid auto-computes rows × columns from a chosen scale (1:N) and an overlap percentage (0–40 %), or the user sets the grid dimensions manually. Maximum 12 × 12 tiles.

OGC GeoPDF export (PR #53)

A true OGC GeoPDF — georeferenced, measurable, opens correctly placed in QGIS/ArcGIS. Available in both Create Map and Mapbook views via the "Export GeoPDF (georeferenced)" button.

How it works — server-side GDAL:

1. captureNorthUp in lib/mapbook.ts forces a north-up nadir capture (bearing = 0, pitch = 0) and records the current map bbox as Mercator corners, then restores the prior bearing/pitch.
2. The PNG + the Mercator bbox are POSTed to POST /api/export/geopdf in cartos-api.
3. cartos-api proxies the request to the model-sidecar's POST /render/geopdf endpoint.
4. The sidecar runs gdal_translate -of PDF -a_srs EPSG:3857 -a_ullr <xmin> <ymax> <xmax> <ymin> (from gdal-bin), tagging the PNG with Web Mercator corners.
5. The resulting .pdf bytes are streamed back as application/pdf and downloaded.

CRS — EPSG:3857 (Web Mercator): the MapLibre canvas is Mercator; tagging as EPSG:4326 would geometrically distort the image at non-equatorial latitudes. GIS tools open and measure correctly in EPSG:3857. Nadir/top-down only: captureNorthUp zeroes bearing and pitch so the extent is axis-aligned (required for a four-corner affine georeference). Oblique/3D views require GCP warping — the documented follow-up.

Verified: gdalinfo reports Driver: PDF/Geospatial PDF, CRS EPSG:3857, corners matching the AOI bbox. gdal-bin is installed in both model-sidecar/Dockerfile and Dockerfile.gpu.

Technical notes

• preserveDrawingBuffer: true is required on the MapLibre map constructor. Omitting it causes canvas.toDataURL to return a blank image (the canvas is cleared after each WebGL frame by default). Smart City, Maritime, and Emergency Services all set this; any new native map module that mounts MapExportOverlay must also set it.
• jsPDF (cartos-web/package.json) is the only new npm dependency from the original PR #51. No server round-trip for PNG/PDF/Mapbook — all assembled in the browser. GeoPDF is the exception (model-sidecar GDAL round-trip).
• Capture adapted from EarthWatch3D (Cesium): canvas.toDataURL instead of Cesium.resolutionScale; map.fitBounds() + map.once('idle', ...) per tile instead of camera.flyTo + waitForTilesLoaded.
• Remaining follow-ups: oblique/3D GCP warping for GeoPDF (non-nadir views); legend-image fetch; higher-than-screen-DPI capture.

9.3 3D Data — Point Clouds & Gaussian Splats

Status: Point clouds — PR #55 (initial), PR #57 (true geospatial placement, density slider, 90° pitch). Gaussian splats — PR #63 (three.js overlay canvas + SuperSplat SOGS importer). All merged to main. Migration 0019 enables the feature for the dev tenant. Compare: basemaps holographic-theme and hillshade-theme were also shipped in PR #59 (theme-matched basemaps in the Compare overlay layer catalog).

Source: cartos-web/src/features/point-cloud/PointCloudOverlay.tsx · cartos-web/src/lib/point-cloud.ts · cartos-web/src/lib/gaussian-splats.ts · cartos-web/src/lib/sogs.ts

The point-cloud capability feature now serves two 3D data types from one PanelDock panel: point clouds / 3D Tiles (via deck.gl) and Gaussian splats (via three.js). A Cloud | Splat mode toggle at the top of the panel selects which viewer is active. The overlay persists while the module is mounted. It is mounted in Smart City, Maritime, Emergency Services, and all nine Cartos Grid department modules (grid-operations, grid-capital, grid-fleet, grid-vegetation by default). A Tech Admin can cross-add it to any other native map module.

Pitch the map (right-drag / ctrl-drag) up to 90° for a full ground-level "standing" view. Smart City, Maritime, Emergency Services, and all Grid modules set maxPitch: 90 on their MapLibre map constructor (MapLibre 5.24 allows up to 180°; the old default was 60°).

Two source modes

3D Tiles service: Paste a tileset.json URL — any OGC 3D Tiles 1.0 point cloud (.pnts) or mesh. Rendered via Tile3DLayer + Tiles3DLoader from @loaders.gl/3d-tiles. On load the map flies to the tileset's cartographicCenter. Works with Cesium ion tilesets, Potree conversions, and hosted municipal or survey datasets.

Local LAS / LAZ file: Drag any .las or .laz file; parsed by LASLoader from @loaders.gl/las. After parsing, placement is determined by the Georeferenced | Center of map toggle:

If the georeferenced path is selected but no CRS is supplied (or the supplied string is unrecognised), the overlay falls through to center-of-map placement and shows a status message prompting the user to enter an EPSG/proj4.

resolveProjDef handles: EPSG:4326, EPSG:3857, all UTM north zones (EPSG 32601–32660), all UTM south zones (EPSG 32701–32760, adds +south), and any raw +proj=… string. Any other EPSG code currently returns null (center-of-map fallback).

Density slider (PR #57)

A density slider (2–100 %) decimates large local clouds before they are sent to the GPU. The library keeps every Nth point (step = round(1/fraction)), so a 10 M-point file at 10 % renders ~1 M points. This keeps WebGL throughput interactive on typical hardware without discarding the raw parse — raising the slider back to 100 % re-renders the full cloud.

Controls summary

Technical notes

• deck.gl MapboxOverlay (non-interleaved): the point cloud renders on its own canvas above MapLibre's. The overlay instance is created once per module mount and destroyed on unmount; closing the panel does not destroy it.
• proj4 reprojection: only the cloud's planar centroid (cx, cy) is reprojected. Each point is then stored as a metre offset (x − cx, y − cy, z − minZ) from that origin, using COORDINATE_SYSTEM.METER_OFFSETS. This is correct for survey-scale clouds (< ~100 km extent); large continental clouds would need a different approach.
• Elevation: for projected georeferenced files, z is subtracted by minZ so the cloud sits on the ground at its true elevation above the origin. Geographic files use COORDINATE_SYSTEM.LNGLAT and carry z as the raw altitude value.
• Color: if the LAS file has COLOR_0 attribute data, it is forwarded to the PointCloudLayer; otherwise a flat steel-blue [120, 200, 255] is used.
• New npm dependencies (PR #55/57): proj4 ^2.20.9, @types/proj4 ^2.5.6, @loaders.gl/las ^4.4.3, @loaders.gl/3d-tiles ^4.4.3 (@loaders.gl/core was already present for the I3S buildings path).
• preserveDrawingBuffer: not required for the point-cloud overlay (deck.gl renders to its own canvas), but all three host modules already set it for Map Export.

Gaussian splats (PR #63)

Gaussian splat files (.splat, .ksplat, .ply, .spz, and SuperSplat SOGS bundles) are rendered in MapLibre via a dedicated transparent overlay canvas driven by MapLibre's per-frame matrices — not a MapLibre custom layer injecting into the default framebuffer (which is not compositable by three.js). The overlay canvas sits above the map canvas with pointer-events: none.

Rendering architecture (lib/gaussian-splats.ts):

• three.js + @mkkellogg/gaussian-splats-3d DropInViewer: the splat viewer runs in the dedicated canvas; DropInViewer handles the per-frame Gaussian sort, splatting shader, and alpha blending.
• MapLibre v5 matrix split: MapLibre v5 exposes the mercator→clip matrix as args.defaultProjectionData.mainMatrix on each render call. Gaussian splats need a conventional perspective projection (P · View) because the shader derives per-splat screen size from the focal lengths in P. The render loop splits mainMatrix into projectionMatrix (the real P) and View = inv(P) · mainMatrix, giving the depth sorter the true eye position. Falls back to baking mainMatrix as the full projection if P is unusable.
• Anchor + scale + heading: splats carry no CRS. The scene is anchored at a chosen lng/lat (default: map centre at load time) with a user scale (×0.01 – ×10), heading (0–359°, yaw about the up axis), and a flip-Y toggle (capture up-axis varies). Auto-fit scales the splat to fill ~60 m on the map so it is immediately findable.
• zoomToSplat: auto-flies to the anchor at a zoom calculated from the splat's bounding box; pitch set to 60° so the splat is visible in 3D. "Zoom to splat" button re-triggers this.
• Placement controls: anchor at map centre ("Recentre"), fine-tune lat/lon inputs.

SuperSplat SOGS importer (lib/sogs.ts, PR #63):

@mkkellogg/gaussian-splats-3d has no built-in SOGS decoder. lib/sogs.ts fills the gap:

• Accepts files ending in .ssog, .sog, or .zip (the SuperSplat SOGS export formats).
• Uses fflate (unzipSync) to unpack the ZIP archive.
• Detects LOD / tiled bundles (lod-meta.json + per-level directories, each with a meta.json + per-tile .splat shards): picks the finest LOD level that fits a per-frame splat budget (the viewer CPU-sorts each frame, so splat count matters) by summing each level's splat count from the meta.
• Decodes the chosen tiles' interleaved position (quantised × 3 floats) + SH-0 colour (3 bytes) + opacity (1 byte) + scale (3 floats) + quaternion rotation (4 bytes) into the antimatter15 .splat binary layout and returns a Blob that the DropInViewer can load natively.
• For non-LOD SOGS (single-level): reads the lone meta.json and splat shard directly.

Splat panel controls:

preserveDrawingBuffer note: the splat overlay uses its own WebGLRenderer with preserveDrawingBuffer: true (keeps the frame visible between browser composite passes); it does not share the MapLibre canvas.

New npm dependencies (PR #63): three (three.js), @mkkellogg/gaussian-splats-3d, fflate (zip decompression for SOGS bundles).

9.4 Platform theme system

Status: built and merged to main (PR #67).

Source: cartos-web/src/lib/themes.ts · lib/theme-context.tsx · lib/themes.css · shell/ThemeSwitcher.tsx · lib/map-styles.ts (recolorStyleAccent, resolveBasemapStyle)

The Cartos engine has a platform-level theme system that re-skins the entire app — including the login screen, splash, all module UIs, and the basemap — without any page reload. Being engine-level, it works equally across every edition (Cartos Atlas, Cartos Grid, and future editions).

Resolution model

There is ONE global theme for the whole app. Any module may set a per-module override that applies while that module is active. Active theme = current module's override if set, else the global theme. Both the global choice and the per-module override map are persisted independently in localStorage (cartos.theme.global and cartos.theme.modules), so a deployment or user keeps its look across reloads.

The 10 palettes

Each palette is a ThemeOption with a ThemeKey, a label, a tagline, and a ThemeTokens set (12 CSS custom-property values + a scheme: "dark" | "light" flag):

applyThemeTokens(key) writes all 12 tokens onto :root as CSS custom properties (--bg, --bg-elev-1, --bg-elev-2, --border, --text, --text-dim, --accent, --accent-dim, --good, --bad, --warn) and sets color-scheme; the whole UI re-skins without a React re-render because everything references these variables. The data-cartos-theme attribute on <html> enables CSS selectors for per-theme overrides.

bootTheme() is called before first paint (in main.tsx before ReactDOM.render) so there is no flash of the default palette on load.

Theme-matched basemaps (lib/map-styles.ts)

Two new basemap keys in the map-styles catalog take the active theme accent:

resolveBasemapStyle(key, accent?) checks a themed: true flag on the basemap definition; when true it calls recolorStyleAccent(baseStyle, accent), which walks the MapLibre StyleSpecification layer list and replaces every colour expression matching the target hue with the new accent. themeAccent(key) reads the accent synchronously from THEMES (not from the DOM) so the recolour happens before the style is applied and there is no flicker. These two basemaps are listed in the Compare overlay's layer catalog (PR #59: "Holographic" and "Hillshade-3D" entries), and appear as native basemap options in GridModule and all other native map modules.

ThemeSwitcher UI (shell/ThemeSwitcher.tsx)

A palette picker accessible from the app shell (gear/settings icon in the user badge area). Shows all 10 palettes as colour swatches; clicking one calls applyThemeTokens and saveGlobalTheme. A per-module override dropdown lets power users set a different look for a specific module without changing the global default.

Floating panels now follow the theme accent (fixed 2026-07-18, shipped platform-wide)

Every dockable/floating panel — Basemap, Analysis, Compare, Map Export, the Navigate rail, AgentChatPanel, ArcGisLayersPanel, GeoWizard, LayerStylePopover, SatelliteDataPanel, SensorReadingsChart, StacCatalogPanel, UserBadge, DockablePanel's own chrome, and more — hardcoded the holographic cyan (#00d9ff, rgba(0,217,255,…)) for borders, title bars, active states, glows, and resize chips, so on any non-holographic edition (Cartos Africa/Blueprint = Desert amber, Cartos Tower = crimson) the map recoloured to the theme but every popup stayed cyan. themes.ts now also writes two RGB-triple custom properties on :root — --accent-rgb and --bg-rgb (hexToRgbTriple) — so CSS can build themed translucent colours with rgba(var(--accent-rgb), 0.2); a 27-file CSS sweep (299 replacements) changed every hardcoded cyan literal to var(--accent) / rgba(var(--accent-rgb), x), and DockablePanel's glass background now uses rgba(var(--bg-rgb), …) so a panel's body tints too (warm-dark on Desert, light on Daylight). Zero-regression for Holographic by construction — its --accent is #00d9ff, so the swept vars resolve to the exact prior cyan. Verified in-browser on Africa (Desert theme): Basemap panel, panel rail, and the Navigate widget all render amber.

"Satellite · Esri" is now a global basemap option (fixed 2026-07-18, shipped platform-wide)

lib/map-styles.ts's esri-imagery basemap (Esri World Imagery + a thin reference overlay) was labelled "Ortho · UAE HR" with a UAE-specific tagline, even though the underlying Esri World Imagery service is a standard global high-res aerial layer (sub-meter over most metros worldwide, not just Abu Dhabi/Dubai). Relabelled "Satellite · Esri" / "Esri World Imagery · global high-res aerial" so it reads correctly in every edition's basemap pulldown, including Cartos Africa's Foundation Layers registry, which reuses the same public Esri tile endpoint.

9.5 Cloud-native data layer — object-storage format spikes

Status: spikes / proofs-of-concept on main (PRs #113–#117). All formats are proven end-to-end on the existing MinIO object store — zero new services beyond what Phase 1 already runs. Demo / synthetic data. Public-read MinIO bucket in dev; not yet access-gated (no signed URLs) or hardened for production input. Production hardening is scoped as TBD in Phase 2 M03.

The platform evaluated GeoLibre 1.0 (opengeos; MIT) as a potential dependency and adopted the underlying permissive-licensed libraries directly (not the GeoLibre app). The result is five object-storage-native data formats that the browser range-reads directly from MinIO, each exercised in the Cartos Grid Grid Data panel and its companion feature panels. All five spikes reuse the existing MinIO object store (deploy/) and expose toggles/launchers in the existing GridModule.tsx panel system.

The six format experiments

Format generators (reusable operator scripts)

One-off batch scripts; scratch outputs go in tools/_tmp/ (gitignored). tools/upload_minio.py is a shared helper used by all generators (creds from env: MINIO_ENDPOINT / MINIO_ACCESS_KEY / MINIO_SECRET_KEY; defaults match deploy/docker-compose.yml).

Env var

VITE_CARTOS_TILES_URL — MinIO base URL the browser uses for all object-storage format range-reads (default http://localhost:9000; set in cartos-web/.env.local). Consumed by cartos-web/src/lib/env.ts → CARTOS_TILES_URL.

Web surface

All five format experiments surface in the Cartos Grid modules:

• Grid Data panel — "Cloud-native (spike)" group (GridModule.tsx): three checkboxes toggle PMTiles (addPmtilesAssets), FlatGeobuf (loadFgbAssets + re-read on moveend), and COG (addCog) layers independently from the live operational layers. Each is fully idempotent (add/remove on style reload via mapEpoch).
• DuckDB-WASM panel (features/duckdb/DuckdbSpikePanel.tsx): launched only from the grid-capital (CIP & Major Projects) module via a dedicated dock button. Lazily boots DuckDB-WASM (via lib/duckdb.ts → getDb()), fetches grid-projects.parquet from MinIO once, registers a projects view (geometry column excluded so SELECT * is tidy), and exposes a SQL input. Results render in a plain table. The view name:projects; queries like SELECT status, COUNT(*) FROM projects GROUP BY status work immediately.
• Geoprocessing panel (features/geoprocessing/GeoprocessingPanel.tsx): available on all Grid modules. Pick a live Grid layer (assets / vegetation / parcels / projects), choose an operation (buffer N metres / convex hull / centroid), and the result renders as a derived fill/line/circle layer instantly in the browser via @turf/turf. Area of the result is displayed in the panel.
• Export panel (features/export/ExportPanel.tsx): available on all Grid modules. Pick a live Grid layer and a format; all vector downloads (GeoJSON / Shapefile ZIP / FlatGeobuf / CSV) are generated client-side by lib/layer-export.ts with no server round-trip. A GeoPackage link points to the MinIO-hosted file produced by build_geopackage.py.