# chaitanyakumarai/pond_catchment_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/chaitanyakumarai/pond_catchment_analysis
- Repository: https://github.com/chaitanyakumarai/pond_catchment_analysis

## Overview

AquaTerrain AI is a web-based pond-site and catchment planner. A user draws a parcel or uploads contour data; the API parses the input, builds or reuses terrain data, analyzes drainage and pond suitability, then returns mapped pond, catchment, and water-volume results. The README also documents whole-map analysis, coverage, plots/3D terrain, and a clustered runtime. The excerpts establish the main modules and load-balancer behavior; detailed API-to-analysis calls and several UI requests are not fully shown, so those links rely on README statements where applicable.

Main entry points: [`app.py`](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/app.py) (Flask API), [`static/app.js`](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/static/app.js) (Interactive map), [`terrain_analyzer.py`](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py) (Parcel hydrology), [`cluster/pond_lb.go`](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/cluster/pond_lb.go) (Go load balancer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Map experience"]
  node_map_ui["Interactive map<br/>[app.js]"]
  node_map_template["Map page<br/>[index.html]"]
end

subgraph group_api["Analysis API"]
  node_api_service["Flask API<br/>[app.py]"]
  node_model_cache[("Model and result cache<br/>[app.py]")]
  node_contour_parser["KML/KMZ parser<br/>[kml_parser.py]"]
end

subgraph group_hydrology["Terrain analysis"]
  node_terrain_model["Terrain model"]
  node_parcel_analysis["Parcel hydrology"]
  node_pond_results["Pond and catchment results"]
  node_terrain_visuals["Terrain plots and mesh"]
end

subgraph group_runtime["Cluster runtime"]
  node_load_balancer["Go load balancer<br/>[pond_lb.go]"]
  node_worker_service["Analysis workers<br/>[gunicorn.conf.py]"]
end

node_farmer(("Land planner"))
node_openstreetmap["OpenStreetMap tiles"]
node_browser(("Browser user"))

node_browser -->|"uses"| node_map_ui
node_map_ui -->|"requests analysis"| node_api_service
node_api_service -->|"renders"| node_map_template
node_api_service -->|"parses contours"| node_contour_parser
node_api_service -->|"builds terrain model"| node_terrain_model
node_api_service -->|"analyzes parcel"| node_parcel_analysis
node_parcel_analysis -.->|"uses terrain model"| node_terrain_model
node_parcel_analysis -->|"returns results"| node_pond_results
node_api_service -->|"caches results"| node_model_cache
node_api_service -->|"serves plots and mesh"| node_terrain_visuals
node_map_ui -.->|"loads map tiles"| node_openstreetmap
node_load_balancer -->|"proxies requests"| node_worker_service
node_worker_service -.->|"serves API"| node_api_service
node_load_balancer -->|"checks health"| node_worker_service
node_browser -->|"uses cluster entry"| node_load_balancer

click node_map_ui "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/static/app.js"
click node_map_template "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/templates/index.html"
click node_api_service "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/app.py"
click node_model_cache "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/app.py"
click node_contour_parser "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/kml_parser.py"
click node_terrain_model "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py"
click node_parcel_analysis "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py"
click node_pond_results "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py"
click node_terrain_visuals "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py"
click node_load_balancer "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/cluster/pond_lb.go"
click node_worker_service "https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/cluster/gunicorn.conf.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_map_ui,node_map_template,node_browser toneBlue
class node_api_service,node_model_cache,node_contour_parser toneAmber
class node_terrain_model,node_parcel_analysis,node_pond_results,node_terrain_visuals toneMint
class node_load_balancer,node_worker_service toneRose
class node_farmer,node_openstreetmap toneIndigo
```

## Components

### Map experience

- [Interactive map](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/static/app.js): `static/app.js`
- [Map page](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/templates/index.html): `templates/index.html`

### Analysis API

- [Flask API](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/app.py): `app.py`
- [Model and result cache](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/app.py): `app.py`
- [KML/KMZ parser](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/kml_parser.py): `kml_parser.py`

### Terrain analysis

- [Terrain model](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py): `terrain_analyzer.py`
- [Parcel hydrology](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py): `terrain_analyzer.py`
- [Pond and catchment results](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py): `terrain_analyzer.py`
- [Terrain plots and mesh](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/terrain_analyzer.py): `terrain_analyzer.py`

### Cluster runtime

- [Go load balancer](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/cluster/pond_lb.go): `cluster/pond_lb.go`
- [Analysis workers](https://github.com/chaitanyakumarai/pond_catchment_analysis/blob/main/cluster/gunicorn.conf.py): `cluster/gunicorn.conf.py`

### Other components

- **Land planner**
- **OpenStreetMap tiles**
- **Browser user**

## Connections

- Browser user → Interactive map: uses (evidence: `README.md`)
- Interactive map → Flask API: requests analysis (evidence: `README.md`)
- Flask API → Map page: renders (evidence: `app.py`)
- Flask API → KML/KMZ parser: parses contours (evidence: `app.py`)
- Flask API → Terrain model: builds terrain model (evidence: `README.md`)
- Flask API → Parcel hydrology: analyzes parcel (evidence: `README.md`)
- Parcel hydrology → Terrain model: uses terrain model (evidence: `terrain_analyzer.py`)
- Parcel hydrology → Pond and catchment results: returns results (evidence: `README.md`)
- Flask API → Model and result cache: caches results (evidence: `app.py`)
- Flask API → Terrain plots and mesh: serves plots and mesh (evidence: `README.md`)
- Interactive map → OpenStreetMap tiles: loads map tiles (evidence: `static/app.js`)
- Go load balancer → Analysis workers: proxies requests (evidence: `cluster/pond_lb.go`)
- Analysis workers → Flask API: serves API (evidence: `README.md`)
- Go load balancer → Analysis workers: checks health (evidence: `cluster/pond_lb.go`)
- Browser user → Go load balancer: uses cluster entry (evidence: `README.md`)
