Guides & technical diagrams

Written guides (Markdown) plus architecture diagrams (docs/tech/) for the Nepal respiratory early-warning stack. Older bookmark /documentation redirects here; partner-internal Markdown lives under Admin → Private documentation.

Public markdown guides

Open in the browser while the API is running (rendered HTML). Sources live under docs/guides/ — all non-private Markdown is stored there.

Overview & quick start Implementation snapshot Cursor setup guide Package summary
Agent prompts Landing page guide Guides folder index Blockchain README Blockchain integration notes

Note: Restricted UNICEF/strategy drafts stay in docs-private/ — they are not linked here; operators open them from Admin → Private documentation after unlocking the dashboard.

Architecture

Tech diagrams live in docs/tech/ on disk and are exposed at /guides/media/tech/…. Concept framing SVGs ship under landing/assets/diagrams/ (/landing-assets/diagrams/…).

End-to-end platform

Early warning platform architecture diagram
High-level platform architecture (sources, APIs, dashboard, alerting).

Backend & hosted stack (FastAPI, MongoDB, Render)

FastAPI MongoDB and Render deployment architecture
How the API, document database (e.g. MongoDB Atlas), and a host such as Render fit together.

Frontend tiers

Three-tier frontend architecture
Suggested frontend tiers: SMS → web dashboard → optional mobile.

Notification & alert flow

This matches the running backend: notifications_api.py, twilio_notify.py, db_state.py, and MongoDB (early_warning). Outbound SMS/WhatsApp use Twilio; email uses SendGrid when configured. There is no built-in timer from air quality to broadcast—an external job or operator calls POST /api/alerts/broadcast when you want automated escalation.

Notification flow: FastAPI, MongoDB, Twilio, SendGrid, webhooks
Implementation flow (not a clinical timeline): registration, persistence, outbound channels, and Twilio webhook return paths.

Concept graphics

Nepal respiratory early warning concept
Respiratory early warning framing (Nepal).
Early warning action framework
Action / readiness framework.

Blockchain & verification

Two layers are implemented in this codebase:

  • Cryptographic anchoring (always safe): payload digests and optional EIP-191-style signing in blockchain_integration.py. Shown on API responses as verification so exports can be checked for tampering.
  • Optional Polygon transactions (off by default): hashed “alert / action / outcome” events are written via onchain_logger.py when POLYGON_ONCHAIN_LOG=true. The bridge module onchain_hooks.py calls these APIs from real product flows (air/heat broadcasts, facility POST /api/action-log) and records every attempt in MongoDB onchain_anchor_log. Each successful write costs testnet or mainnet gas.

Operator verification (not on the public users page): open GET /admin/dashboard → Polygon section → Refresh blockchain overview, Load recent anchors, and Send test on-chain touch (one minimal on-chain transaction to prove signer + RPC). On mainnet, that smoke test spends real POL; use Amoy first.

GET /api/blockchain/status GET /api/blockchain/integration

Environment variables (on-chain path)

  • POLYGON_ONCHAIN_LOG=true — turn on the optional transaction logger at API startup.
  • POLYGON_PRIVATE_KEY — funded wallet key (never commit; use secrets in production).
  • BLOCKCHAIN_ONCHAIN_NETWORK=amoy (recommended testnet), mumbai (deprecated), or mainnet (live ledger — real POL).

Full operator route list: docs/guides/IMPLEMENTATION_SNAPSHOT.md → Operator admin → Polygon / /api/admin/blockchain/*.

Testnets change. Polygon has been transitioning away from Mumbai; your deployment should prefer Amoy (chain 80002) and current RPC URLs. Check Polygon documentation before production.

Free test “coins” on Polygon

On testnets, tokens are worthless play money used to pay gas while you experiment. They are minted by faucets, not purchased.

  1. Install a wallet (e.g. MetaMask) and create a dedicated developer wallet—never reuse a main wallet loaded with real funds.
  2. Add the correct test network to your wallet (historically Mumbai 80001; increasingly Amoy 80002).
  3. Visit an official/community faucet, connect the wallet, and request test MATIC.
  4. Wait for the transaction to arrive, then retry your API with POLYGON_ONCHAIN_LOG=true.

Examples of faucet entry points (verify current URLs with Polygon documentation):

Mainnet MATIC costs real money. Until you consciously choose mainnet + accept cost and key custody risk, stay on testnets for development.

APIs & operations

Interactive API docs (Swagger UI) GET /api/system-discovery

Operational checks

  • GET /api/health — API up; mongodb_persistence when MongoDB is wired; notification_registry when the full DB handle is active for contacts/alerts.
  • GET /api/runtime-config — public config + integration flags (including Twilio / email provider readiness where implemented).

Weather and optional LLM proxies are documented in Swagger once your server is running.