TreeHacks Monorepo: Hazard Map + Forecast + Voice + Data Harvester

This repo contains several hackathon-sized projects that work together (and can also be run independently):

• A California hazard map frontend (React + Vite + Mapbox) with hazard overlays + a hyper-local weather probe panel.
• A hazard aggregator backend (Flask) that normalizes public hazard feeds into GeoJSON endpoints for the map.
• A GPU forecast API (FastAPI) that runs NVIDIA Earth2Studio FCN3 forecasts and writes NetCDF outputs.
• A Twilio call center voice bridge (FastAPI) for NVIDIA PersonaPlex running on an NVIDIA DGX.
• A WPS harvester (Python) that crawls Apple wloc nearby responses into a resumable Postgres-backed dataset, plus an AWS load-test harness.

Repo Layout

Path	What it is	Default port
frontend/	Map UI (Vite + React + Mapbox GL)	5173 (Vite dev)
backend/	Flask API for hazards + weather probe	5001
forecast/	FastAPI forecast service + models/scripts	8000
callcenter/	Twilio Media Streams bridge to PersonaPlex	5050
wps-harvester/	Apple WPS crawler + exports + AWS tooling	(CLI)

Quickstart (Map + Hazard API)

1) Backend (Flask)

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
python run.py

Backend runs at http://localhost:5001.

Key endpoints:

• GET /healthz
• GET /api/v1/hazards?... (aggregated GeoJSON)
• GET /api/v1/weather/probe?lat=...&lon=...&hours=72 (NWS-backed)

Notes:

• backend/run.py will also load a repo-root .env (at ./.env) if present.
• WEATHER_PROVIDER=earth2 in the backend is currently a stub (provider_unavailable).

2) Frontend (Vite)

cd frontend
npm install

cp .env.example .env
# set VITE_MAPBOX_TOKEN

npm run dev

Frontend defaults to http://localhost:5173 and calls the backend via VITE_API_BASE_URL (default http://localhost:5001).

GPU Forecast API (Optional)

The forecast service is a FastAPI app in forecast/api.py with endpoints:

• GET /health
• POST /forecast (writes NetCDF output under forecast/outputs/)
• POST /forecast-fcn3 (Earth2Studio FCN3 ensemble forecast)
• GET /storm-detection (runs detection over a NetCDF path)

Run via Docker (requires NVIDIA GPU + NVIDIA Container Toolkit)

Root docker-compose.yml builds and runs the service on port 8000:

docker compose up --build

Then:

curl http://localhost:8000/health

Implementation details:

• Image is built from the repo-root Dockerfile and based on nvcr.io/nvidia/pytorch.
• Installs earth2studio[fcn3] and related dependencies.

Call Center (Optional)

callcenter/ is a Twilio Media Streams full-duplex audio bridge to NVIDIA PersonaPlex (typically running on a DGX).

See callcenter/README.md for the full setup:

• running PersonaPlex on DGX via Docker Compose
• running the FastAPI bridge locally
• exposing the bridge to Twilio (ngrok) and configuring the Twilio webhook

WPS Harvester (Optional)

wps-harvester/ is a Postgres-backed, resumable crawler that:

• seeds from local Wi-Fi scan BSSIDs
• expands using Apple wloc “nearby” responses
• exports a GeoJSON point set for visualization

Quick run (Postgres required):

cd wps-harvester
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export DATABASE_URL='postgresql://localhost/postgres'
python3 harvest_ca.py --resume --summary-every-sec 10 --export-geojson ca_points.geojson

AWS tooling:

• wps-harvester/aws/ contains a cost-capped load-test harness plus a small DynamoDB-backed dashboard.

Tests

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