Early warning system (Nepal AQI demo)

FastAPI backend, static landing, guides hub (/guides), registration, dashboard UI, and operator admin console. Technical behaviour (env keys, AQ resolver order, MongoDB, notifications, provenance JSON) is maintained in docs/guides/IMPLEMENTATION_SNAPSHOT.md — prefer that file over older marketing summaries when describing what the deployment actually does.

Repository: github.com/mamta2009/aqinepal2026

Setup (about 10 minutes)

1. Python dependencies

cd backend
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Environment variables

Templates:

backend/.env.example — primary template (Mongo, AQ keys, Twilio/Resend, admin keys)
config/.env.example — optional second file; merged after backend/.env for unset keys only

cd backend
cp .env.example .env
# Optionally copy additional keys from ../config/.env.example into backend/.env

Do not commit backend/.env. Git ignores .env; use .env.example for placeholders only.

3. Run the API

cd backend
python -m uvicorn main:app --reload --host 127.0.0.1 --port 8000

Use 127.0.0.1 or localhost in the browser (main.py warns that http://0.0.0.0:8000 often appears blank).

4. Main browser URLs

Page	URL	Notes
Marketing landing	`http://127.0.0.1:8000/`	`landing/landing.html`
Guides hub (diagrams + links)	`http://127.0.0.1:8000/guides`	Public markdown is under `/guides/md/…`
Registration	`http://127.0.0.1:8000/registration`	Public enrollee flow
Data dashboard UI	`http://127.0.0.1:8000/frontend/index.html`	AQ / cases / hooks to registration
Operator admin	`http://127.0.0.1:8000/admin/dashboard`	Requires `NOTIFICATION_API_KEY`; PIN gate; private markdown viewer

Interactive API docs: http://127.0.0.1:8000/docs
Route map: http://127.0.0.1:8000/api/system-discovery

Example API calls

Air quality & weather

curl "http://127.0.0.1:8000/api/air-quality/current?city=Kathmandu"
curl http://127.0.0.1:8000/api/weather/current?city=Kathmandu

Core checks

curl http://127.0.0.1:8000/api/health
curl http://127.0.0.1:8000/api/cities

Repository layout — documentation

Public markdown is under early-warning-system/docs/guides/. Private partner drafts remain in early-warning-system/docs-private/ (browse only via admin API / admin UI).

Diagrams (SVG) live in early-warning-system/docs/tech/ (/guides/media/tech/ on the wire).

See README.md in this folder for a full guides index table.