# baran-oz/dam-flood-simulator architecture

> Architecture diagram of the GitHub repository baran-oz/dam-flood-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baran-oz/dam-flood-simulator
- Repository: https://github.com/baran-oz/dam-flood-simulator

## Overview

Dam Flood Simulator is a browser-based exploration tool: users draw a dam axis on a map, choose terrain and dam settings, then receive an estimated flood extent, area, volume, depths, and leak status. App coordinates the interface and analysis; analysis loads terrain tiles, grows its grid as needed, and calls the reservoir engine. The map and side panel present the result, with an optional profile and explanatory dialog. Relationships for unsampled modules rely on the SOURCE INDEX or README; external terrain and basemap requests are documented, but their detailed runtime wiring was not sampled.

Main entry points: [`frontend/src/App.jsx`](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/App.jsx) (App coordinator), [`frontend/src/components/SidePanel.jsx`](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/SidePanel.jsx) (Settings and results), [`frontend/src/lib/analysis.js`](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/analysis.js) (Analysis orchestration), [`frontend/src/lib/geotiffSources.js`](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/geotiffSources.js) (GeoTIFF providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interface"]
  node_app["App coordinator<br/>[App.jsx]"]
  node_error["Error boundary<br/>[ErrorBoundary.jsx]"]
  node_sidepanel["Settings and results<br/>[SidePanel.jsx]"]
  node_terrainpicker["Terrain picker<br/>[TerrainPicker.jsx]"]
  node_profile["Dam profile<br/>[DamProfile.jsx]"]
  node_about["Method dialog<br/>[AboutDialog.jsx]"]
end

subgraph group_simulation["Flood analysis"]
  node_analysis["Analysis orchestration<br/>[analysis.js]"]
  node_reservoir["Reservoir engine<br/>[reservoir.js]"]
  node_overlay["Flood overlay renderer<br/>[overlay.js]"]
  node_geo["Web Mercator helpers<br/>[geo.js]"]
end

subgraph group_terrain["Terrain data"]
  node_sources["Terrain source catalog<br/>[sources.js]"]
  node_terrainloader["Raster tile loader<br/>[terrain.js]"]
  node_geotiff["GeoTIFF providers<br/>[geotiffSources.js]"]
  node_rastertiles["Raster tile support<br/>[rasterTiles.js]"]
end

subgraph group_mapping["Map display"]
  node_map["Interactive map<br/>[MapView.jsx]"]
  node_basemaps["Basemap providers<br/>[basemaps.js]"]
end

node_user(("Dam simulator user"))
node_terrainservices[("Terrain data services")]
node_mapservices[("Basemap tile services")]

node_user -->|"sets simulation"| node_app
node_app -->|"renders controls"| node_sidepanel
node_app -->|"renders map"| node_map
node_app -->|"renders dialog"| node_about
node_app -->|"runs analysis"| node_analysis
node_app -->|"renders flood overlay"| node_overlay
node_sidepanel -->|"renders picker"| node_terrainpicker
node_sidepanel -->|"renders profile"| node_profile
node_sidepanel -->|"measures dam"| node_geo
node_terrainpicker -->|"selects source"| node_sources
node_analysis -->|"simulates flooding"| node_reservoir
node_analysis -->|"converts coordinates"| node_geo
node_analysis -->|"uses tile loader"| node_sources
node_sources -->|"creates RGB loaders"| node_terrainloader
node_sources -->|"creates DEM loaders"| node_geotiff
node_geotiff -->|"uses raster support"| node_rastertiles
node_geotiff -->|"uses terrain plumbing"| node_terrainloader
node_terrainloader -->|"uses tile size"| node_geo
node_terrainloader -.->|"fetches elevation data"| node_terrainservices
node_geotiff -.->|"fetches elevation data"| node_terrainservices
node_map -->|"creates basemap"| node_basemaps
node_map -.->|"displays map tiles"| node_mapservices
node_error -->|"catches UI errors"| node_app

click node_app "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/App.jsx"
click node_error "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/ErrorBoundary.jsx"
click node_sidepanel "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/SidePanel.jsx"
click node_terrainpicker "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/TerrainPicker.jsx"
click node_profile "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/DamProfile.jsx"
click node_about "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/AboutDialog.jsx"
click node_analysis "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/analysis.js"
click node_reservoir "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/reservoir.js"
click node_overlay "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/overlay.js"
click node_geo "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/geo.js"
click node_sources "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/sources.js"
click node_terrainloader "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/terrain.js"
click node_geotiff "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/geotiffSources.js"
click node_rastertiles "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/rasterTiles.js"
click node_map "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/MapView.jsx"
click node_basemaps "https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/basemaps.js"

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_app,node_error,node_sidepanel,node_terrainpicker,node_profile,node_about,node_user toneBlue
class node_analysis,node_reservoir,node_overlay,node_geo,node_terrainservices,node_mapservices toneAmber
class node_sources,node_terrainloader,node_geotiff,node_rastertiles toneMint
class node_map,node_basemaps toneRose
```

## Components

### User interface

- [App coordinator](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Error boundary](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/ErrorBoundary.jsx): `frontend/src/components/ErrorBoundary.jsx`
- [Settings and results](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/SidePanel.jsx): `frontend/src/components/SidePanel.jsx`
- [Terrain picker](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/TerrainPicker.jsx): `frontend/src/components/TerrainPicker.jsx`
- [Dam profile](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/DamProfile.jsx): `frontend/src/components/DamProfile.jsx`
- [Method dialog](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/AboutDialog.jsx): `frontend/src/components/AboutDialog.jsx`

### Flood analysis

- [Analysis orchestration](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/analysis.js): `frontend/src/lib/analysis.js`
- [Reservoir engine](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/reservoir.js): `frontend/src/lib/reservoir.js`
- [Flood overlay renderer](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/overlay.js): `frontend/src/lib/overlay.js`
- [Web Mercator helpers](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/geo.js): `frontend/src/lib/geo.js`

### Terrain data

- [Terrain source catalog](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/sources.js): `frontend/src/lib/sources.js`
- [Raster tile loader](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/terrain.js): `frontend/src/lib/terrain.js`
- [GeoTIFF providers](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/geotiffSources.js): `frontend/src/lib/geotiffSources.js`
- [Raster tile support](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/rasterTiles.js): `frontend/src/lib/rasterTiles.js`

### Map display

- [Interactive map](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/components/MapView.jsx): `frontend/src/components/MapView.jsx`
- [Basemap providers](https://github.com/baran-oz/dam-flood-simulator/blob/master/frontend/src/lib/basemaps.js): `frontend/src/lib/basemaps.js`

### Other components

- **Dam simulator user**
- **Terrain data services**
- **Basemap tile services**

## Connections

- Dam simulator user → App coordinator: sets simulation (evidence: `README.md`)
- App coordinator → Settings and results: renders controls (evidence: `frontend/src/App.jsx`)
- App coordinator → Interactive map: renders map (evidence: `frontend/src/App.jsx`)
- App coordinator → Method dialog: renders dialog (evidence: `frontend/src/App.jsx`)
- App coordinator → Analysis orchestration: runs analysis (evidence: `frontend/src/App.jsx`)
- App coordinator → Flood overlay renderer: renders flood overlay (evidence: `frontend/src/App.jsx`)
- Settings and results → Terrain picker: renders picker (evidence: `frontend/src/components/SidePanel.jsx`)
- Settings and results → Dam profile: renders profile (evidence: `frontend/src/components/SidePanel.jsx`)
- Settings and results → Web Mercator helpers: measures dam (evidence: `frontend/src/components/SidePanel.jsx`)
- Terrain picker → Terrain source catalog: selects source (evidence: `frontend/src/components/TerrainPicker.jsx`)
- Analysis orchestration → Reservoir engine: simulates flooding (evidence: `frontend/src/lib/analysis.js`)
- Analysis orchestration → Web Mercator helpers: converts coordinates (evidence: `frontend/src/lib/analysis.js`)
- Analysis orchestration → Terrain source catalog: uses tile loader (evidence: `frontend/src/App.jsx`)
- Terrain source catalog → Raster tile loader: creates RGB loaders (evidence: `frontend/src/lib/sources.js`)
- Terrain source catalog → GeoTIFF providers: creates DEM loaders (evidence: `frontend/src/lib/sources.js`)
- GeoTIFF providers → Raster tile support: uses raster support (evidence: `frontend/src/lib/geotiffSources.js`)
- GeoTIFF providers → Raster tile loader: uses terrain plumbing (evidence: `frontend/src/lib/geotiffSources.js`)
- Raster tile loader → Web Mercator helpers: uses tile size (evidence: `frontend/src/lib/terrain.js`)
- Raster tile loader → Terrain data services: fetches elevation data (evidence: `README.md`)
- GeoTIFF providers → Terrain data services: fetches elevation data (evidence: `README.md`)
- Interactive map → Basemap providers: creates basemap (evidence: `frontend/src/components/MapView.jsx`)
- Interactive map → Basemap tile services: displays map tiles (evidence: `README.md`)
- Error boundary → App coordinator: catches UI errors (evidence: `frontend/src/main.jsx`)
