# amkkoussay/rain2risk architecture

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

- Interactive diagram: https://gitdiagram.com/amkkoussay/rain2risk
- Repository: https://github.com/amkkoussay/rain2risk

## Overview

Rain2Risk is a web-based flood-risk screening map. A user selects a location, the browser submits it to the API, the backend gathers forecast and geographic inputs, scores grid cells, and returns results for map and risk-panel display. The graph emphasizes this live workflow and the documented global terrain, land-cover, and OpenStreetMap capabilities. The sampled sources support the analysis and provider wiring shown; unsampled API and feature modules are represented only where their paths and role are supported by the tree and documented architecture.

Main entry points: [`backend/geo/global_data.py`](https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/global_data.py) (GIS orchestration), [`backend/api/analyze.py`](https://github.com/amkkoussay/rain2risk/blob/main/backend/api/analyze.py) (Analysis API), [`frontend/app.js`](https://github.com/amkkoussay/rain2risk/blob/main/frontend/app.js) (Map interface), [`backend/main.py`](https://github.com/amkkoussay/rain2risk/blob/main/backend/main.py) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Map experience"]
  node_frontend["Map interface<br/>[app.js]"]
  node_tiles["Base map tiles"]
  node_osmtiles["OpenStreetMap tiles"]
end

subgraph group_api["API workflow"]
  node_server["HTTP server<br/>[main.py]"]
  node_analyze["Analysis API<br/>[analyze.py]"]
  node_health["Health API<br/>[health.py]"]
end

subgraph group_geodata["Geographic data"]
  node_grid["Grid builder<br/>[grid.py]"]
  node_globaldata["GIS orchestration<br/>[global_data.py]"]
  node_dem["Elevation provider<br/>[dem.py]"]
  node_worldcover["Land-cover provider<br/>[worldcover.py]"]
  node_osm["OSM provider<br/>[osm.py]"]
  node_features["Cell features<br/>[features.py]"]
  node_elevationservice["Open-Meteo elevation"]
  node_worldcoverservice["ESA WorldCover"]
  node_overpass["Overpass API"]
end

subgraph group_risk["Risk analysis"]
  node_scoring["Risk scoring<br/>[scoring.py]"]
  node_normalization["Factor normalization<br/>[normalization.py]"]
  node_thresholds["Weights and levels<br/>[thresholds.py]"]
end

subgraph group_weather["Weather data"]
  node_weatherapi["Weather API<br/>[weather.py]"]
  node_weatherclient["Forecast client<br/>[client.py]"]
  node_weatherparser["Forecast parser<br/>[parser.py]"]
  node_openweather["OpenWeather"]
end

node_user(("Map user"))

node_user -->|"selects location"| node_frontend
node_frontend -->|"POSTs coordinates"| node_server
node_server -->|"dispatches analysis"| node_analyze
node_server -->|"dispatches health check"| node_health
node_server -->|"serves interface"| node_frontend
node_frontend -->|"loads base tiles"| node_osmtiles
node_analyze -->|"requests grid data"| node_globaldata
node_analyze -->|"requests forecast"| node_weatherapi
node_analyze -->|"scores each cell"| node_scoring
node_globaldata -->|"builds cells"| node_grid
node_globaldata -->|"fetches elevations"| node_dem
node_globaldata -->|"fetches land cover"| node_worldcover
node_globaldata -->|"fetches map features"| node_osm
node_globaldata -->|"assembles cell features"| node_features
node_dem -->|"requests elevation"| node_elevationservice
node_worldcover -->|"requests cover tiles"| node_worldcoverservice
node_osm -->|"queries map data"| node_overpass
node_weatherapi -->|"fetches forecast"| node_weatherclient
node_weatherclient -->|"requests forecast"| node_openweather
node_weatherapi -->|"parses payload"| node_weatherparser
node_scoring -->|"normalizes factors"| node_normalization
node_scoring -->|"uses weights and levels"| node_thresholds
node_analyze -->|"returns score and grid"| node_frontend

click node_frontend "https://github.com/amkkoussay/rain2risk/blob/main/frontend/app.js"
click node_server "https://github.com/amkkoussay/rain2risk/blob/main/backend/main.py"
click node_analyze "https://github.com/amkkoussay/rain2risk/blob/main/backend/api/analyze.py"
click node_health "https://github.com/amkkoussay/rain2risk/blob/main/backend/api/health.py"
click node_grid "https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/grid.py"
click node_globaldata "https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/global_data.py"
click node_dem "https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/dem.py"
click node_worldcover "https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/worldcover.py"
click node_osm "https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/osm.py"
click node_features "https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/features.py"
click node_weatherapi "https://github.com/amkkoussay/rain2risk/blob/main/backend/api/weather.py"
click node_weatherclient "https://github.com/amkkoussay/rain2risk/blob/main/backend/weather/client.py"
click node_weatherparser "https://github.com/amkkoussay/rain2risk/blob/main/backend/weather/parser.py"
click node_scoring "https://github.com/amkkoussay/rain2risk/blob/main/backend/risk/scoring.py"
click node_normalization "https://github.com/amkkoussay/rain2risk/blob/main/backend/risk/normalization.py"
click node_thresholds "https://github.com/amkkoussay/rain2risk/blob/main/backend/risk/thresholds.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_frontend,node_tiles,node_osmtiles,node_user toneBlue
class node_server,node_analyze,node_health toneAmber
class node_grid,node_globaldata,node_dem,node_worldcover,node_osm,node_features,node_elevationservice,node_worldcoverservice,node_overpass toneMint
class node_scoring,node_normalization,node_thresholds toneRose
class node_weatherapi,node_weatherclient,node_weatherparser,node_openweather toneIndigo
```

## Components

### Map experience

- [Map interface](https://github.com/amkkoussay/rain2risk/blob/main/frontend/app.js): `frontend/app.js`
- **Base map tiles**
- **OpenStreetMap tiles**

### API workflow

- [HTTP server](https://github.com/amkkoussay/rain2risk/blob/main/backend/main.py): `backend/main.py`
- [Analysis API](https://github.com/amkkoussay/rain2risk/blob/main/backend/api/analyze.py): `backend/api/analyze.py`
- [Health API](https://github.com/amkkoussay/rain2risk/blob/main/backend/api/health.py): `backend/api/health.py`

### Geographic data

- [Grid builder](https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/grid.py): `backend/geo/grid.py`
- [GIS orchestration](https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/global_data.py): `backend/geo/global_data.py`
- [Elevation provider](https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/dem.py): `backend/geo/dem.py`
- [Land-cover provider](https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/worldcover.py): `backend/geo/worldcover.py`
- [OSM provider](https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/osm.py): `backend/geo/osm.py`
- [Cell features](https://github.com/amkkoussay/rain2risk/blob/main/backend/geo/features.py): `backend/geo/features.py`
- **Open-Meteo elevation**
- **ESA WorldCover**
- **Overpass API**

### Risk analysis

- [Risk scoring](https://github.com/amkkoussay/rain2risk/blob/main/backend/risk/scoring.py): `backend/risk/scoring.py`
- [Factor normalization](https://github.com/amkkoussay/rain2risk/blob/main/backend/risk/normalization.py): `backend/risk/normalization.py`
- [Weights and levels](https://github.com/amkkoussay/rain2risk/blob/main/backend/risk/thresholds.py): `backend/risk/thresholds.py`

### Weather data

- [Weather API](https://github.com/amkkoussay/rain2risk/blob/main/backend/api/weather.py): `backend/api/weather.py`
- [Forecast client](https://github.com/amkkoussay/rain2risk/blob/main/backend/weather/client.py): `backend/weather/client.py`
- [Forecast parser](https://github.com/amkkoussay/rain2risk/blob/main/backend/weather/parser.py): `backend/weather/parser.py`
- **OpenWeather**

### Other components

- **Map user**

## Connections

- Map user → Map interface: selects location
- Map interface → HTTP server: POSTs coordinates
- HTTP server → Analysis API: dispatches analysis
- HTTP server → Health API: dispatches health check
- HTTP server → Map interface: serves interface
- Map interface → OpenStreetMap tiles: loads base tiles
- Analysis API → GIS orchestration: requests grid data
- Analysis API → Weather API: requests forecast
- Analysis API → Risk scoring: scores each cell
- GIS orchestration → Grid builder: builds cells
- GIS orchestration → Elevation provider: fetches elevations
- GIS orchestration → Land-cover provider: fetches land cover
- GIS orchestration → OSM provider: fetches map features
- GIS orchestration → Cell features: assembles cell features
- Elevation provider → Open-Meteo elevation: requests elevation
- Land-cover provider → ESA WorldCover: requests cover tiles
- OSM provider → Overpass API: queries map data
- Weather API → Forecast client: fetches forecast
- Forecast client → OpenWeather: requests forecast
- Weather API → Forecast parser: parses payload
- Risk scoring → Factor normalization: normalizes factors
- Risk scoring → Weights and levels: uses weights and levels
- Analysis API → Map interface: returns score and grid