Vokeh254/Kenya-Disease-Simulation-Platform

Interactive epidemic simulation engine implementing SEIR/SIR compartmental models with real population data. Features a live parameter control dashboard and geo-visualisation of disease spread across Kenyan counties. # Kenya Disease Simulation Platform An interactive, production-grade epidemic modelling web application implementing **SEIR/SIR compartmental models** with real KNBS 2019 census data and geo-visualisation across Kenya's 47 counties. --- ## Architecture ```mermaid graph TB Browser["Browser\n(React + D3)"] API["API\n(Node.js / Express)\n:3001"] SimEngine["Sim Engine\n(Python / FastAPI)\n:8001"] DB["PostgreSQL + PostGIS\n:5432"] Browser -- "REST / WebSocket" --> API API -- "REST proxy" --> SimEngine API -- "SQL" --> DB SimEngine -- "ODE solver\n(scipy)" --> SimEngine ``` ### Services | Service | Port | Stack | Role | |---|---|---|---| | `frontend` | 3000 | React + Vite + D3 | Dashboard, map, parameter controls | | `api` | 3001 | Node.js + Express + TypeScript | REST/WebSocket gateway, data persistence | | `sim-engine` | 8001 | Python + FastAPI + scipy | SIR/SEIR ODE solver | | `db` | 5432 | PostgreSQL 15 + PostGIS | County data, simulation runs | | `seed` | — | Python | One-shot DB seeder (KNBS census + scenarios) | --- ## Quick Start ```bash # 1. Clone and copy the environment file cp .env.example .env # adjust passwords if deploying # 2. Start the full stack docker compose up --build # 3. Wait ~60s for the seed container to finish loading census data # then open the app open localhost ``` The stack boots in this order: `db` → `sim-engine` + `seed` → `api` → `frontend`. --- ## Running Tests ### Python (sim-engine) ```bash cd sim-engine pip install -r requirements.txt pytest tests/ -v ``` ### Node.js API ```bash cd api npm ci npm run test:ci ``` ### React frontend ```bash cd frontend npm ci npm test ``` ### All at once (CI) ```bash # Mirrors what GitHub Actions runs: docker compose build ``` --- ## The Epidemiological Math ### SIR Model The population N is divided into three compartments: | Symbol | Compartment | Description | |---|---|---| | S | Susceptible | Can be infected | | I | Infectious | Currently infected and c …