Two-Way Last-Mile Action & Verification Network

A working IGAD Hackathon 2026 prototype that connects hazard forecasting to last-mile alerts, then closes the loop with community SMS verification.

What Works

• Regional dashboard with impact map, priority alerts, delivery reach, and action confirmation.
• Forecast simulation with explainable 0-100 impact scoring.
• Persistent alerts, districts, users, trigger rules, feedback, and audit records in SQLite.
• Simulated Africa's Talking SMS delivery and reply parsing (1, 2, or 3).
• Automatic escalation when a focal point requests support.
• WebSocket events that refresh dashboard state after alerts and replies.
• District, feedback, field mobile, and administration workspaces.
• Synthetic model training pipeline and a documented deterministic runtime baseline.

Quick Start

Docker

docker compose up --build

Open http://localhost:3000. API documentation is at http://localhost:8000/docs.

Local Development

Backend:

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend, in another terminal:

cd frontend
npm install
npm run dev

Open http://localhost:5173.

The database is seeded on first start. Demo credentials are:

• admin@example.com / admin123
• officer@example.com / officer123

The current UI opens directly into the operations dashboard for judging. The JWT endpoints are available at /api/auth/login and /api/auth/me for a production login gate.

Tests

cd backend
pytest -q

cd ../frontend
npm run build

The backend tests cover impact scoring, SMS parsing, validation, and the full trigger-to-send-to-feedback flow.

Model Training

cd ml
pip install -r requirements.txt
python training/impact_model.py

The trained pipeline is written to ml/models/impact_model.pkl. See ml/MODEL_CARD.md before using the model outside a demonstration.

Environment

Copy the .env.example files in backend and frontend when overriding defaults. SMS stays in simulation mode unless a reviewed provider adapter and credentials are configured.

Deployment

• Backend: deploy backend/Dockerfile to Render or Railway and set DATABASE_URL, SECRET_KEY, and CORS_ORIGINS.
• Frontend: deploy frontend to Vercel, Netlify, or a static container. Set VITE_API_URL and VITE_WS_URL before building.
• Database: SQLite is suitable for the demo. For multi-instance deployment, set a PostgreSQL SQLAlchemy URL and run schema creation or a migration during release.

Never commit real SMS or forecasting API keys. Rotate any credential shared in chat or logs.