# ajay-1011-git/hyper-local-flood-prediction architecture

> Architecture diagram of the GitHub repository ajay-1011-git/hyper-local-flood-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ajay-1011-git/hyper-local-flood-prediction
- Repository: https://github.com/ajay-1011-git/hyper-local-flood-prediction

## Overview

Hyperlocal flood prediction and early warning: operators request a site forecast, which progresses from regional weather and river observations through terrain downscaling, physical flood simulation, and risk ranking; Stage 4 packages results as CAP alerts and scene assets for the frontend. The README documents inter-stage HTTP/data boundaries, and sampled routes confirm key fetches. Some internal subsystem wiring is inferred only at the documented pipeline level; uncertain links are omitted.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/api/client.ts) (API client), [`backend/stage4/routes.py`](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage4/routes.py) (Alert and scene API), [`backend/stage1b/routes.py`](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/routes.py) (Downscale and ingest API), [`frontend/src/App.tsx`](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_forecast["Forecast acquisition"]
  node_stage1a_routes["Regional forecast API<br/>[routes.py]"]
  node_gefs["GEFS client<br/>[client.py]"]
  node_cwc["River-stage client<br/>[client.py]"]
  node_wn2["WN2 fallback<br/>[loader.py]"]
end

subgraph group_site["Site inputs"]
  node_stage1b_routes["Downscale and ingest API<br/>[routes.py]"]
  node_dem["DEM acquisition<br/>[client.py]"]
  node_downscale["Statistical downscaling<br/>[orchestrator.py]"]
  node_tnwrd["Gauge calibration<br/>[client.py]"]
  node_sensor_ingest["Sensor ingestion<br/>[ingest.py]"]
end

subgraph group_physics["Flood simulation"]
  node_stage2_routes["Simulation API<br/>[routes.py]"]
  node_precompute["Precompute orchestration<br/>[precompute.py]"]
  node_terrain_mesh["Terrain and mesh<br/>[site_transform.py]"]
  node_solver["Shallow-water solver"]
  node_gnn["SWE-GNN ensemble<br/>[ensemble.py]"]
  node_assimilation["Sensor assimilation"]
  node_simulation_state[("Simulation state store")]
end

subgraph group_decisions["Risk and alerts"]
  node_stage3_routes["Damage-ranking API<br/>[routes.py]"]
  node_ranking["Exposure and risk ranking<br/>[risk_ranking.py]"]
  node_stage4_routes["Alert and scene API<br/>[routes.py]"]
  node_cap["CAP alert generation<br/>[cap_generator.py]"]
  node_multilingual["Multilingual alert text<br/>[multilingual.py]"]
end

subgraph group_experience["User experience"]
  node_frontend["React application<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_dashboard["Operations dashboard<br/>[Dashboard.tsx]"]
  node_alert_composer["Alert composer<br/>[AlertComposer.tsx]"]
  node_citizen_view["Citizen view<br/>[CitizenView.tsx]"]
  node_scene["3D site scene<br/>[SiteScene.tsx]"]
end

node_operator(("Operator / citizen"))
node_weather_services(("NOAA / CWC"))
node_sensors(("ESP32 water sensor"))
node_terrain_services(("DEM / telemetry services"))
node_sarvam(("Sarvam service"))
node_redis[("Redis cache")]
node_postgres[("PostgreSQL / PostGIS")]

node_operator -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_dashboard
node_frontend -->|"routes to"| node_alert_composer
node_frontend -->|"routes to"| node_citizen_view
node_dashboard -->|"requests data"| node_api_client
node_alert_composer -->|"requests alerts"| node_api_client
node_citizen_view -->|"requests alerts"| node_api_client
node_api_client -->|"fetches forecast"| node_stage1a_routes
node_api_client -->|"fetches downscaled"| node_stage1b_routes
node_api_client -->|"requests simulation"| node_stage2_routes
node_api_client -->|"requests ranking"| node_stage3_routes
node_api_client -->|"requests alerts"| node_stage4_routes
node_stage1a_routes -->|"acquires rainfall"| node_gefs
node_stage1a_routes -->|"acquires river stage"| node_cwc
node_stage1a_routes -.->|"falls back to"| node_wn2
node_gefs -->|"fetches GEFS"| node_weather_services
node_cwc -->|"fetches observations"| node_weather_services
node_stage1b_routes -->|"fetches regional forecast"| node_stage1a_routes
node_stage1b_routes -->|"obtains terrain"| node_dem
node_stage1b_routes -->|"computes field"| node_downscale
node_downscale -->|"uses calibration data"| node_tnwrd
node_dem -->|"fetches elevation"| node_terrain_services
node_tnwrd -->|"fetches telemetry"| node_terrain_services
node_sensors -->|"posts readings"| node_stage1b_routes
node_stage1b_routes -->|"handles reading"| node_sensor_ingest
node_sensor_ingest -->|"persists readings"| node_postgres
node_sensor_ingest -->|"broadcasts updates"| node_frontend
node_stage2_routes -->|"fetches downscaled field"| node_stage1b_routes
node_stage2_routes -->|"starts job"| node_precompute
node_precompute -->|"builds site mesh"| node_terrain_mesh
node_precompute -->|"runs physics"| node_solver
node_precompute -->|"runs ensemble"| node_gnn
node_precompute -->|"applies observations"| node_assimilation
node_assimilation -->|"reads sensor data"| node_postgres
node_stage2_routes -->|"loads and saves"| node_simulation_state
node_stage3_routes -->|"fetches simulation"| node_stage2_routes
node_stage3_routes -->|"computes ranking"| node_ranking
node_stage3_routes -->|"caches ranking"| node_redis
node_stage4_routes -->|"fetches simulation"| node_stage2_routes
node_stage4_routes -->|"fetches ranking"| node_stage3_routes
node_stage4_routes -->|"generates CAP"| node_cap
node_stage4_routes -->|"generates translations"| node_multilingual
node_multilingual -.->|"requests translation"| node_sarvam
node_stage4_routes -->|"caches alerts"| node_redis
node_stage4_routes -->|"serves scene assets"| node_frontend
node_frontend -->|"renders site"| node_scene

click node_frontend "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/api/client.ts"
click node_dashboard "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/pages/Dashboard.tsx"
click node_alert_composer "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/pages/AlertComposer.tsx"
click node_citizen_view "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/pages/CitizenView.tsx"
click node_scene "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/scene/SiteScene.tsx"
click node_stage1a_routes "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1a/routes.py"
click node_gefs "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1a/gefs/client.py"
click node_cwc "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1a/cwc/client.py"
click node_wn2 "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1a/wn2mini/loader.py"
click node_stage1b_routes "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/routes.py"
click node_dem "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/dem/client.py"
click node_downscale "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/downscaling/orchestrator.py"
click node_tnwrd "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/tnwrd/client.py"
click node_sensor_ingest "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/sensor/ingest.py"
click node_stage2_routes "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/routes.py"
click node_precompute "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/precompute.py"
click node_terrain_mesh "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/terrain/site_transform.py"
click node_solver "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/solver/shallow_water_solver.py"
click node_gnn "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/gnn/ensemble.py"
click node_assimilation "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/assimilation/ghost_cell_update.py"
click node_simulation_state "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/site_state_store.py"
click node_stage3_routes "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage3/routes.py"
click node_ranking "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage3/ranking/risk_ranking.py"
click node_stage4_routes "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage4/routes.py"
click node_cap "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage4/alerts/cap_generator.py"
click node_multilingual "https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage4/alerts/multilingual.py"

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_stage1a_routes,node_gefs,node_cwc,node_wn2 toneBlue
class node_stage1b_routes,node_dem,node_downscale,node_tnwrd,node_sensor_ingest,node_redis,node_postgres toneAmber
class node_stage2_routes,node_precompute,node_terrain_mesh,node_solver,node_gnn,node_assimilation,node_simulation_state toneMint
class node_stage3_routes,node_ranking,node_stage4_routes,node_cap,node_multilingual toneRose
class node_frontend,node_api_client,node_dashboard,node_alert_composer,node_citizen_view,node_scene,node_operator,node_weather_services,node_sensors,node_terrain_services,node_sarvam toneIndigo
```

## Components

### Forecast acquisition

- [Regional forecast API](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1a/routes.py): `backend/stage1a/routes.py`
- [GEFS client](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1a/gefs/client.py): `backend/stage1a/gefs/client.py`
- [River-stage client](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1a/cwc/client.py): `backend/stage1a/cwc/client.py`
- [WN2 fallback](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1a/wn2mini/loader.py): `backend/stage1a/wn2mini/loader.py`

### Site inputs

- [Downscale and ingest API](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/routes.py): `backend/stage1b/routes.py`
- [DEM acquisition](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/dem/client.py): `backend/stage1b/dem/client.py`
- [Statistical downscaling](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/downscaling/orchestrator.py): `backend/stage1b/downscaling/orchestrator.py`
- [Gauge calibration](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/tnwrd/client.py): `backend/stage1b/tnwrd/client.py`
- [Sensor ingestion](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage1b/sensor/ingest.py): `backend/stage1b/sensor/ingest.py`

### Flood simulation

- [Simulation API](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/routes.py): `backend/stage2/routes.py`
- [Precompute orchestration](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/precompute.py): `backend/stage2/precompute.py`
- [Terrain and mesh](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/terrain/site_transform.py): `backend/stage2/terrain/site_transform.py`
- [Shallow-water solver](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/solver/shallow_water_solver.py): `backend/stage2/solver/shallow_water_solver.py`
- [SWE-GNN ensemble](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/gnn/ensemble.py): `backend/stage2/gnn/ensemble.py`
- [Sensor assimilation](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/assimilation/ghost_cell_update.py): `backend/stage2/assimilation/ghost_cell_update.py`
- [Simulation state store](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage2/site_state_store.py): `backend/stage2/site_state_store.py`

### Risk and alerts

- [Damage-ranking API](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage3/routes.py): `backend/stage3/routes.py`
- [Exposure and risk ranking](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage3/ranking/risk_ranking.py): `backend/stage3/ranking/risk_ranking.py`
- [Alert and scene API](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage4/routes.py): `backend/stage4/routes.py`
- [CAP alert generation](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage4/alerts/cap_generator.py): `backend/stage4/alerts/cap_generator.py`
- [Multilingual alert text](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/backend/stage4/alerts/multilingual.py): `backend/stage4/alerts/multilingual.py`

### User experience

- [React application](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Operations dashboard](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Alert composer](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/pages/AlertComposer.tsx): `frontend/src/pages/AlertComposer.tsx`
- [Citizen view](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/pages/CitizenView.tsx): `frontend/src/pages/CitizenView.tsx`
- [3D site scene](https://github.com/ajay-1011-git/hyper-local-flood-prediction/blob/main/frontend/src/scene/SiteScene.tsx): `frontend/src/scene/SiteScene.tsx`

### Other components

- **Operator / citizen**
- **NOAA / CWC**
- **ESP32 water sensor**
- **DEM / telemetry services**
- **Sarvam service**
- **Redis cache**
- **PostgreSQL / PostGIS**

## Connections

- Operator / citizen → React application: uses
- React application → Operations dashboard: routes to
- React application → Alert composer: routes to
- React application → Citizen view: routes to
- Operations dashboard → API client: requests data
- Alert composer → API client: requests alerts
- Citizen view → API client: requests alerts
- API client → Regional forecast API: fetches forecast
- API client → Downscale and ingest API: fetches downscaled
- API client → Simulation API: requests simulation
- API client → Damage-ranking API: requests ranking
- API client → Alert and scene API: requests alerts
- Regional forecast API → GEFS client: acquires rainfall
- Regional forecast API → River-stage client: acquires river stage
- Regional forecast API → WN2 fallback: falls back to
- GEFS client → NOAA / CWC: fetches GEFS
- River-stage client → NOAA / CWC: fetches observations
- Downscale and ingest API → Regional forecast API: fetches regional forecast
- Downscale and ingest API → DEM acquisition: obtains terrain
- Downscale and ingest API → Statistical downscaling: computes field
- Statistical downscaling → Gauge calibration: uses calibration data
- DEM acquisition → DEM / telemetry services: fetches elevation
- Gauge calibration → DEM / telemetry services: fetches telemetry
- ESP32 water sensor → Downscale and ingest API: posts readings
- Downscale and ingest API → Sensor ingestion: handles reading
- Sensor ingestion → PostgreSQL / PostGIS: persists readings
- Sensor ingestion → React application: broadcasts updates
- Simulation API → Downscale and ingest API: fetches downscaled field
- Simulation API → Precompute orchestration: starts job
- Precompute orchestration → Terrain and mesh: builds site mesh
- Precompute orchestration → Shallow-water solver: runs physics
- Precompute orchestration → SWE-GNN ensemble: runs ensemble
- Precompute orchestration → Sensor assimilation: applies observations
- Sensor assimilation → PostgreSQL / PostGIS: reads sensor data
- Simulation API → Simulation state store: loads and saves
- Damage-ranking API → Simulation API: fetches simulation
- Damage-ranking API → Exposure and risk ranking: computes ranking
- Damage-ranking API → Redis cache: caches ranking
- Alert and scene API → Simulation API: fetches simulation
- Alert and scene API → Damage-ranking API: fetches ranking
- Alert and scene API → CAP alert generation: generates CAP
- Alert and scene API → Multilingual alert text: generates translations
- Multilingual alert text → Sarvam service: requests translation
- Alert and scene API → Redis cache: caches alerts
- Alert and scene API → React application: serves scene assets
- React application → 3D site scene: renders site