# rishu07368/urban-flood-nowcasting architecture

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

- Interactive diagram: https://gitdiagram.com/rishu07368/urban-flood-nowcasting
- Repository: https://github.com/rishu07368/urban-flood-nowcasting

## Overview

This prototype turns synthetic rainfall forecasts and simulated drainage observations into a three-hour flood-risk nowcast, exposed through a FastAPI service and GIS map. The risk-map path orchestrates rainfall loading, SWMM input generation and execution, result extraction, sensor comparison, scoring, and GeoJSON construction; the API also exposes sensor, rainfall, and full-simulation endpoints. README-documented Leaflet timeline, legend, and map capabilities are represented, but frontend source was not sampled, so its API interactions are not asserted. SWMM model and rainfall data are supported by the tree and README; finer internal connections are limited to excerpted code.

Main entry points: [`backend/risk_mapper.py`](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/risk_mapper.py) (Forecast risk orchestration), [`backend/api.py`](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/api.py) (FastAPI routes), [`run_simulation.py`](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/run_simulation.py) (Rainfall injection and SWMM), [`frontend/index.html`](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/frontend/index.html) (GIS map and timeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Forecast and sensors"]
  node_rainfall["Rainfall forecast"]
  node_sensor["Sensor simulator<br/>[sensors.py]"]
end

subgraph group_model["Hydraulic simulation"]
  node_inputfile["SWMM base model<br/>[urban_flood.inp]"]
  node_runner["Rainfall injection and SWMM<br/>[run_simulation.py]"]
  node_results["SWMM result extraction<br/>[extract_result.py]"]
  node_output["SWMM output<br/>[flood_output.out]"]
  node_pipeline["Simulation endpoint pipeline<br/>[simulation.py]"]
end

subgraph group_risk["Risk and mapping"]
  node_mapper["Forecast risk orchestration<br/>[risk_mapper.py]"]
  node_scoring["Risk scoring and summary<br/>[flood_engine.py]"]
  node_geojson["Risk GeoJSON<br/>[risk_mapper.py]"]
end

subgraph group_service["API and map"]
  node_api["FastAPI routes<br/>[api.py]"]
  node_frontend["GIS map and timeline<br/>[index.html]"]
end

node_user(("Map user"))
node_tiles["OpenStreetMap tiles"]

node_api -->|"serves"| node_frontend
node_user -.->|"views"| node_frontend
node_frontend -.->|"requests"| node_api
node_frontend -.->|"loads tiles"| node_tiles
node_api -->|"builds payload"| node_sensor
node_sensor -->|"reads forecast"| node_rainfall
node_api -->|"loads forecast"| node_rainfall
node_api -->|"runs pipeline"| node_pipeline
node_pipeline -->|"runs model"| node_runner
node_pipeline -->|"extracts results"| node_results
node_runner -->|"loads forecast"| node_rainfall
node_runner -->|"copies model"| node_inputfile
node_runner -->|"writes output"| node_output
node_results -->|"reads results"| node_output
node_api -->|"requests risk"| node_mapper
node_mapper -->|"loads forecast"| node_rainfall
node_mapper -->|"updates and runs"| node_runner
node_mapper -->|"extracts metrics"| node_results
node_mapper -->|"gets observations"| node_sensor
node_mapper -->|"scores zones"| node_scoring
node_mapper -->|"builds features"| node_geojson
node_api -->|"returns map"| node_geojson

click node_rainfall "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/data/rainfall_nowcast.json"
click node_sensor "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/sensors.py"
click node_inputfile "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/swmm/urban_flood.inp"
click node_runner "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/run_simulation.py"
click node_results "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/extract_result.py"
click node_output "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/swmm/flood_output.out"
click node_pipeline "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/simulation.py"
click node_mapper "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/risk_mapper.py"
click node_scoring "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/flood_engine.py"
click node_geojson "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/risk_mapper.py"
click node_api "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/api.py"
click node_frontend "https://github.com/rishu07368/urban-flood-nowcasting/blob/main/frontend/index.html"

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_rainfall,node_sensor,node_user toneBlue
class node_inputfile,node_runner,node_results,node_output,node_pipeline toneAmber
class node_mapper,node_scoring,node_geojson toneMint
class node_api,node_frontend toneRose
class node_tiles toneIndigo
```

## Components

### Forecast and sensors

- [Rainfall forecast](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/data/rainfall_nowcast.json): `data/rainfall_nowcast.json`
- [Sensor simulator](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/sensors.py): `backend/sensors.py`

### Hydraulic simulation

- [SWMM base model](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/swmm/urban_flood.inp): `swmm/urban_flood.inp`
- [Rainfall injection and SWMM](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/run_simulation.py): `run_simulation.py`
- [SWMM result extraction](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/extract_result.py): `extract_result.py`
- [SWMM output](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/swmm/flood_output.out): `swmm/flood_output.out`
- [Simulation endpoint pipeline](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/simulation.py): `backend/simulation.py`

### Risk and mapping

- [Forecast risk orchestration](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/risk_mapper.py): `backend/risk_mapper.py`
- [Risk scoring and summary](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/flood_engine.py): `backend/flood_engine.py`
- [Risk GeoJSON](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/risk_mapper.py): `backend/risk_mapper.py`

### API and map

- [FastAPI routes](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/backend/api.py): `backend/api.py`
- [GIS map and timeline](https://github.com/rishu07368/urban-flood-nowcasting/blob/main/frontend/index.html): `frontend/index.html`

### Other components

- **Map user**
- **OpenStreetMap tiles**

## Connections

- FastAPI routes → GIS map and timeline: serves (evidence: `backend/api.py`)
- Map user → GIS map and timeline: views (evidence: `README.md`)
- GIS map and timeline → FastAPI routes: requests (evidence: `README.md`)
- GIS map and timeline → OpenStreetMap tiles: loads tiles (evidence: `README.md`)
- FastAPI routes → Sensor simulator: builds payload (evidence: `backend/api.py`)
- Sensor simulator → Rainfall forecast: reads forecast (evidence: `backend/sensors.py`)
- FastAPI routes → Rainfall forecast: loads forecast (evidence: `backend/api.py`)
- FastAPI routes → Simulation endpoint pipeline: runs pipeline (evidence: `backend/api.py`)
- Simulation endpoint pipeline → Rainfall injection and SWMM: runs model (evidence: `backend/simulation.py`)
- Simulation endpoint pipeline → SWMM result extraction: extracts results (evidence: `backend/simulation.py`)
- Rainfall injection and SWMM → Rainfall forecast: loads forecast (evidence: `run_simulation.py`)
- Rainfall injection and SWMM → SWMM base model: copies model (evidence: `run_simulation.py`)
- Rainfall injection and SWMM → SWMM output: writes output (evidence: `run_simulation.py`)
- SWMM result extraction → SWMM output: reads results (evidence: `extract_result.py`)
- FastAPI routes → Forecast risk orchestration: requests risk (evidence: `backend/api.py`)
- Forecast risk orchestration → Rainfall forecast: loads forecast (evidence: `backend/risk_mapper.py`)
- Forecast risk orchestration → Rainfall injection and SWMM: updates and runs (evidence: `backend/risk_mapper.py`)
- Forecast risk orchestration → SWMM result extraction: extracts metrics (evidence: `backend/risk_mapper.py`)
- Forecast risk orchestration → Sensor simulator: gets observations (evidence: `backend/risk_mapper.py`)
- Forecast risk orchestration → Risk scoring and summary: scores zones (evidence: `backend/risk_mapper.py`)
- Forecast risk orchestration → Risk GeoJSON: builds features (evidence: `backend/risk_mapper.py`)
- FastAPI routes → Risk GeoJSON: returns map (evidence: `backend/api.py`)
