📦 Nepal AQI early-warning — package summary

✅ What you have

Source code (GitHub — recommended)

Repository: https://github.com/mamta2009/aqinepal2026

git clone https://github.com/mamta2009/aqinepal2026.git
cd aqinepal2026/early-warning-system

Documentation for behaviour and APIs: IMPLEMENTATION_SNAPSHOT.md (this folder).
Hands-on Cursor walkthrough: CURSOR_SETUP_GUIDE.md — same /guides URLs as the running site.

Optional ZIP delivery

An early-warning-system.zip (if someone shared one) mirrors the early-warning-system/ folder: backend, landing/ (marketing /guides via guides.html, /registration, /admin/dashboard), frontend/, config/, docs/ (guides under docs/guides/).

🚀 Getting started (~10 minutes)

git clone https://github.com/mamta2009/aqinepal2026.git
cd aqinepal2026/early-warning-system/backend
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env — Mongo keys, AQ keys, NOTIFICATION_API_KEY, etc.

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

Use http://127.0.0.1:8000 in the browser (avoid http://0.0.0.0:8000 — often blank).

📚 Documentation index (in-repo)

Older “/outputs” or duplicate guides elsewhere may exist from packaging history; IMPLEMENTATION_SNAPSHOT.md wins when wording conflicts with the running code.

✅ What runs out of the box

• FastAPI backend, static /frontend, landing/ pages, GET /guides, GET /admin/dashboard
• Synthetic weekly health patterns (health_data_generator.py) unless you integrate DHIS2 or other feeds
• Air-quality resolver (WeatherAPI → WAQI → Rapid, per snapshot) plus supplementary weather routes where keys exist
• provenance / A2A-style hints on responses when integrations return data
• Regional/national demo mode flags in payloads
• Optional MongoDB enrollees, logs, broadcasts when MONGODB_URL (or DATABASE_URL) is set
• Optional Twilio / Resend when configured; NOTIFICATION_API_KEY protects operator notification JSON routes (and admin JSON under /api/admin/*)
• Blockchain helpers and optional gas-spend on Polygon — off by default; product wiring in backend/onchain_hooks.py, operator audit in Mongo onchain_anchor_log (docs/guides/blockchain-ai/README.md)

📋 Repository layout (app tree)

early-warning-system/
├── backend/           ← main.py, admin_panel.py, notifications_api.py, …
├── landing/           ← landing.html, guides.html, registration_portal.html, admin_dashboard.html
├── frontend/index.html
├── config/.env.example
├── docs/
│   ├── guides/                    ← Every public Markdown file + `/guides/md/…` rendering
│   ├── tech/*.svg                 ← Architectural diagrams (/guides/media/tech/…)
│   └── blockchain-ai/             ← Reference Python only (guides live under docs/guides/blockchain-ai/)
├── docs-private/                  ← Internal markdown — `/admin/dashboard` → Private documentation
├── render.yaml
└── README.md

⚡ Smoke test (quick)

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

📤 Deploy

1. Repo is already on GitHub: mamta2009/aqinepal2026. Fork or mirror to a private repo if you must exclude materials under docs-private/ from publication.
2. Connect Render (or another host): run uvicorn from early-warning-system/backend with production env vars. See early-warning-system/render.yaml as a starting blueprint.
3. Hosting cost depends on provider and tiers — size the service to traffic and MongoDB separately.

🔧 Troubleshooting (short)

🎯 Realistic demo data vs production

Weekly case curves are synthetic WHO-style patterns suitable to prove dashboards and alerting — not a substitute for ministry surveillance until you swap the pipeline. See IMPLEMENTATION_SNAPSHOT.md for what is keyed vs heuristic.

Last aligned with docs: May 2026 (repository aqinepal2026, branch main). Update this file if the canonical snapshot or URLs change.