Cartos — Comprehensive Guide

Space42 Smart Solutions · sovereign geospatial vertical-AI platform. Last updated 2026-06-09. 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)
6. The modules
7. Cross-cutting features every module inherits
8. Data sources, integrations & keys
9. HTTP API reference
10. The marketing website & GTM artifacts
11. Roadmap — Phase 2 & Phase 3
12. Reference docs

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.

It is built in three phases, each standing on its own and compounding the last:

This guide is primarily about Phase I — what's actually built and running. Phases II/III are planning doc sets (see §13).

Two different things are called "Phase 2": the RLS / group-access work (shipped — §7) and the Analyst Intelligence Layer doc set (not built). When in doubt, ask which is meant.

2. Live URLs & quick links

The app (cartos-web + cartos-api) is run locally in development; only the

3. Architecture at a glance

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

   Browser  │  cartos-web — React + Vite shell                  │

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

            │  panels · AI agent chat · GeoWizard · overlays    │

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

                            │  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)

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

                            │

        ┌───────────────────┼───────────────────────┐

        ▼                   ▼                         ▼

  Postgres + PostGIS   Keycloak (SSO/JWT)      MinIO (object store)

  (RLS tenant+team)    realm: cartos           + Caddy reverse proxy

• Rust workspace carries the data fabric, agent, and API; a React shell renders MapLibre 2D and Cesium 3D (the latter via an iframe bridge to the sibling ../cesium_project_SPS app).
• Everything ships in containers you run in-territory (deploy/).
• Tenant- and team-isolation is enforced at the database with row-level security, 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.
• RLS bites in production once the API runs under a non-super role; in dev with the postgres role 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 (admin / viewer), and team-scoped data. JWT is RS256-validated against Keycloak's JWKS (fetched at startup, cached).
• Native Admin module manages users and group membership in-app via the Keycloak Admin REST API (/api/admin/users, /api/admin/groups, add/remove user↔︎group). 503s unless CARTOS_KEYCLOAK_ADMIN_CLIENT_SECRET is set.

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).
• 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
• Tools requiring the DB are disabled gracefully if Postgres is unreachable (server still starts; /healthz reports honestly).

8. The modules

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

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

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.
• 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).
• Layer persistence: /api/layers (list/save/delete) so discovered overlays survive reloads.
• Layer styling on the fly (LayerStylePopover, lib/layer-style*).
• Map tools: measure (lib/measure.ts), export (lib/map-export.ts), camera/bookmarks (lib/map-camera.ts), geocoding (lib/geocode.ts), a Legend, and identify/floating-popup.
• 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).
• 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.

10. Data sources, integrations & keys

cartos-api loads a gitignored workspace-root .env via dotenvy; the Anthropic / aisstream / TomTom keys are reused from EarthWatch3D's .env.

11. HTTP API reference

All /api/* routes require a Bearer JWT except /healthz.

12. The marketing website & GTM artifacts

website/ — live at https://cartos.pages.dev

• Cloudflare Pages, git-connected to main → pushing main publishes. No CI/wrangler in the repo (the connection lives in the Cloudflare dashboard).
• Pages: index, vision (Map Africa / UAE Base Map), interface (product-screenshot tour), platform (Phase I), analyst-layer (Phase II), field (Phase III), why, and commercial-model (pricing).
• Plain HTML/CSS/JS, inline-SVG charts (no chart library), strict CSP in _headers (script-src 'self' — scripts must be external files, e.g. gate.js).
• images/*.webp are optimized from cartos_screenshots/ via website/tools/optimize-screenshots.py (re-run after adding captures).
• The footer CARTOS wordmark on every page links to commercial-model.html.

cartos-pricing/ — commercial model & business case

• build.py is the single source of truth (pricing pillars, tier ACVs, unit economics, revenue/breakeven, customer ROI, competitive TCO, departments, personas) and emits two docs from the same data:
  • Internal cartos-commercial-model.html — full financials.
  • Public-safe website/commercial-model.html — our margins / cost-to-deliver / revenue / breakeven stripped; published on the site.
• make_docx.py builds the .docx; a headless-Chrome print builds the .pdf.
• All figures are illustrative planning anchors, not quotes.
• The public page sits behind a temporary soft password gate (the demo password): website/gate.js, only the SHA-256 is embedded, noindex. It's demo-grade, not real security (content still ships in source) — replace with Cloudflare Access for real auth. GATE_PASSWORD lives in build.py.

To regenerate: python cartos-pricing/build.py, then (for docx/pdf) the rasterize + make_docx.py steps in cartos-pricing/README.md.

13. Roadmap — Phase 2 & Phase 3

Phase II — Analyst Intelligence Layer (cartos-phase2/, Gate 0, not built)

Turns the substrate into one that reasons about change, builds in 3D, derives analysis-ready data, and writes auditable reports. Five modules in waves:

New infra shape: a GPU-backed Python model sidecar that cartos-api calls as async jobs. Read the three Gate-0 build contracts in cartos-phase2/docs/phase-2/specs/ before implementing. ⚠ cartos-phase2/docs/strategy/ip-timing.md is time-sensitive (public disclosure affects patentability).

Phase III — Cartos Field (cartos-phase3-mobile/, MRD/PRD, not built)

A configurable, offline-first mobile field-capture platform — the sovereign ground-truth edge that feeds the loop and multiplies seats (~10× field vs analyst).

14. Reference docs

Questions or something out of date? Update this guide alongside the change.

Live site: https://cartos.pages.dev