Water Hub — Pan-African Satellite Water Monitoring Platform

A full-stack platform for monitoring water resources across 55 African countries using multi-mission satellite remote sensing. Tracks 543 water bodies (lakes, reservoirs, rivers, wetlands) with data from 17+ satellite missions including SWOT, Sentinel-3, ICESat-2, GRACE/GRACE-FO, and NISAR.

Features

• 543 Water Bodies — Lakes, reservoirs, rivers, wetlands, and crater lakes across 6 African regions with real coordinates and polygons
• 55 Country Profiles — Unified country-level water dashboards with lakes, rivers, soil moisture, water quality, storage, and GRACE TWS
• Multi-Mission Altimetry — 17 satellite missions (SWOT, Sentinel-3, ICESat-2, Jason, etc.) with combined water surface elevation time series
• NISAR Soil Moisture — L-band SAR soil moisture coverage for 54 African countries with heatmap overlays
• Water Quality — Turbidity, chlorophyll-a, CDOM, Secchi depth, TSM from Sentinel-2 with real-time alerting
• Transboundary Basins — 8 major shared basins (Nile, Congo, Niger, etc.), 24 shared water bodies, country-specific water budgets
• SWOT Lake Integration — 21 African lakes with KaRIn-derived WSE, area, and storage change from SWOT satellite
• GRACE/GRACE-FO — Total water storage anomalies decomposed by component (surface, soil, groundwater)
• DAHITI Validation — Lake and river altimetry validation against TU Munich DAHITI reference data
• Real-Time Alerting — Threshold-based water quality scanning (algal blooms, turbidity, eutrophication, sedimentation, drinking water safety)
• Hydrology Model — Precipitation, evapotranspiration, water balance, drought indices (SPI/SPEI)
• Machine Learning — Water quality prediction (RF/XGBoost), U-Net segmentation, LSTM forecasting
• RBAC & Audit Logging — 5-level role hierarchy (viewer to super_admin), 17 permissions, request-level audit trail
• Policy Briefs — AI-powered policy document generation via Claude API
• Interactive Maps — Leaflet-based dashboards with GeoJSON overlays, NISAR heatmaps, basin boundaries
• Data Export — CSV, GeoJSON, Shapefile formats

Tech Stack

Layer	Technology
Frontend	React 18, Vite 5, Leaflet, Recharts, TailwindCSS
Backend	Python FastAPI, 444 API endpoints across 20+ router modules
Satellites	SWOT, Sentinel-3, ICESat-2, GRACE-FO, NISAR, Sentinel-2, Landsat, SMAP, MODIS
ETL	APScheduler (6-hour cycles), NASA CMR, Hydrocron, DAHITI APIs
ML	scikit-learn, XGBoost, h5py (ICESat-2 HDF5)
LLM	Anthropic Claude API (policy briefs)
Auth	JWT + RBAC (5 roles, 17 permissions)

Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+

Development Setup

Backend:

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Frontend:

cd frontend
cp .env.example .env     # first time only — see env vars below
npm install
npm run dev

Access:

• Frontend: http://localhost:5173 (or :3000 via demo_restart.sh)
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/api/docs

Frontend env vars (frontend/.env, see frontend/.env.example):

Variable	Default	Purpose
VITE_API_URL	(empty)	Backend base URL. Leave empty in dev — vite.config.js proxies /api → http://localhost:8000. Set to an absolute URL in production.
VITE_USE_DEMO_API	true	true routes waterService.js calls to /api/demo/*; false uses production endpoints. Demo mode is required for hyperspectral, InSAR, cyanobacteria, and advanced hydrology features.
VITE_SENTRY_DSN	(empty)	Sentry DSN. Empty in dev keeps logger.error/warn console-only; set in prod to forward via logger.setSink() (see src/lib/sentry.js).
VITE_APP_VERSION	(empty)	Optional release tag Sentry attaches to captured events (e.g. a git sha).

Convenience: demo_restart.sh

For demos or quick restarts, the repo ships a helper that starts both servers on the standard demo ports (backend :8000, frontend :3000) and tails their output to /tmp/water_hub_*.log:

bash demo_restart.sh            # start or restart both
bash demo_restart.sh status     # show what's running + health
bash demo_restart.sh stop       # kill both

Uses uvicorn --workers 2 for the backend and npm run dev --host 0.0.0.0 for the frontend. Open http://localhost:3000 when it reports ready.

API Overview

The backend provides 444 endpoints across 20+ router modules:

Module	Prefix	Description
Country Profiles	/api/country	Unified water profiles for 55 African countries
Water Bodies	/api/demo/water-bodies	543 water bodies with metadata and time series
Altimetry	/api/altimetry	Multi-mission satellite altimetry, DAHITI validation
Transboundary	/api/transboundary	8 basins, discharge, water budgets, shared waters
SWOT Lakes	/api/swot	SWOT satellite lake catalog, WSE, area, storage
NISAR	/api/nisar	L-band SAR soil moisture for 54 countries
Alerts	/api/alerts	Real-time water quality alerting engine
Auth & RBAC	/api/auth	JWT auth, role management, audit log
GRACE	/api/demo/grace	Terrestrial water storage anomalies
Hydrology	/api/demo/hydrology	Precipitation, ET, water balance, drought
Sentinel-2	/api/demo/sentinel2	Water quality parameters
Sentinel-1	/api/demo/sentinel1	SAR flood mapping
ICESat-2	/api/icesat2	Laser altimetry water levels
Landsat	/api/demo/landsat	40-year water extent archive
SMAP	/api/demo/smap	Soil moisture monitoring
ML	/api/ml	Prediction, segmentation, forecasting
Export	/api/export	CSV, GeoJSON, Shapefile export
Policy Brief	/api/policy-brief	AI-powered policy documents
ETL	/api/etl	Pipeline status and manual triggers
Satellite	/api/satellite	Flood detection, water extent, storage

Full interactive documentation at /api/docs (Swagger UI).

Testing

Backend:

cd backend
source venv/bin/activate
pytest tests/ -q

Frontend:

cd frontend
npm test               # vitest (unit + component, jsdom)
npm run test:watch     # vitest watch mode
npm run test:e2e       # playwright (visual regression, real browser)
npm run test:e2e:update  # regenerate screenshot baselines after an intentional UI change

First-time Playwright setup: npx playwright install chromium (and, on Linux, sudo npx playwright install-deps chromium for shared libs). CI does this automatically.

Project Structure

Water_Hub/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI entry point
│   │   ├── routers/             # 20+ API router modules
│   │   │   ├── country.py       # Country water profiles
│   │   │   ├── transboundary.py # Basin & shared waters
│   │   │   ├── alerts.py        # Water quality alerting
│   │   │   ├── swot.py          # SWOT lake integration
│   │   │   ├── altimetry.py     # Multi-mission altimetry + DAHITI
│   │   │   ├── auth.py          # JWT + RBAC + audit log
│   │   │   └── demo/            # Modular demo data endpoints
│   │   ├── services/            # Business logic
│   │   │   ├── country_water_service.py
│   │   │   ├── alert_engine.py
│   │   │   ├── swot_lake.py
│   │   │   ├── rbac.py
│   │   │   └── audit_log.py
│   │   ├── middleware/           # Audit logging middleware
│   │   ├── etl/                 # APScheduler ETL pipelines
│   │   └── data/                # JSON caches, GeoJSON, altimetry
│   └── tests/
├── frontend/
│   ├── src/
│   │   ├── components/          # 20 React component folders
│   │   │   ├── Hubs/            # CountryWaterHub
│   │   │   ├── Transboundary/   # Basin & shared waters UI
│   │   │   ├── Alerts/          # Water quality alerts
│   │   │   ├── Map/             # Leaflet maps + NISAR overlays
│   │   │   └── ...
│   │   ├── services/            # API client (60+ methods)
│   │   └── App.jsx              # Route definitions
│   └── package.json
└── README.md

Data Sources

Source	Provider	Resolution	Use
SWOT KaRIn	NASA/CNES	250m	Lake WSE, area, storage
Sentinel-3 SRAL	ESA	Along-track	River/lake water levels
Sentinel-2 MSI	ESA	10m	Water quality
Sentinel-1 SAR	ESA	10m	Flood mapping
ICESat-2 ATL13	NASA	14m track	Water levels
GRACE/GRACE-FO	NASA/GFZ	~300km	Total water storage
NISAR L-band	NASA/ISRO	12m	Soil moisture
Landsat 8/9	NASA/USGS	30m	Long-term water extent
SMAP	NASA	9km	Soil moisture
GPM IMERG	NASA	0.1deg	Precipitation
CHIRPS	UCSB	0.05deg	Precipitation
ERA5-Land	ECMWF	0.1deg	Meteorology
MODIS	NASA	500m-1km	Vegetation, ET
JRC GSW	EC-JRC	30m	Surface water history
DAHITI	TU Munich	Per-target	Validation reference
FAO Aquastat	FAO	National	Water budget reference

License

Internal use — Ethiopian Ministry of Water and Energy.