# alpinistpanda/flood-twin-lab architecture

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

- Interactive diagram: https://gitdiagram.com/alpinistpanda/flood-twin-lab
- Repository: https://github.com/alpinistpanda/flood-twin-lab

## Overview

This repository is a teaching flood-twin web application: a browser presents replayed Tambaram sensor readings, alerts and maps, alongside static 100-year flood-scenario layers. The principal workflow is sensor data → API replay → shared browser feed and level classification → table or interactive map; map users can also inspect sensor history and explore flood exposure over time. The API, map, sensor classification and flood-layer behavior are evidenced in sampled source. Feed internals and some UI wiring were not sampled, so those connections are omitted or marked unverified.

Main entry points: [`app/src/routes/maplibre/+page.svelte`](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/routes/maplibre/%2Bpage.svelte) (Map page route), [`app/src/lib/MapLibreMap.svelte`](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/MapLibreMap.svelte) (MapLibre view), [`app/src/lib/scenario.js`](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/scenario.js) (Flood layer logic), [`app/src/lib/feed.svelte.js`](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/feed.svelte.js) (Shared live feed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Sensor replay API"]
  node_api_service["Sensor API<br/>[main.py]"]
  node_sensor_data["Sensor readings"]
end

subgraph group_client["Web app and feed"]
  node_layout["App shell<br/>[+layout.svelte]"]
  node_feed["Shared live feed<br/>[feed.svelte.js]"]
  node_classification["Level classification<br/>[sensors.js]"]
  node_sensor_page["Sensor table<br/>[+page.svelte]"]
end

subgraph group_maps["Map and flood views"]
  node_map_route["Map page route<br/>[+page.svelte]"]
  node_map_page["Map layout<br/>[MapPage.svelte]"]
  node_map_view["MapLibre view<br/>[MapLibreMap.svelte]"]
  node_layers["Layer selection<br/>[layers.svelte.js]"]
  node_sensor_detail["Sensor detail popup"]
  node_sensor_chart["History charts<br/>[SensorChart.svelte]"]
  node_time_bar["Flood time slider"]
end

subgraph group_scenario["Flood scenario data"]
  node_scenario["Flood layer logic<br/>[scenario.js]"]
  node_scenario_files["Flood model files"]
end

node_resident(("App user"))
node_map_tiles["Basemap tiles"]

node_resident -->|"opens app"| node_layout
node_api_service -->|"loads readings"| node_sensor_data
node_layout -->|"starts feed"| node_feed
node_feed -.->|"fetches feed"| node_api_service
node_sensor_page -->|"reads shared state"| node_feed
node_sensor_page -->|"uses levels"| node_classification
node_map_route -->|"renders"| node_map_page
node_map_route -->|"renders"| node_map_view
node_map_route -->|"passes sensor data"| node_feed
node_map_route -->|"passes layer state"| node_layers
node_map_route -->|"shows when enabled"| node_time_bar
node_map_view -->|"mounts on click"| node_sensor_detail
node_sensor_detail -.->|"displays history"| node_sensor_chart
node_map_view -->|"calls layer and query functions"| node_scenario
node_time_bar -->|"loads time metadata"| node_scenario
node_scenario -->|"reads flood layers"| node_scenario_files
node_scenario -->|"uses level colours"| node_classification
node_map_view -->|"loads basemap style"| node_map_tiles

click node_api_service "https://github.com/alpinistpanda/flood-twin-lab/blob/main/api/main.py"
click node_sensor_data "https://github.com/alpinistpanda/flood-twin-lab/tree/main/data"
click node_layout "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/routes/%2Blayout.svelte"
click node_feed "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/feed.svelte.js"
click node_classification "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/sensors.js"
click node_sensor_page "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/routes/sensors/%2Bpage.svelte"
click node_map_route "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/routes/maplibre/%2Bpage.svelte"
click node_map_page "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/MapPage.svelte"
click node_map_view "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/MapLibreMap.svelte"
click node_layers "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/layers.svelte.js"
click node_sensor_detail "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/SensorDetail.svelte"
click node_sensor_chart "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/SensorChart.svelte"
click node_time_bar "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/FloodTimeBar.svelte"
click node_scenario "https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/scenario.js"
click node_scenario_files "https://github.com/alpinistpanda/flood-twin-lab/tree/main/app/static/layers"

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_api_service,node_sensor_data,node_resident toneBlue
class node_layout,node_feed,node_classification,node_sensor_page toneAmber
class node_map_route,node_map_page,node_map_view,node_layers,node_sensor_detail,node_sensor_chart,node_time_bar toneMint
class node_scenario,node_scenario_files toneRose
class node_map_tiles toneIndigo
```

## Components

### Sensor replay API

- [Sensor API](https://github.com/alpinistpanda/flood-twin-lab/blob/main/api/main.py): `api/main.py`
- [Sensor readings](https://github.com/alpinistpanda/flood-twin-lab/tree/main/data): `data`

### Web app and feed

- [App shell](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/routes/%2Blayout.svelte): `app/src/routes/+layout.svelte`
- [Shared live feed](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/feed.svelte.js): `app/src/lib/feed.svelte.js`
- [Level classification](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/sensors.js): `app/src/lib/sensors.js`
- [Sensor table](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/routes/sensors/%2Bpage.svelte): `app/src/routes/sensors/+page.svelte`

### Map and flood views

- [Map page route](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/routes/maplibre/%2Bpage.svelte): `app/src/routes/maplibre/+page.svelte`
- [Map layout](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/MapPage.svelte): `app/src/lib/MapPage.svelte`
- [MapLibre view](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/MapLibreMap.svelte): `app/src/lib/MapLibreMap.svelte`
- [Layer selection](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/layers.svelte.js): `app/src/lib/layers.svelte.js`
- [Sensor detail popup](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/SensorDetail.svelte): `app/src/lib/SensorDetail.svelte`
- [History charts](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/SensorChart.svelte): `app/src/lib/SensorChart.svelte`
- [Flood time slider](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/FloodTimeBar.svelte): `app/src/lib/FloodTimeBar.svelte`

### Flood scenario data

- [Flood layer logic](https://github.com/alpinistpanda/flood-twin-lab/blob/main/app/src/lib/scenario.js): `app/src/lib/scenario.js`
- [Flood model files](https://github.com/alpinistpanda/flood-twin-lab/tree/main/app/static/layers): `app/static/layers`

### Other components

- **App user**
- **Basemap tiles**

## Connections

- App user → App shell: opens app (evidence: `README.md`)
- Sensor API → Sensor readings: loads readings (evidence: `api/main.py`)
- App shell → Shared live feed: starts feed (evidence: `app/src/routes/+layout.svelte`)
- Shared live feed → Sensor API: fetches feed (evidence: `README.md`)
- Sensor table → Shared live feed: reads shared state (evidence: `app/src/routes/sensors/+page.svelte`)
- Sensor table → Level classification: uses levels (evidence: `app/src/routes/sensors/+page.svelte`)
- Map page route → Map layout: renders (evidence: `app/src/routes/maplibre/+page.svelte`)
- Map page route → MapLibre view: renders (evidence: `app/src/routes/maplibre/+page.svelte`)
- Map page route → Shared live feed: passes sensor data (evidence: `app/src/routes/maplibre/+page.svelte`)
- Map page route → Layer selection: passes layer state (evidence: `app/src/routes/maplibre/+page.svelte`)
- Map page route → Flood time slider: shows when enabled (evidence: `app/src/routes/maplibre/+page.svelte`)
- MapLibre view → Sensor detail popup: mounts on click (evidence: `app/src/lib/MapLibreMap.svelte`)
- Sensor detail popup → History charts: displays history (evidence: `README.md`)
- MapLibre view → Flood layer logic: calls layer and query functions (evidence: `app/src/lib/MapLibreMap.svelte`)
- Flood time slider → Flood layer logic: loads time metadata (evidence: `app/src/lib/FloodTimeBar.svelte`)
- Flood layer logic → Flood model files: reads flood layers (evidence: `app/src/lib/scenario.js`)
- Flood layer logic → Level classification: uses level colours (evidence: `app/src/lib/scenario.js`)
- MapLibre view → Basemap tiles: loads basemap style (evidence: `app/src/lib/MapLibreMap.svelte`)
