# adityakamthe/jalpravah architecture

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

- Interactive diagram: https://gitdiagram.com/adityakamthe/jalpravah
- Repository: https://github.com/adityakamthe/jalpravah

## Overview

Jal Pravah is an urban flood-forecasting and safe-navigation platform for Pune, with a broader municipal map and analysis portal. The principal backend workflow is a rainfall-source chain feeding a 0–3 hour nowcast, a coupled surface/sewer simulation, and corridor hazard outputs for publication. The frontend presents nowcasts, maps, history, alerts, and routing; its Pune dashboard also computes a client-side safe route. README-described features include citizen reports, CAP alerts, and live forecast streaming, though their backend wiring is not shown in the sampled excerpts.

Main entry points: [`src/App.jsx`](https://github.com/adityakamthe/jalpravah/blob/main/src/App.jsx) (Portal application), [`backend/jalpravah/worker.py`](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/worker.py) (Nowcast worker), [`backend/jalpravah/coupling/engine.py`](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/coupling/engine.py) (Coupled simulation), [`src/components/PuneNowcastDashboard.jsx`](https://github.com/adityakamthe/jalpravah/blob/main/src/components/PuneNowcastDashboard.jsx) (Pune nowcast dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_forecast["Forecast and Hydraulics"]
  node_worker["Nowcast worker<br/>[worker.py]"]
  node_rainchain["Rain source chain<br/>[chain.py]"]
  node_radarsource["Radar sources<br/>[base.py]"]
  node_nowcast["Rain nowcast<br/>[nowcast.py]"]
  node_coupled["Coupled simulation<br/>[engine.py]"]
  node_surface["Surface flow<br/>[surface2d.py]"]
  node_inlets["Inlet exchange<br/>[inlets.py]"]
  node_hydraulics["Sewer hydraulics<br/>[hydraulics.py]"]
  node_tailwater["River tailwater<br/>[tailwater.py]"]
  node_conditioning["Terrain conditioning<br/>[conditioning.py]"]
  node_feedback["Report feedback<br/>[feedback.py]"]
  node_cap["CAP alerts<br/>[rules.py]"]
  node_sse["Forecast stream<br/>[api_server.py]"]
  node_forecaststore[("Forecast store")]
end

subgraph group_routing["Hazards and Routing"]
  node_extract["Hazard extraction<br/>[extract.py]"]
  node_tiers["Hazard tiers<br/>[hazard_tiers.py]"]
  node_router["Safe route engine<br/>[router.py]"]
  node_osmgraph["Road graph<br/>[osm_graph.py]"]
end

subgraph group_portal["Municipal Portal"]
  node_app["Portal application<br/>[App.jsx]"]
  node_dashboard["Pune nowcast dashboard"]
  node_analysis["Flood analysis map"]
  node_admin["Municipal command portal<br/>[AdminPanel.jsx]"]
  node_floodmap["3D flood map<br/>[FloodMap3D.jsx]"]
  node_alerts["Alert banner<br/>[AlertBanner.jsx]"]
  node_historical["Historical data<br/>[HistoricalData.jsx]"]
  node_citizen["Citizen reporter<br/>[CitizenReport.jsx]"]
end

subgraph group_data["Location and Integrations"]
  node_location["Location context"]
  node_search["City search"]
  node_dynamic["City analysis<br/>[dynamicLocation.js]"]
  node_terrainapi["Terrain service<br/>[bhuvan-api.js]"]
  node_floodml["Client flood model<br/>[floodML.js]"]
end

node_operator(("Municipal user"))
node_rainservices(("Rainfall providers"))
node_weather(("Weather and map services"))

node_operator -->|"uses portal"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_analysis
node_app -->|"routes to"| node_admin
node_app -->|"routes to"| node_floodmap
node_app -->|"routes to"| node_historical
node_app -->|"renders"| node_alerts
node_app -->|"refreshes model"| node_floodml
node_worker -->|"selects source"| node_rainchain
node_rainchain -->|"selects providers"| node_radarsource
node_worker -->|"generates forecast"| node_nowcast
node_nowcast -->|"reads rainfall"| node_radarsource
node_worker -->|"runs simulation"| node_coupled
node_worker -->|"conditions terrain"| node_conditioning
node_coupled -->|"updates flow"| node_surface
node_coupled -->|"uses inlet exchange"| node_inlets
node_coupled -->|"advances network"| node_hydraulics
node_hydraulics -->|"uses stage"| node_tailwater
node_worker -->|"extracts corridors"| node_extract
node_extract -->|"classifies depth"| node_tiers
node_dashboard -->|"uses hazard scale"| node_tiers
node_dashboard -->|"calculates route"| node_router
node_router -->|"uses road graph"| node_osmgraph
node_search -->|"updates location"| node_location
node_search -->|"analyzes city"| node_dynamic
node_dynamic -->|"fetches terrain"| node_terrainapi
node_dynamic -->|"queries services"| node_weather
node_search -->|"fetches forecast"| node_weather
node_analysis -->|"reads location"| node_location
node_analysis -->|"uses flood model"| node_floodml
node_admin -->|"uses flood model"| node_floodml
node_rainservices -.->|"provides rainfall"| node_rainchain
node_worker -.->|"publishes forecast"| node_forecaststore
node_citizen -.->|"submits reports"| node_feedback
node_feedback -.->|"adjusts blockage"| node_hydraulics
node_worker -.->|"broadcasts runs"| node_sse
node_sse -.->|"pushes updates"| node_dashboard
node_cap -.->|"issues warnings"| node_operator

click node_worker "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/worker.py"
click node_rainchain "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/radar/sources/chain.py"
click node_radarsource "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/radar/sources/base.py"
click node_nowcast "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/radar/nowcast.py"
click node_coupled "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/coupling/engine.py"
click node_surface "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/terrain/surface2d.py"
click node_inlets "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/coupling/inlets.py"
click node_hydraulics "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/network/hydraulics.py"
click node_tailwater "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/network/tailwater.py"
click node_conditioning "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/terrain/conditioning.py"
click node_extract "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/coupling/extract.py"
click node_tiers "https://github.com/adityakamthe/jalpravah/blob/main/scripts/hazard_tiers.py"
click node_router "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/nav/router.py"
click node_osmgraph "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/nav/osm_graph.py"
click node_app "https://github.com/adityakamthe/jalpravah/blob/main/src/App.jsx"
click node_dashboard "https://github.com/adityakamthe/jalpravah/blob/main/src/components/PuneNowcastDashboard.jsx"
click node_analysis "https://github.com/adityakamthe/jalpravah/blob/main/src/components/DeepAnalysisMap.jsx"
click node_admin "https://github.com/adityakamthe/jalpravah/blob/main/src/components/AdminPanel.jsx"
click node_floodmap "https://github.com/adityakamthe/jalpravah/blob/main/src/components/FloodMap3D.jsx"
click node_alerts "https://github.com/adityakamthe/jalpravah/blob/main/src/components/AlertBanner.jsx"
click node_historical "https://github.com/adityakamthe/jalpravah/blob/main/src/components/HistoricalData.jsx"
click node_location "https://github.com/adityakamthe/jalpravah/blob/main/src/context/LocationContext.jsx"
click node_search "https://github.com/adityakamthe/jalpravah/blob/main/src/components/GlobalSearchBar.jsx"
click node_dynamic "https://github.com/adityakamthe/jalpravah/blob/main/src/utils/dynamicLocation.js"
click node_terrainapi "https://github.com/adityakamthe/jalpravah/blob/main/src/utils/bhuvan-api.js"
click node_floodml "https://github.com/adityakamthe/jalpravah/blob/main/src/utils/floodML.js"
click node_citizen "https://github.com/adityakamthe/jalpravah/blob/main/src/components/CitizenReport.jsx"
click node_feedback "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/alerts/feedback.py"
click node_cap "https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/alerts/rules.py"
click node_sse "https://github.com/adityakamthe/jalpravah/blob/main/scripts/api_server.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_worker,node_rainchain,node_radarsource,node_nowcast,node_coupled,node_surface,node_inlets,node_hydraulics,node_tailwater,node_conditioning,node_feedback,node_cap,node_sse,node_forecaststore,node_operator toneBlue
class node_extract,node_tiers,node_router,node_osmgraph toneAmber
class node_app,node_dashboard,node_analysis,node_admin,node_floodmap,node_alerts,node_historical,node_citizen toneMint
class node_location,node_search,node_dynamic,node_terrainapi,node_floodml toneRose
class node_rainservices,node_weather toneIndigo
```

## Components

### Forecast and Hydraulics

- [Nowcast worker](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/worker.py): `backend/jalpravah/worker.py`
- [Rain source chain](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/radar/sources/chain.py): `backend/jalpravah/radar/sources/chain.py`
- [Radar sources](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/radar/sources/base.py): `backend/jalpravah/radar/sources/base.py`
- [Rain nowcast](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/radar/nowcast.py): `backend/jalpravah/radar/nowcast.py`
- [Coupled simulation](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/coupling/engine.py): `backend/jalpravah/coupling/engine.py`
- [Surface flow](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/terrain/surface2d.py): `backend/jalpravah/terrain/surface2d.py`
- [Inlet exchange](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/coupling/inlets.py): `backend/jalpravah/coupling/inlets.py`
- [Sewer hydraulics](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/network/hydraulics.py): `backend/jalpravah/network/hydraulics.py`
- [River tailwater](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/network/tailwater.py): `backend/jalpravah/network/tailwater.py`
- [Terrain conditioning](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/terrain/conditioning.py): `backend/jalpravah/terrain/conditioning.py`
- [Report feedback](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/alerts/feedback.py): `backend/jalpravah/alerts/feedback.py`
- [CAP alerts](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/alerts/rules.py): `backend/jalpravah/alerts/rules.py`
- [Forecast stream](https://github.com/adityakamthe/jalpravah/blob/main/scripts/api_server.py): `scripts/api_server.py`
- **Forecast store**

### Hazards and Routing

- [Hazard extraction](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/coupling/extract.py): `backend/jalpravah/coupling/extract.py`
- [Hazard tiers](https://github.com/adityakamthe/jalpravah/blob/main/scripts/hazard_tiers.py): `scripts/hazard_tiers.py`
- [Safe route engine](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/nav/router.py): `backend/jalpravah/nav/router.py`
- [Road graph](https://github.com/adityakamthe/jalpravah/blob/main/backend/jalpravah/nav/osm_graph.py): `backend/jalpravah/nav/osm_graph.py`

### Municipal Portal

- [Portal application](https://github.com/adityakamthe/jalpravah/blob/main/src/App.jsx): `src/App.jsx`
- [Pune nowcast dashboard](https://github.com/adityakamthe/jalpravah/blob/main/src/components/PuneNowcastDashboard.jsx): `src/components/PuneNowcastDashboard.jsx`
- [Flood analysis map](https://github.com/adityakamthe/jalpravah/blob/main/src/components/DeepAnalysisMap.jsx): `src/components/DeepAnalysisMap.jsx`
- [Municipal command portal](https://github.com/adityakamthe/jalpravah/blob/main/src/components/AdminPanel.jsx): `src/components/AdminPanel.jsx`
- [3D flood map](https://github.com/adityakamthe/jalpravah/blob/main/src/components/FloodMap3D.jsx): `src/components/FloodMap3D.jsx`
- [Alert banner](https://github.com/adityakamthe/jalpravah/blob/main/src/components/AlertBanner.jsx): `src/components/AlertBanner.jsx`
- [Historical data](https://github.com/adityakamthe/jalpravah/blob/main/src/components/HistoricalData.jsx): `src/components/HistoricalData.jsx`
- [Citizen reporter](https://github.com/adityakamthe/jalpravah/blob/main/src/components/CitizenReport.jsx): `src/components/CitizenReport.jsx`

### Location and Integrations

- [Location context](https://github.com/adityakamthe/jalpravah/blob/main/src/context/LocationContext.jsx): `src/context/LocationContext.jsx`
- [City search](https://github.com/adityakamthe/jalpravah/blob/main/src/components/GlobalSearchBar.jsx): `src/components/GlobalSearchBar.jsx`
- [City analysis](https://github.com/adityakamthe/jalpravah/blob/main/src/utils/dynamicLocation.js): `src/utils/dynamicLocation.js`
- [Terrain service](https://github.com/adityakamthe/jalpravah/blob/main/src/utils/bhuvan-api.js): `src/utils/bhuvan-api.js`
- [Client flood model](https://github.com/adityakamthe/jalpravah/blob/main/src/utils/floodML.js): `src/utils/floodML.js`

### Other components

- **Municipal user**
- **Rainfall providers**
- **Weather and map services**

## Connections

- Municipal user → Portal application: uses portal (evidence: `src/App.jsx`)
- Portal application → Pune nowcast dashboard: routes to (evidence: `src/App.jsx`)
- Portal application → Flood analysis map: routes to (evidence: `src/App.jsx`)
- Portal application → Municipal command portal: routes to (evidence: `src/App.jsx`)
- Portal application → 3D flood map: routes to (evidence: `src/App.jsx`)
- Portal application → Historical data: routes to (evidence: `src/App.jsx`)
- Portal application → Alert banner: renders (evidence: `src/App.jsx`)
- Portal application → Client flood model: refreshes model (evidence: `src/App.jsx`)
- Nowcast worker → Rain source chain: selects source (evidence: `backend/jalpravah/worker.py`)
- Rain source chain → Radar sources: selects providers (evidence: `backend/jalpravah/radar/sources/chain.py`)
- Nowcast worker → Rain nowcast: generates forecast (evidence: `backend/jalpravah/worker.py`)
- Rain nowcast → Radar sources: reads rainfall (evidence: `backend/jalpravah/radar/nowcast.py`)
- Nowcast worker → Coupled simulation: runs simulation (evidence: `backend/jalpravah/worker.py`)
- Nowcast worker → Terrain conditioning: conditions terrain (evidence: `backend/jalpravah/worker.py`)
- Coupled simulation → Surface flow: updates flow (evidence: `backend/jalpravah/coupling/engine.py`)
- Coupled simulation → Inlet exchange: uses inlet exchange (evidence: `backend/jalpravah/coupling/engine.py`)
- Coupled simulation → Sewer hydraulics: advances network (evidence: `backend/jalpravah/coupling/engine.py`)
- Sewer hydraulics → River tailwater: uses stage (evidence: `backend/jalpravah/network/hydraulics.py`)
- Nowcast worker → Hazard extraction: extracts corridors (evidence: `backend/jalpravah/worker.py`)
- Hazard extraction → Hazard tiers: classifies depth (evidence: `backend/jalpravah/coupling/extract.py`)
- Pune nowcast dashboard → Hazard tiers: uses hazard scale (evidence: `src/components/PuneNowcastDashboard.jsx`)
- Pune nowcast dashboard → Safe route engine: calculates route (evidence: `src/components/PuneNowcastDashboard.jsx`)
- Safe route engine → Road graph: uses road graph (evidence: `backend/jalpravah/nav/router.py`)
- City search → Location context: updates location (evidence: `src/components/GlobalSearchBar.jsx`)
- City search → City analysis: analyzes city (evidence: `src/components/GlobalSearchBar.jsx`)
- City analysis → Terrain service: fetches terrain (evidence: `src/utils/dynamicLocation.js`)
- City analysis → Weather and map services: queries services (evidence: `src/utils/dynamicLocation.js`)
- City search → Weather and map services: fetches forecast (evidence: `src/components/GlobalSearchBar.jsx`)
- Flood analysis map → Location context: reads location (evidence: `src/components/DeepAnalysisMap.jsx`)
- Flood analysis map → Client flood model: uses flood model (evidence: `src/components/DeepAnalysisMap.jsx`)
- Municipal command portal → Client flood model: uses flood model (evidence: `src/components/AdminPanel.jsx`)
- Rainfall providers → Rain source chain: provides rainfall
- Nowcast worker → Forecast store: publishes forecast (evidence: `backend/jalpravah/worker.py`)
- Citizen reporter → Report feedback: submits reports (evidence: `README.md`)
- Report feedback → Sewer hydraulics: adjusts blockage (evidence: `README.md`)
- Nowcast worker → Forecast stream: broadcasts runs (evidence: `README.md`)
- Forecast stream → Pune nowcast dashboard: pushes updates (evidence: `README.md`)
- CAP alerts → Municipal user: issues warnings (evidence: `README.md`)