Incident Lifecycle & Core Process
A step-by-step engineering breakdown of how an incident flows from mobile citizen intake to zero-shot ML triage, LangGraph multi-agent reasoning, human supervisor review, and before/after resolution verification.
Stage 01: Multimodal Intake & Zero-Trust Ingestion
Citizen reporting begins through the responsive web wizard, WhatsApp Webhooks, Telegram Bots, or voice note audio submissions. Incoming media undergoes zero-trust sanitization, binary magic-byte validation, and automated EXIF GPS extraction while stripping sensitive hardware fingerprints.
Client-side canvas downsampling reduces 40MB photos to <1.2MB in under 200ms. The backend performs binary magic-byte validation (PNG, JPEG, WebP, MP4) and isolates storage under non-enumerable UUIDs with 1-hour signed access URLs.
- Omnichannel ingestion: WhatsApp, Telegram, Audio voice notes, and web reporting.
- EXIF GPS extraction and offline Google Maps/OSM share link regex parsing.
- Strict 50MB file size ceiling and MIME-type allowlist enforcement.
Citizen Device (Web Wizard / WhatsApp / Audio)
├── 1. Canvas Downscaler (≤ 1920x1080 @ 0.85 JPEG)
├── 2. EXIF / Map-Link Extraction (WGS84 lat/lon)
└── 3. POST /api/v1/reports + POST /reports/{id}/media
│
▼
FastAPI Ingestion Adapter
├── Binary Magic Byte Header Check (\x89PNG, \xff\xd8\xff, ftyp)
└── Isolated Storage Vault (med-<uuid>.<ext>)Stage 02: Deterministic Geospatial & Zero-Shot Vision Triage
Before invoking generative agent nodes, incoming reports are processed through fast, deterministic spatial queries, H3 hexagonal indexing, and computer vision defect models to establish observable facts.
- PostGIS Spatial Clustering: ST_DWithin queries group reports within dynamic radiuses (50m for potholes, 150m for water bursts) over a 72-hour rolling window.
- Zero-Shot Defect Vision: CLIP embeddings categorize visual defects against municipal taxonomies and compute defect surface area (cm²) and depth (mm).
- Landmark Proximity Buffer: Calculates exact distances to schools, hospital emergency bays, and transit corridors to assign deterministic P1/P2/P3 priority ratings.
Raw Report (med-0241.jpg, lat=20.29614, lon=85.82451)
│
├──► [PostGIS ST_DWithin(50m, 72h)] ──► Clustered to INC-0241 (duplicates: 3)
├──► [CLIP Zero-Shot Vision] ──► Defect: Water Leakage (Area: 2500cm², Depth: 60mm)
└──► [Spatial Buffer Engine] ──► 14m from DAV School Gate ──► PRIORITY: P1 (SLA: 4h)Stage 03: LangGraph Checkpointed Multi-Agent Reasoning
The incident enters a deterministic LangGraph state machine. Each agent operates with an isolated system prompt, dedicated schema contracts, and separate LLM calls to prevent cross-contamination.
1. Structure Evidence (triad separation) → 2. Clarification Check (interactive numbered prompt) → 3. Grounding Retrieval (hybrid BM25+dense RRF) → 4. Policy Routing (statutory jurisdiction) → 5. Operational Planning (SOR BOQ & dynamic SLA) → 6. Adversarial Critic (hallucination guardrail, max 2 revisions).
[load_context] ──► [ml_intelligence] ──► [structure_evidence]
│
▼
[knowledge_grounding] ◄── [clarification_check] ──► (Missing info? ──► [WAITING_FOR_CLARIFICATION])
│
▼
[routing_agent] ──► (Cites ROUTE-WATER-02 + Statutory Boundary)
│
▼
[operational_planner] ◄──┐ (BOQ: INR 17,077 / USD 197)
│ │
▼ │ (Critic Rejection, max 2 revisions)
[critic] ──────────┘
│
▼ (Critic Approved)
[prepare_human_review] ──► [WAITING_FOR_REVIEW]Stage 04: Human-in-the-Loop Review Gate & Command Center
Civitas enforces a strict governance standard: AI proposes operational plans, but authorized municipal supervisors hold final decision authority. Work orders are never automatically dispatched without human approval.
- Checkpointed Halt: LangGraph freezes execution state to PostgreSQL at WAITING_FOR_REVIEW.
- Supervisor Incident Dossier: Municipal supervisors review GIS hazard buffers, visual evidence triads, BOQ repair cost breakdowns, and the draft work order in the Command Center.
- 5 Canonical Review Actions: Approve (dispatch), Edit Work Order (adjust SLA/equipment), Reroute Department, Reject (dismiss false alarm), or Request Additional Evidence.
- Resumption: Submitting the review resumes the existing thread ID idempotently via POST /api/v1/workflows/{id}/review.
Stage 05: Field Crew Dispatch & Route Optimization
Upon supervisor authorization, the work order is assigned to district field crew leads with exact spatial coordinates, H3 hex route clusters, and equipment requirements. Concurrently, the citizen communication agent generates a non-technical status update for residents.
- Work Order Dispatch: Assigned to designated crew lead (e.g. Marcus Vance, Ward 12 Water Supply Dept) with required tools (ductile clamp, backhoe, asphalt patch).
- Spatial Crew Batching: Clusters multi-stop work orders in the same H3 hex cell into optimized waypoints to minimize travel time.
- Citizen Status Feed: Reassuring, non-technical notification informing the citizen that crew dispatch is active with an estimated resolution window.
Stage 06: Anti-Fraud Verification, Dispute Window & Digital Seal
An incident cannot be marked RESOLVED based on time elapsed alone. Field crews must submit post-repair photographic evidence, which is audited against pre-repair photos and historical completion archives using a 64-bit difference hash (dHash) anti-fraud engine.
Post-closure triggers an active 72-hour citizen dispute window. If uncontested, a permanent SHA-256 Municipal Audit Certificate is minted, and sanitized differential-privacy records are published to public GeoJSON/CSV open data feeds.
Field Crew Uploads Post-Repair Photo
│
▼
[64-bit dHash Anti-Fraud Check] ──► Duplicate / Stock Photo? ──► FLAG FRAUD
│
▼ (Clean Verification)
[Resolution Inspector Engine] ──► Pre/Post Embedding Delta Passed
│
├── 72-Hour Citizen Dispute Window Active (Auto Re-Open on Dispute)
├── Cryptographic SHA-256 Municipal Audit Certificate Minted
└── Public GeoJSON Feed Updated (Differential Privacy ±25m Jitter)