How ajay-1011-git/hyper-local-flood-prediction works
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: client.ts API client · stage4/routes.py Alert and scene API · stage1b/routes.py Downscale and ingest API · App.tsx React application
Components 34
Forecast acquisition
- Regional forecast API
backend/stage1a/routes.py - GEFS client
backend/stage1a/gefs/client.py - River-stage client
backend/stage1a/cwc/client.py - WN2 fallback
backend/stage1a/wn2mini/loader.py
Site inputs
- Downscale and ingest API
backend/stage1b/routes.py - DEM acquisition
backend/stage1b/dem/client.py - Statistical downscaling
backend/stage1b/downscaling/orchestrator.py - Gauge calibration
backend/stage1b/tnwrd/client.py - Sensor ingestion
backend/stage1b/sensor/ingest.py
Flood simulation
- Simulation API
backend/stage2/routes.py - Precompute orchestration
backend/stage2/precompute.py - Terrain and mesh
backend/stage2/terrain/site_transform.py - Shallow-water solver
backend/stage2/solver/shallow_water_solver.py - SWE-GNN ensemble
backend/stage2/gnn/ensemble.py - Sensor assimilation
backend/stage2/assimilation/ghost_cell_update.py - Simulation state store
backend/stage2/site_state_store.py
Risk and alerts
- Damage-ranking API
backend/stage3/routes.py - Exposure and risk ranking
backend/stage3/ranking/risk_ranking.py - Alert and scene API
backend/stage4/routes.py - CAP alert generation
backend/stage4/alerts/cap_generator.py - Multilingual alert text
backend/stage4/alerts/multilingual.py
User experience
- React application
frontend/src/App.tsx - API client
frontend/src/api/client.ts - Operations dashboard
frontend/src/pages/Dashboard.tsx - Alert composer
frontend/src/pages/AlertComposer.tsx - Citizen view
frontend/src/pages/CitizenView.tsx - 3D site scene
frontend/src/scene/SiteScene.tsx
Other components
- Operator / citizen
- NOAA / CWC
- ESP32 water sensor
- DEM / telemetry services
- Sarvam service
- Redis cache
- PostgreSQL / PostGIS
Connections 46
- 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