Real-Time Ebola Outbreak Tracker

A full-stack surveillance dashboard for the 2026 Bundibugyo ebolavirus PHEIC, refactored from a single HTML file into a deployable React frontend + Python backend.

ebola-tracker/
├── frontend/              # Vite + React + TypeScript  → deploy to Hostinger (static)
│   ├── src/
│   │   ├── components/    # Map, Analytics, Intelligence, Vaccines, AI Analyst, etc.
│   │   ├── lib/api.ts     # backend → static → bundled fallback chain
│   │   ├── data/          # bundled offline fallback dataset
│   │   └── index.css      # full "Biohazard Command Center" design system
│   └── public/            # .htaccess (SPA routing) + data/dashboard.json
│
├── backend/               # FastAPI  → deploy to Railway
│   ├── app/
│   │   ├── main.py        # API: /api/health, /api/dashboard, /api/chat
│   │   ├── rag/           # knowledge base + TF-IDF retriever + Groq chatbot
│   │   ├── sync/          # daily data-sync job
│   │   ├── scheduler.py   # APScheduler — 7 AM Eastern daily
│   │   └── data_store.py  # in-memory cache around dashboard.json
│   ├── scripts/
│   │   ├── build_seed.py  # regenerate the canonical dataset (single source of truth)
│   │   └── run_sync.py    # standalone sync runner (Railway Cron alternative)
│   ├── data/dashboard.json
│   ├── Dockerfile
│   └── requirements.txt
│
└── docs/
    ├── DEPLOY_HOSTINGER.md
    └── DEPLOY_RAILWAY.md

What each piece does

Frontend — Faithful port of the original v3 dashboard: Leaflet map with pulsing outbreak markers and rich popups, Chart.js analytics (epidemic curve, CFR-by-strain, largest outbreaks), expandable intelligence briefings, vaccine/ countermeasure tables, and the AI Analyst chat. It fetches live data from the backend when configured, and always falls back to a bundled dataset so the UI renders even with no backend.

Backend — Serves the dataset and powers the AI Analyst with a Retrieval- Augmented Generation (RAG) pipeline: it builds a knowledge base from the outbreak data plus curated reference docs, retrieves the most relevant snippets with TF-IDF/cosine similarity, and asks a Groq-hosted LLM (openai/gpt-oss-120b, OpenAI's flagship open-weight model on Groq's free, ultra-fast LPU tier) to answer using only that grounded context — so answers cite real dashboard data instead of hallucinating.

Daily sync — Every day at 7 AM Eastern, the backend refreshes the dataset (timestamps, PHEIC-day counter, live timeline markers; plus trusted-feed figures if you configure one) and rebuilds the RAG index, so the dashboard stays current without redeploying.

Quick start (local)

Full step-by-step with troubleshooting: docs/RUN_LOCALLY.md

Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # add your GROQ_API_KEY (free: console.groq.com/keys)
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm install
echo "VITE_API_BASE_URL=http://localhost:8000" > .env
npm run dev

Open the printed localhost URL.

Regenerating the dataset

backend/scripts/build_seed.py is the single source of truth for the seed data. Running it writes the dataset to all three locations (backend data, frontend bundled fallback, frontend public copy) so they never drift:

cd backend && python scripts/build_seed.py

Deploying

• Frontend → Hostinger: see docs/DEPLOY_HOSTINGER.md
• Backend → Railway: see docs/DEPLOY_RAILWAY.md

Deploy the backend first, then put its public URL into the frontend's VITE_API_BASE_URL and build/upload the frontend.

Data & accuracy

Outbreak figures reflect WHO Disease Outbreak News, Africa CDC, and US CDC reporting on the 2026 Bundibugyo PHEIC (declared 16 May 2026). The unattended daily sync intentionally does not publish scraped/unverified case numbers — it refreshes time-derived fields and only ingests new figures from a trusted feed you explicitly configure. This is a surveillance/awareness tool, not a substitute for official public-health guidance.

Built With

This project started as a conversation, not a codebase. Zakir Khawaja and Bilal Riaz built the first version entirely through voice-dictated prompting with Claude (via Wispr Flow), working session by session from a single HTML file through to a full outbreak intelligence dashboard.

When that conversation hit its limit, Bilal (senior software engineer) took the architecture and refactored it into a production React frontend and Python (FastAPI) backend, adding the RAG-grounded AI Analyst and the daily data sync job.

Every design decision, from the epidemic curve to the cross-border risk model, was deliberate. This was not unreviewed AI output. It was directed, understood, and iterated on by both of us.