# aditya-pm/climate-twin architecture

> Architecture diagram of the GitHub repository aditya-pm/climate-twin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aditya-pm/climate-twin
- Repository: https://github.com/aditya-pm/climate-twin

## Overview

ClimateTwin is a Chennai urban-heat digital twin: the web app explores grid cells, explains vulnerability, compares mitigation scenarios, and presents citywide priorities and model methodology. Its main runtime path is the browser’s API client to FastAPI, which serves a Twin built from grid data and an LST model; the Twin computes vulnerability, scenario effects, and recommendations. The README documents the product capabilities and HTTP boundary; source excerpts support the backend dependencies and selected UI composition. Unshown frontend data wiring is not expanded beyond that boundary.

Main entry points: [`backend/climatetwin/engine.py`](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/engine.py) (Twin analytics), [`web/components/simulator/Simulator.tsx`](https://github.com/aditya-pm/climate-twin/blob/main/web/components/simulator/Simulator.tsx) (Scenario simulator), [`backend/climatetwin/data.py`](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/data.py) (Dataset loader), [`backend/climatetwin/geo.py`](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/geo.py) (Chennai geography)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["ClimateTwin web app"]
  node_landing["City landing<br/>[Landing.tsx]"]
  node_explorer["Grid explorer<br/>[Explorer.tsx]"]
  node_cell["Cell diagnosis<br/>[CellPanel.tsx]"]
  node_simulator["Scenario simulator<br/>[Simulator.tsx]"]
  node_compare["Before-after map<br/>[CompareMap.tsx]"]
  node_insights["City insights<br/>[Insights.tsx]"]
  node_methodology["Model methodology<br/>[Methodology.tsx]"]
  node_map["Interactive map<br/>[MapView.tsx]"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and twin"]
  node_service["FastAPI service<br/>[app.py]"]
  node_twin["Twin analytics<br/>[engine.py]"]
end

subgraph group_data["Grid data"]
  node_loader["Dataset loader<br/>[data.py]"]
  node_realgrid["Real-data pipeline<br/>[realdata.py]"]
  node_synthetic["Synthetic observations<br/>[synth.py]"]
  node_geography["Chennai geography<br/>[geo.py]"]
end

subgraph group_analysis["Climate analysis"]
  node_model["LST and SHAP<br/>[model.py]"]
end

node_resident(("City user"))

node_resident -->|"opens app"| node_landing
node_resident -->|"explores cells"| node_explorer
node_resident -->|"sets scenario"| node_simulator
node_resident -->|"reviews priorities"| node_insights
node_resident -->|"reviews method"| node_methodology
node_explorer -->|"selects cell"| node_cell
node_simulator -->|"renders comparison"| node_compare
node_simulator -->|"renders map"| node_map
node_client -->|"requests API"| node_service
node_service -->|"serves twin results"| node_twin
node_twin -->|"loads dataset"| node_loader
node_twin -->|"uses model"| node_model
node_twin -->|"uses grid bounds"| node_geography
node_loader -->|"loads fallback"| node_synthetic
node_synthetic -->|"uses geography"| node_geography
node_realgrid -->|"uses grid"| node_geography
node_loader -.->|"selects real data"| node_realgrid

click node_landing "https://github.com/aditya-pm/climate-twin/blob/main/web/components/landing/Landing.tsx"
click node_explorer "https://github.com/aditya-pm/climate-twin/blob/main/web/components/explorer/Explorer.tsx"
click node_cell "https://github.com/aditya-pm/climate-twin/blob/main/web/components/explorer/CellPanel.tsx"
click node_simulator "https://github.com/aditya-pm/climate-twin/blob/main/web/components/simulator/Simulator.tsx"
click node_compare "https://github.com/aditya-pm/climate-twin/blob/main/web/components/simulator/CompareMap.tsx"
click node_insights "https://github.com/aditya-pm/climate-twin/blob/main/web/components/insights/Insights.tsx"
click node_methodology "https://github.com/aditya-pm/climate-twin/blob/main/web/components/methodology/Methodology.tsx"
click node_map "https://github.com/aditya-pm/climate-twin/blob/main/web/components/MapView.tsx"
click node_client "https://github.com/aditya-pm/climate-twin/blob/main/web/lib/api.ts"
click node_service "https://github.com/aditya-pm/climate-twin/blob/main/backend/app.py"
click node_twin "https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/engine.py"
click node_model "https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/model.py"
click node_loader "https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/data.py"
click node_realgrid "https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/realdata.py"
click node_synthetic "https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/synth.py"
click node_geography "https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/geo.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_landing,node_explorer,node_cell,node_simulator,node_compare,node_insights,node_methodology,node_map,node_client,node_resident toneBlue
class node_service,node_twin toneAmber
class node_loader,node_realgrid,node_synthetic,node_geography toneMint
class node_model toneRose
```

## Components

### ClimateTwin web app

- [City landing](https://github.com/aditya-pm/climate-twin/blob/main/web/components/landing/Landing.tsx): `web/components/landing/Landing.tsx`
- [Grid explorer](https://github.com/aditya-pm/climate-twin/blob/main/web/components/explorer/Explorer.tsx): `web/components/explorer/Explorer.tsx`
- [Cell diagnosis](https://github.com/aditya-pm/climate-twin/blob/main/web/components/explorer/CellPanel.tsx): `web/components/explorer/CellPanel.tsx`
- [Scenario simulator](https://github.com/aditya-pm/climate-twin/blob/main/web/components/simulator/Simulator.tsx): `web/components/simulator/Simulator.tsx`
- [Before-after map](https://github.com/aditya-pm/climate-twin/blob/main/web/components/simulator/CompareMap.tsx): `web/components/simulator/CompareMap.tsx`
- [City insights](https://github.com/aditya-pm/climate-twin/blob/main/web/components/insights/Insights.tsx): `web/components/insights/Insights.tsx`
- [Model methodology](https://github.com/aditya-pm/climate-twin/blob/main/web/components/methodology/Methodology.tsx): `web/components/methodology/Methodology.tsx`
- [Interactive map](https://github.com/aditya-pm/climate-twin/blob/main/web/components/MapView.tsx): `web/components/MapView.tsx`
- [API client](https://github.com/aditya-pm/climate-twin/blob/main/web/lib/api.ts): `web/lib/api.ts`

### API and twin

- [FastAPI service](https://github.com/aditya-pm/climate-twin/blob/main/backend/app.py): `backend/app.py`
- [Twin analytics](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/engine.py): `backend/climatetwin/engine.py`

### Grid data

- [Dataset loader](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/data.py): `backend/climatetwin/data.py`
- [Real-data pipeline](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/realdata.py): `backend/climatetwin/realdata.py`
- [Synthetic observations](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/synth.py): `backend/climatetwin/synth.py`
- [Chennai geography](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/geo.py): `backend/climatetwin/geo.py`

### Climate analysis

- [LST and SHAP](https://github.com/aditya-pm/climate-twin/blob/main/backend/climatetwin/model.py): `backend/climatetwin/model.py`

### Other components

- **City user**

## Connections

- City user → City landing: opens app (evidence: `README.md`)
- City user → Grid explorer: explores cells (evidence: `README.md`)
- City user → Scenario simulator: sets scenario (evidence: `README.md`)
- City user → City insights: reviews priorities (evidence: `README.md`)
- City user → Model methodology: reviews method (evidence: `README.md`)
- Grid explorer → Cell diagnosis: selects cell (evidence: `web/components/explorer/Explorer.tsx`)
- Scenario simulator → Before-after map: renders comparison (evidence: `web/components/simulator/Simulator.tsx`)
- Scenario simulator → Interactive map: renders map (evidence: `web/components/simulator/Simulator.tsx`)
- API client → FastAPI service: requests API (evidence: `README.md`)
- FastAPI service → Twin analytics: serves twin results (evidence: `backend/app.py`)
- Twin analytics → Dataset loader: loads dataset (evidence: `backend/climatetwin/engine.py`)
- Twin analytics → LST and SHAP: uses model (evidence: `backend/climatetwin/engine.py`)
- Twin analytics → Chennai geography: uses grid bounds (evidence: `backend/climatetwin/engine.py`)
- Dataset loader → Synthetic observations: loads fallback (evidence: `backend/climatetwin/data.py`)
- Synthetic observations → Chennai geography: uses geography (evidence: `backend/climatetwin/synth.py`)
- Real-data pipeline → Chennai geography: uses grid (evidence: `backend/climatetwin/realdata.py`)
- Dataset loader → Real-data pipeline: selects real data
