# paradise-theking/eswatini-water-stress-ml architecture

> Architecture diagram of the GitHub repository paradise-theking/eswatini-water-stress-ml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paradise-theking/eswatini-water-stress-ml
- Repository: https://github.com/paradise-theking/eswatini-water-stress-ml

## Overview

The repository is a hydroclimatic research and forecasting application: environmental observations feed a one-month-ahead Ridge forecast, exposed through a FastAPI API and TypeScript dashboard. It also serves historical indices and separate climate-balance and satellite surface-water context. The dashboard includes demonstration subscription flows. Edges reflect README statements or shown imports/calls; sampled excerpts are partial, so unsampled details and some UI interactions are not inferred.

Main entry points: [`backend/main.py`](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/main.py) (FastAPI routes), [`frontend/src/main.ts`](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/frontend/src/main.ts) (Forecast and risk dashboard), [`backend/live_forecast.py`](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/live_forecast.py) (Live forecast generation), [`backend/water_availability.py`](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/water_availability.py) (Climate balance and surface water)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Environmental data"]
  node_ingest["Earth observation ingestion<br/>[data_ingestion.py]"]
  node_historicdata["Research dataset"]
  node_history["Live observed history<br/>[live_history.py]"]
end

subgraph group_forecast["Forecasting"]
  node_model["Trained Ridge model"]
  node_features["Forecast features"]
  node_liveforecast["Live forecast generation<br/>[live_forecast.py]"]
end

subgraph group_api["API and water risk"]
  node_apiapp["FastAPI routes<br/>[main.py]"]
  node_availability["Climate balance and surface water"]
end

subgraph group_ui["Dashboard and services"]
  node_dashboard["Forecast and risk dashboard<br/>[main.ts]"]
  node_firebasecfg["Firebase setup<br/>[firebaseConfig.ts]"]
end

node_user(("Water manager"))
node_earth["Earth Engine"]
node_weather["Weather provider"]
node_firestore[("Firebase Firestore")]
node_browser(("Web browser"))

node_browser -->|"uses"| node_dashboard
node_user -.->|"views"| node_dashboard
node_dashboard -->|"requests"| node_apiapp
node_apiapp -->|"generates"| node_liveforecast
node_liveforecast -->|"fetches observations"| node_ingest
node_liveforecast -->|"builds input"| node_features
node_liveforecast -->|"loads and predicts"| node_model
node_apiapp -->|"reads history"| node_historicdata
node_apiapp -->|"fetches live history"| node_history
node_history -->|"fetches observations"| node_ingest
node_apiapp -->|"serves risk endpoints"| node_availability
node_availability -.->|"requests forecast data"| node_weather
node_availability -.->|"processes satellite imagery"| node_earth
node_ingest -->|"queries observations"| node_earth
node_dashboard -->|"imports database"| node_firebasecfg
node_firebasecfg -->|"initializes client"| node_firestore
node_dashboard -->|"reads and writes subscriptions"| node_firestore

click node_ingest "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/data_ingestion.py"
click node_historicdata "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/data/processed/mnjoli_water_stress_ml_dataset.csv"
click node_model "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/models/water_stress_ridge.joblib"
click node_features "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/feature_engineering.py"
click node_liveforecast "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/live_forecast.py"
click node_history "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/live_history.py"
click node_apiapp "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/main.py"
click node_availability "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/water_availability.py"
click node_dashboard "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/frontend/src/main.ts"
click node_firebasecfg "https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/frontend/src/firebaseConfig.ts"

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_ingest,node_historicdata,node_history,node_browser toneBlue
class node_model,node_features,node_liveforecast,node_firestore toneAmber
class node_apiapp,node_availability toneMint
class node_dashboard,node_firebasecfg toneRose
class node_user,node_earth,node_weather toneIndigo
```

## Components

### Environmental data

- [Earth observation ingestion](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/data_ingestion.py): `backend/data_ingestion.py`
- [Research dataset](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/data/processed/mnjoli_water_stress_ml_dataset.csv): `data/processed/mnjoli_water_stress_ml_dataset.csv`
- [Live observed history](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/live_history.py): `backend/live_history.py`

### Forecasting

- [Trained Ridge model](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/models/water_stress_ridge.joblib): `models/water_stress_ridge.joblib`
- [Forecast features](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/feature_engineering.py): `backend/feature_engineering.py`
- [Live forecast generation](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/live_forecast.py): `backend/live_forecast.py`

### API and water risk

- [FastAPI routes](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/main.py): `backend/main.py`
- [Climate balance and surface water](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/backend/water_availability.py): `backend/water_availability.py`

### Dashboard and services

- [Forecast and risk dashboard](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/frontend/src/main.ts): `frontend/src/main.ts`
- [Firebase setup](https://github.com/paradise-theking/eswatini-water-stress-ml/blob/main/frontend/src/firebaseConfig.ts): `frontend/src/firebaseConfig.ts`

### Other components

- **Water manager**
- **Earth Engine**
- **Weather provider**
- **Firebase Firestore**
- **Web browser**

## Connections

- Web browser → Forecast and risk dashboard: uses (evidence: `frontend/src/main.ts`)
- Water manager → Forecast and risk dashboard: views
- Forecast and risk dashboard → FastAPI routes: requests (evidence: `frontend/src/main.ts`)
- FastAPI routes → Live forecast generation: generates (evidence: `backend/main.py`)
- Live forecast generation → Earth observation ingestion: fetches observations (evidence: `backend/live_forecast.py`)
- Live forecast generation → Forecast features: builds input (evidence: `backend/live_forecast.py`)
- Live forecast generation → Trained Ridge model: loads and predicts (evidence: `backend/live_forecast.py`)
- FastAPI routes → Research dataset: reads history (evidence: `backend/main.py`)
- FastAPI routes → Live observed history: fetches live history (evidence: `backend/main.py`)
- Live observed history → Earth observation ingestion: fetches observations (evidence: `backend/live_history.py`)
- FastAPI routes → Climate balance and surface water: serves risk endpoints (evidence: `backend/main.py`)
- Climate balance and surface water → Weather provider: requests forecast data
- Climate balance and surface water → Earth Engine: processes satellite imagery
- Earth observation ingestion → Earth Engine: queries observations (evidence: `backend/data_ingestion.py`)
- Forecast and risk dashboard → Firebase setup: imports database (evidence: `frontend/src/main.ts`)
- Firebase setup → Firebase Firestore: initializes client (evidence: `frontend/src/firebaseConfig.ts`)
- Forecast and risk dashboard → Firebase Firestore: reads and writes subscriptions (evidence: `frontend/src/main.ts`)