# keshavkhandelwal13/matsya-flood-detector architecture

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

- Interactive diagram: https://gitdiagram.com/keshavkhandelwal13/matsya-flood-detector
- Repository: https://github.com/keshavkhandelwal13/matsya-flood-detector

## Overview

This repository provides a flood-risk dashboard backed by rainfall and river forecasts plus geospatial risk mapping. The user-facing flow is dashboard requests to Flask data endpoints, which read generated forecast/history files; a separate run action executes the model jobs, including the mapper. The mapper’s evidenced orchestration loads and clips geospatial inputs, computes threat and vulnerability, then classifies risk and produces map/report outputs. Source excerpts do not establish the detector’s internal script sequence or all frontend-to-API wiring, so those links are omitted or marked unverified.

Main entry points: [`backend/flood_mapper/run_analysis.py`](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/run_analysis.py) (Mapper analysis), [`backend/app.py`](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/app.py) (Flask API), [`backend/flood_mapper/mapper/combine.py`](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/combine.py) (Risk classification), [`backend/run_model.py`](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/run_model.py) (Model runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Flood dashboard<br/>[script.js]"]
end

subgraph group_service["API and orchestration"]
  node_api["Flask API<br/>[app.py]"]
  node_runner["Model runner<br/>[run_model.py]"]
end

subgraph group_forecast["Forecast models"]
  node_rain_generator["Rainfall generator<br/>[generator.py]"]
  node_rain_model["Rainfall prediction"]
  node_detector_suite["Flood detector suite"]
  node_flood_prediction["Flood probability<br/>[predict_flood.py]"]
  node_forecast_files[("Forecast and history CSVs")]
end

subgraph group_mapping["Geospatial risk mapping"]
  node_mapper_entry["Mapper analysis<br/>[run_analysis.py]"]
  node_geo_inputs["Geospatial inputs<br/>[inputs.py]"]
  node_threat["Threat scoring<br/>[threat.py]"]
  node_vulnerability["Vulnerability raster<br/>[vulnerability.py]"]
  node_risk_combine["Risk classification<br/>[combine.py]"]
end

subgraph group_outputs["Risk products"]
  node_risk_products["Risk map and report"]
end

node_visitor(("Dashboard user"))

node_visitor -->|"views"| node_dashboard
node_dashboard -.->|"requests data"| node_api
node_api -->|"reads forecast data"| node_forecast_files
node_api -->|"runs generator"| node_rain_generator
node_api -->|"runs detector"| node_detector_suite
node_api -->|"runs analysis"| node_mapper_entry
node_runner -->|"runs generator"| node_rain_generator
node_runner -->|"runs suite"| node_detector_suite
node_runner -->|"runs analysis"| node_mapper_entry
node_rain_model -->|"writes predictions"| node_forecast_files
node_flood_prediction -->|"writes forecast"| node_forecast_files
node_mapper_entry -->|"loads and clips"| node_geo_inputs
node_mapper_entry -->|"calculates threat"| node_threat
node_mapper_entry -->|"calculates vulnerability"| node_vulnerability
node_mapper_entry -->|"combines and classifies"| node_risk_combine
node_risk_combine -->|"generates outputs"| node_risk_products
node_geo_inputs -.->|"supplies clipped data"| node_risk_combine
node_vulnerability -.->|"supplies vulnerability"| node_risk_combine

click node_dashboard "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/frontend/script.js"
click node_api "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/app.py"
click node_runner "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/run_model.py"
click node_rain_generator "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/csv_generator/generator.py"
click node_rain_model "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/csv_generator/combine_generator.py"
click node_detector_suite "https://github.com/keshavkhandelwal13/matsya-flood-detector/tree/main/backend/flood_detector"
click node_flood_prediction "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_detector/predict_flood.py"
click node_forecast_files "https://github.com/keshavkhandelwal13/matsya-flood-detector/tree/main/backend/flood_detector"
click node_mapper_entry "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/run_analysis.py"
click node_geo_inputs "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/inputs.py"
click node_threat "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/threat.py"
click node_vulnerability "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/vulnerability.py"
click node_risk_combine "https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/combine.py"
click node_risk_products "https://github.com/keshavkhandelwal13/matsya-flood-detector/tree/main/backend/flood_mapper/output"

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_dashboard,node_visitor toneBlue
class node_api,node_runner toneAmber
class node_rain_generator,node_rain_model,node_detector_suite,node_flood_prediction,node_forecast_files toneMint
class node_mapper_entry,node_geo_inputs,node_threat,node_vulnerability,node_risk_combine toneRose
class node_risk_products toneIndigo
```

## Components

### Dashboard

- [Flood dashboard](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/frontend/script.js): `frontend/script.js`

### API and orchestration

- [Flask API](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/app.py): `backend/app.py`
- [Model runner](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/run_model.py): `backend/run_model.py`

### Forecast models

- [Rainfall generator](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/csv_generator/generator.py): `backend/csv_generator/generator.py`
- [Rainfall prediction](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/csv_generator/combine_generator.py): `backend/csv_generator/combine_generator.py`
- [Flood detector suite](https://github.com/keshavkhandelwal13/matsya-flood-detector/tree/main/backend/flood_detector): `backend/flood_detector`
- [Flood probability](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_detector/predict_flood.py): `backend/flood_detector/predict_flood.py`
- [Forecast and history CSVs](https://github.com/keshavkhandelwal13/matsya-flood-detector/tree/main/backend/flood_detector): `backend/flood_detector`

### Geospatial risk mapping

- [Mapper analysis](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/run_analysis.py): `backend/flood_mapper/run_analysis.py`
- [Geospatial inputs](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/inputs.py): `backend/flood_mapper/mapper/inputs.py`
- [Threat scoring](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/threat.py): `backend/flood_mapper/mapper/threat.py`
- [Vulnerability raster](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/vulnerability.py): `backend/flood_mapper/mapper/vulnerability.py`
- [Risk classification](https://github.com/keshavkhandelwal13/matsya-flood-detector/blob/main/backend/flood_mapper/mapper/combine.py): `backend/flood_mapper/mapper/combine.py`

### Risk products

- [Risk map and report](https://github.com/keshavkhandelwal13/matsya-flood-detector/tree/main/backend/flood_mapper/output): `backend/flood_mapper/output`

### Other components

- **Dashboard user**

## Connections

- Dashboard user → Flood dashboard: views (evidence: `frontend/script.js`)
- Flood dashboard → Flask API: requests data
- Flask API → Forecast and history CSVs: reads forecast data (evidence: `backend/app.py`)
- Flask API → Rainfall generator: runs generator (evidence: `backend/app.py`)
- Flask API → Flood detector suite: runs detector (evidence: `backend/app.py`)
- Flask API → Mapper analysis: runs analysis (evidence: `backend/app.py`)
- Model runner → Rainfall generator: runs generator (evidence: `backend/run_model.py`)
- Model runner → Flood detector suite: runs suite (evidence: `backend/run_model.py`)
- Model runner → Mapper analysis: runs analysis (evidence: `backend/run_model.py`)
- Rainfall prediction → Forecast and history CSVs: writes predictions (evidence: `backend/csv_generator/combine_generator.py`)
- Flood probability → Forecast and history CSVs: writes forecast (evidence: `backend/flood_detector/predict_flood.py`)
- Mapper analysis → Geospatial inputs: loads and clips (evidence: `backend/flood_mapper/run_analysis.py`)
- Mapper analysis → Threat scoring: calculates threat (evidence: `backend/flood_mapper/run_analysis.py`)
- Mapper analysis → Vulnerability raster: calculates vulnerability (evidence: `backend/flood_mapper/run_analysis.py`)
- Mapper analysis → Risk classification: combines and classifies (evidence: `backend/flood_mapper/run_analysis.py`)
- Risk classification → Risk map and report: generates outputs (evidence: `backend/flood_mapper/mapper/combine.py`)
- Geospatial inputs → Risk classification: supplies clipped data
- Vulnerability raster → Risk classification: supplies vulnerability
