System Architecture

Explicit architectural boundaries keep the platform testable, operationally comprehensible, and safe to evolve.

Runtime Topology & Stack

The Civitas architecture separates user interfaces, operational runtime, workflow orchestration, and geospatial storage into independent, reviewable modules.

SCHEMA / FLOW

Next.js 16 (App Router + Leaflet GIS)
    │  (Typed HTTP Envelopes)
    ▼
FastAPI Operational Backend (apps/api)
    ├── Internal ML Engine (CLIP Zero-Shot, DBSCAN)
    ├── Geospatial Service (PostGIS 3.4 + H3 Indexing)
    ├── Knowledge Service (Policy & Playbook Retrieval)
    └── LangGraph Workflow Orchestrator (Checkpoint Saver)
        │
        ▼
PostgreSQL / Supabase (Application Data + LangGraph State)

Why the ML Bridge is Internal

The unified ReportAnalysis pipeline remains directly installed with the FastAPI runtime as a clean internal adapter. The internal analyze endpoint is a contract boundary rather than a separately deployed microservice, avoiding cold-start latency and duplicated model logic while keeping inference fully testable.

NOTE

Inference Isolation

ML inference runs deterministically with fallback heuristics if GPU acceleration or model checkpoints are unavailable.

Persistence & State Storage Split

Workflow-run metadata records execution IDs, report references, incident associations, trace IDs, and thread IDs in PostgreSQL. Canonical report, assessment, routing, work-order, and human review structures remain owned by the backend persistence layer.

H3 Hexagonal Indexing & SCADA IoT Telemetry Fusion

Civitas integrates Uber H3 discrete global grid indexing (Resolution 8 ~0.7km² neighborhoods, Resolution 9 ~0.1km² micro-zones) to detect chronic infrastructure failure zones without arbitrary administrative polygon bias. Real-time municipal SCADA sensor streams (subsurface water main pressure drops) and precipitation forecasts are fused with spatial clusters to distinguish localized leaks from systemic main ruptures.

H3 Res 8/9 hexagonal clustering computes rolling 90-day defect densities to flag systemic chronic failure zones.
SCADA pressure sensor fusion detects upstream anomalies (>15 PSI sudden drop) correlating with citizen leak reports.
Spatial crew batching organizes open work orders by H3 hex cell to minimize transit times and vehicle emissions.

Runtime Topology & Stack

The Civitas architecture separates user interfaces, operational runtime, workflow orchestration, and geospatial storage into independent, reviewable modules.

SCHEMA / FLOW

Next.js 16 (App Router + Leaflet GIS)
    │  (Typed HTTP Envelopes)
    ▼
FastAPI Operational Backend (apps/api)
    ├── Internal ML Engine (CLIP Zero-Shot, DBSCAN)
    ├── Geospatial Service (PostGIS 3.4 + H3 Indexing)
    ├── Knowledge Service (Policy & Playbook Retrieval)
    └── LangGraph Workflow Orchestrator (Checkpoint Saver)
        │
        ▼
PostgreSQL / Supabase (Application Data + LangGraph State)

Why the ML Bridge is Internal

NOTE

Inference Isolation

ML inference runs deterministically with fallback heuristics if GPU acceleration or model checkpoints are unavailable.

H3 Hexagonal Indexing & SCADA IoT Telemetry Fusion

H3 Res 8/9 hexagonal clustering computes rolling 90-day defect densities to flag systemic chronic failure zones.

SCADA pressure sensor fusion detects upstream anomalies (>15 PSI sudden drop) correlating with citizen leak reports.

Spatial crew batching organizes open work orders by H3 hex cell to minimize transit times and vehicle emissions.