# vikram0678/vigil-flood architecture

> Architecture diagram of the GitHub repository vikram0678/vigil-flood, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vikram0678/vigil-flood
- Repository: https://github.com/vikram0678/vigil-flood

## Overview

VIGIL-FLOOD is a flash-flood early-warning and response system for hilly communities. Its primary workflow turns sensor and weather telemetry into village-level hazard analysis, actionable lead time, evacuation guidance, and live authority/citizen views. The backend also provides scenario simulation, external-data access, and Aapda Mitra disaster Q&A; the React dashboard adds GIS, XAI, and citizen-facing capabilities. Several subsystem links are documented by the README or imports, but unsampled routes and modules limit evidence for finer runtime relationships.

Main entry points: [`frontend_react/src/App.tsx`](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/App.tsx) (Dashboard application), [`backend/app/core/simulation.py`](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/simulation.py) (Scenario analysis), [`backend/app/api/routes.py`](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/api/routes.py) (REST API), [`backend/app/aapda_mitra/router.py`](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/router.py) (Assistant API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Warning backend"]
  node_api["REST API<br/>[routes.py]"]
  node_ws["Telemetry stream<br/>[websocket.py]"]
  node_server["FastAPI server<br/>[main.py]"]
  node_connectors["External data connectors"]
  node_cache[("Tile cache<br/>[tile_cache.py]")]
end

subgraph group_data["Risk and response"]
  node_validation["Input sanitizers<br/>[sanitizers.py]"]
  node_health["Sensor health<br/>[sensor_health.py]"]
  node_ml["Dual ML risk engine<br/>[ml_engine.py]"]
  node_training["Synthetic data<br/>[synthetic_data.py]"]
  node_lead["Lead-time estimator"]
  node_actions["Evacuation and alerts<br/>[action_engine.py]"]
  node_simulation["Scenario analysis<br/>[simulation.py]"]
end

subgraph group_assistant["Disaster assistant"]
  node_chatapi["Assistant API<br/>[router.py]"]
  node_rules["Offline decision engine"]
  node_chatconfig["Assistant configuration"]
  node_llm["OpenRouter client"]
end

subgraph group_frontend["React dashboard"]
  node_app["Dashboard application<br/>[App.tsx]"]
  node_state["Flood state<br/>[FloodContext.tsx]"]
  node_socket["WebSocket hook<br/>[useWebSocket.ts]"]
  node_map["GIS maps<br/>[MapContainer.tsx]"]
  node_analysis["XAI analysis"]
  node_sandbox["What-if controls<br/>[WhatIfSandbox.tsx]"]
  node_citizenview["Citizen alerts<br/>[CitizenView.tsx]"]
  node_panel["Catchment panel"]
  node_bot["Aapda Mitra chat<br/>[AapdaMitraBot.tsx]"]
  node_deepmap["2D GIS view<br/>[GISMap2D.tsx]"]
  node_terrain["3D terrain view<br/>[GISMap3D.tsx]"]
  node_floodhub["Flood Hub panel"]
  node_hydrograph["Hydrograph"]
  node_methodology["Methodology"]
  node_tour["Product tour"]
end

node_operators(("Authorities"))
node_citizens(("Citizens"))
node_sources(("Weather and IoT"))

node_operators -.->|"use dashboard"| node_app
node_citizens -.->|"view alerts"| node_app
node_sources -.->|"provide observations"| node_connectors
node_server -->|"mounts routes"| node_api
node_server -->|"mounts stream"| node_ws
node_server -->|"mounts assistant"| node_chatapi
node_api -->|"requests analysis"| node_simulation
node_api -->|"queries health"| node_health
node_api -->|"fetches external data"| node_connectors
node_api -->|"uses tile cache"| node_cache
node_ws -->|"reads analysis"| node_simulation
node_simulation -->|"evaluates risk"| node_ml
node_simulation -->|"calculates lead time"| node_lead
node_simulation -->|"builds response plan"| node_actions
node_simulation -->|"checks sensor health"| node_health
node_simulation -->|"uses validation"| node_validation
node_ml -->|"loads training data"| node_training
node_chatapi -->|"tries cloud model"| node_llm
node_chatapi -->|"falls back to rules"| node_rules
node_chatapi -->|"uses prompt settings"| node_chatconfig
node_app -->|"reads shared state"| node_state
node_app -->|"starts live updates"| node_socket
node_socket -->|"updates telemetry"| node_state
node_state -->|"fetches village data"| node_api
node_state -.->|"submits scenarios"| node_simulation
node_app -->|"renders map"| node_map
node_map -->|"renders 2D view"| node_deepmap
node_map -->|"renders 3D view"| node_terrain
node_map -.->|"offers basemap panel"| node_floodhub
node_app -->|"renders analysis"| node_analysis
node_app -->|"renders simulation"| node_sandbox
node_app -->|"renders citizen view"| node_citizenview
node_app -->|"renders catchments"| node_panel
node_app -->|"renders assistant"| node_bot
node_app -->|"renders hydrograph"| node_hydrograph
node_app -->|"renders methodology"| node_methodology
node_app -->|"renders product tour"| node_tour

click node_api "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/api/routes.py"
click node_ws "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/api/websocket.py"
click node_server "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/main.py"
click node_connectors "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/external_connectors.py"
click node_cache "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/tile_cache.py"
click node_validation "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/sanitizers.py"
click node_health "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/sensor_health.py"
click node_ml "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/ml_engine.py"
click node_training "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/synthetic_data.py"
click node_lead "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/lead_time_engine.py"
click node_actions "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/action_engine.py"
click node_simulation "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/simulation.py"
click node_chatapi "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/router.py"
click node_rules "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/deterministic_engine.py"
click node_chatconfig "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/aapda_mitra_config.py"
click node_llm "https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/openrouter_client.py"
click node_app "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/App.tsx"
click node_state "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/context/FloodContext.tsx"
click node_socket "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/hooks/useWebSocket.ts"
click node_map "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/map/MapContainer.tsx"
click node_analysis "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/analysis/DeepDiveAnalysis.tsx"
click node_sandbox "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/simulation/WhatIfSandbox.tsx"
click node_citizenview "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/citizen/CitizenView.tsx"
click node_panel "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/sidebar/PilotCatchmentPanel.tsx"
click node_bot "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/aapda_mitra/AapdaMitraBot.tsx"
click node_deepmap "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/map/GISMap2D.tsx"
click node_terrain "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/map/GISMap3D.tsx"
click node_floodhub "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/map/GoogleFloodHubPanel.tsx"
click node_hydrograph "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/modals/HydrographModal.tsx"
click node_methodology "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/modals/MethodologyModal.tsx"
click node_tour "https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/tour/ProductTourModal.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_ws,node_server,node_connectors,node_cache toneBlue
class node_validation,node_health,node_ml,node_training,node_lead,node_actions,node_simulation toneAmber
class node_chatapi,node_rules,node_chatconfig,node_llm toneMint
class node_app,node_state,node_socket,node_map,node_analysis,node_sandbox,node_citizenview,node_panel,node_bot,node_deepmap,node_terrain,node_floodhub,node_hydrograph,node_methodology,node_tour toneRose
class node_operators,node_citizens,node_sources toneIndigo
```

## Components

### Warning backend

- [REST API](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Telemetry stream](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/api/websocket.py): `backend/app/api/websocket.py`
- [FastAPI server](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/main.py): `backend/app/main.py`
- [External data connectors](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/external_connectors.py): `backend/app/core/external_connectors.py`
- [Tile cache](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/tile_cache.py): `backend/app/core/tile_cache.py`

### Risk and response

- [Input sanitizers](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/sanitizers.py): `backend/app/core/sanitizers.py`
- [Sensor health](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/sensor_health.py): `backend/app/core/sensor_health.py`
- [Dual ML risk engine](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/ml_engine.py): `backend/app/core/ml_engine.py`
- [Synthetic data](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/synthetic_data.py): `backend/app/core/synthetic_data.py`
- [Lead-time estimator](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/lead_time_engine.py): `backend/app/core/lead_time_engine.py`
- [Evacuation and alerts](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/action_engine.py): `backend/app/core/action_engine.py`
- [Scenario analysis](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/core/simulation.py): `backend/app/core/simulation.py`

### Disaster assistant

- [Assistant API](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/router.py): `backend/app/aapda_mitra/router.py`
- [Offline decision engine](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/deterministic_engine.py): `backend/app/aapda_mitra/deterministic_engine.py`
- [Assistant configuration](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/aapda_mitra_config.py): `backend/app/aapda_mitra/aapda_mitra_config.py`
- [OpenRouter client](https://github.com/vikram0678/vigil-flood/blob/main/backend/app/aapda_mitra/openrouter_client.py): `backend/app/aapda_mitra/openrouter_client.py`

### React dashboard

- [Dashboard application](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/App.tsx): `frontend_react/src/App.tsx`
- [Flood state](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/context/FloodContext.tsx): `frontend_react/src/context/FloodContext.tsx`
- [WebSocket hook](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/hooks/useWebSocket.ts): `frontend_react/src/hooks/useWebSocket.ts`
- [GIS maps](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/map/MapContainer.tsx): `frontend_react/src/components/map/MapContainer.tsx`
- [XAI analysis](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/analysis/DeepDiveAnalysis.tsx): `frontend_react/src/components/analysis/DeepDiveAnalysis.tsx`
- [What-if controls](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/simulation/WhatIfSandbox.tsx): `frontend_react/src/components/simulation/WhatIfSandbox.tsx`
- [Citizen alerts](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/citizen/CitizenView.tsx): `frontend_react/src/components/citizen/CitizenView.tsx`
- [Catchment panel](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/sidebar/PilotCatchmentPanel.tsx): `frontend_react/src/components/sidebar/PilotCatchmentPanel.tsx`
- [Aapda Mitra chat](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/aapda_mitra/AapdaMitraBot.tsx): `frontend_react/src/components/aapda_mitra/AapdaMitraBot.tsx`
- [2D GIS view](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/map/GISMap2D.tsx): `frontend_react/src/components/map/GISMap2D.tsx`
- [3D terrain view](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/map/GISMap3D.tsx): `frontend_react/src/components/map/GISMap3D.tsx`
- [Flood Hub panel](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/map/GoogleFloodHubPanel.tsx): `frontend_react/src/components/map/GoogleFloodHubPanel.tsx`
- [Hydrograph](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/modals/HydrographModal.tsx): `frontend_react/src/components/modals/HydrographModal.tsx`
- [Methodology](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/modals/MethodologyModal.tsx): `frontend_react/src/components/modals/MethodologyModal.tsx`
- [Product tour](https://github.com/vikram0678/vigil-flood/blob/main/frontend_react/src/components/tour/ProductTourModal.tsx): `frontend_react/src/components/tour/ProductTourModal.tsx`

### Other components

- **Authorities**
- **Citizens**
- **Weather and IoT**

## Connections

- Authorities → Dashboard application: use dashboard
- Citizens → Dashboard application: view alerts
- Weather and IoT → External data connectors: provide observations
- FastAPI server → REST API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI server → Telemetry stream: mounts stream (evidence: `backend/app/main.py`)
- FastAPI server → Assistant API: mounts assistant (evidence: `backend/app/main.py`)
- REST API → Scenario analysis: requests analysis (evidence: `backend/app/api/routes.py`)
- REST API → Sensor health: queries health (evidence: `backend/app/api/routes.py`)
- REST API → External data connectors: fetches external data (evidence: `backend/app/api/routes.py`)
- REST API → Tile cache: uses tile cache (evidence: `backend/app/api/routes.py`)
- Telemetry stream → Scenario analysis: reads analysis (evidence: `backend/app/api/websocket.py`)
- Scenario analysis → Dual ML risk engine: evaluates risk (evidence: `backend/app/core/simulation.py`)
- Scenario analysis → Lead-time estimator: calculates lead time (evidence: `backend/app/core/simulation.py`)
- Scenario analysis → Evacuation and alerts: builds response plan (evidence: `backend/app/core/simulation.py`)
- Scenario analysis → Sensor health: checks sensor health (evidence: `backend/app/core/simulation.py`)
- Scenario analysis → Input sanitizers: uses validation (evidence: `backend/app/core/simulation.py`)
- Dual ML risk engine → Synthetic data: loads training data (evidence: `backend/app/core/ml_engine.py`)
- Assistant API → OpenRouter client: tries cloud model (evidence: `backend/app/aapda_mitra/router.py`)
- Assistant API → Offline decision engine: falls back to rules (evidence: `backend/app/aapda_mitra/router.py`)
- Assistant API → Assistant configuration: uses prompt settings (evidence: `backend/app/aapda_mitra/router.py`)
- Dashboard application → Flood state: reads shared state (evidence: `frontend_react/src/App.tsx`)
- Dashboard application → WebSocket hook: starts live updates (evidence: `frontend_react/src/App.tsx`)
- WebSocket hook → Flood state: updates telemetry (evidence: `frontend_react/src/hooks/useWebSocket.ts`)
- Flood state → REST API: fetches village data (evidence: `frontend_react/src/context/FloodContext.tsx`)
- Flood state → Scenario analysis: submits scenarios
- Dashboard application → GIS maps: renders map (evidence: `frontend_react/src/App.tsx`)
- GIS maps → 2D GIS view: renders 2D view (evidence: `frontend_react/src/components/map/MapContainer.tsx`)
- GIS maps → 3D terrain view: renders 3D view (evidence: `frontend_react/src/components/map/MapContainer.tsx`)
- GIS maps → Flood Hub panel: offers basemap panel
- Dashboard application → XAI analysis: renders analysis (evidence: `frontend_react/src/App.tsx`)
- Dashboard application → What-if controls: renders simulation (evidence: `frontend_react/src/App.tsx`)
- Dashboard application → Citizen alerts: renders citizen view (evidence: `frontend_react/src/App.tsx`)
- Dashboard application → Catchment panel: renders catchments (evidence: `frontend_react/src/App.tsx`)
- Dashboard application → Aapda Mitra chat: renders assistant (evidence: `frontend_react/src/App.tsx`)
- Dashboard application → Hydrograph: renders hydrograph (evidence: `frontend_react/src/App.tsx`)
- Dashboard application → Methodology: renders methodology (evidence: `frontend_react/src/App.tsx`)
- Dashboard application → Product tour: renders product tour (evidence: `frontend_react/src/App.tsx`)
