🩸 JeevanDhara — Blood Bank & Emergency Donor Neural Network

Every drop. Every second. Every life. A real-time intelligence layer over India's blood ecosystem — built on 2,130 real, licensed blood banks across 35 states & UTs from the Government of India's open data portal.

Author: Praveen Sudireddy

---

💡 The Problem

India needs 13–15 million units of blood every year but collects only ~11 million — a structural shortfall of 1–4 million units (15–25%). Meanwhile:

• ~10% of collected blood expires unused — RBC units live just 42 days
• 74 districts have zero blood banks; 660M people live in "blood deserts" with marginal access
• In an emergency, families make dozens of phone calls to find a compatible unit — minutes that cost lives
• Rare groups (O−, AB−) are chronically dry, yet donors willing to help are never paged

JeevanDhara attacks all four failures with one neural network.

⚡ What It Does

Engine	Magic
🚨 Emergency Matching	Scores every bank on stock coverage (0.40) · proximity (0.25) · freshness (0.20) · 24×7 readiness (0.15), then builds a multi-bank fulfillment plan with live ETAs — exact group first, O− universal reserve routed automatically
📟 Donor Paging	When shelves run dry (Rh-negative groups), pages the nearest eligible, committed, compatible donors — NBTC rules enforced: 90-day interval, 18–65 yrs, ≥50 kg, Hb ≥12.5
🧬 Compatibility Graph	The 8-node, 27-edge red-cell transfusion graph (O− universal donor → AB+ universal recipient) with rarity indices and pool mathematics
🗺 Network Map	All 2,130 real banks plotted live — names, districts, coordinates, contact numbers, stock health
🩸 Inventory Intelligence	Days-of-supply per group & state, expiry-risk windows, and a rebalancing advisor that rescues near-expiry units by routing them to hungry banks
📈 Demand Forecast	12-month seasonal model — monsoon dengue/malaria surge (+15–18%), winter surgery & trauma rise (+8%) — with an AI camp planner telling you where and when to hold drives
🤝 Donor Hub	Live eligibility checker with every rule explained, next-eligible-date calculation, and "lives touchable" impact maths

🖥 The Dashboard

Hand-crafted, zero-dependency frontend — glassmorphism over a night-shift palette, animated ECG pulse, glowing bank constellation, count-up stats, and staged emergency scans.

Command Center — live network pulse & real-world facts	Emergency Match — multi-bank plan, ETAs, donor paging
Network Map — 2,130 real banks, stock-health coloured	Inventory — group health, expiry risk, rebalancing
Forecast — seasonal demand vs supply, camp planner	Donor Hub — eligibility, compatibility matrix, rarity

🎬 Demo Video

docs/demo_video.mp4 — a 3-minute narrated walkthrough: the crisis in numbers, the real-data foundation, a live AB− emergency in Mysuru (scan → multi-bank plan → donor paging), zero-waste rebalancing, seasonal forecasting with the camp planner, and the donor hub.

🚀 Quickstart

pip install -r requirements.txt

# seed the database (deterministic, ~10s first run)
python3 app/db.py

# launch
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 — the dashboard loads instantly.

Run the test suite (40 tests):

python3 -m pytest tests/ -v

Interactive API docs are auto-generated at /docs (Swagger) and /redoc.

🏗 Architecture

jeevandhara/
├── data/
│   ├── blood_banks.json        # 2,130 real banks (source of truth)
│   ├── raw_bloodbanks.geojson  # raw government fetch (provenance)
│   └── jeevandhara.db          # SQLite: banks · inventory · lots · donors · requests
├── app/
│   ├── db.py                   # schema + deterministic seed (rng 2026)
│   ├── main.py                 # FastAPI · 15 API endpoints · static dashboard
│   └── engines/
│       ├── compatibility.py    # 27-edge transfusion graph
│       ├── emergency.py        # ⭐ hero: scoring + planning + paging
│       ├── inventory.py        # stock health + rebalancing
│       ├── forecast.py         # seasonal demand + camp planner
│       ├── donors.py           # eligibility rules + network stats
│       └── facts.py            # citable real-world numbers
├── web/                        # index.html · style.css · app.js (zero deps)
├── tests/                      # 40 pytest cases (engines + API)
└── docs/                       # screenshots

API Endpoints

Method	Endpoint	Purpose
POST	/api/emergency/find	🚨 the hero — full fulfillment plan
GET	/api/inventory/health	network stock health
GET	/api/inventory/rebalance	near-expiry rescue plan
GET	/api/forecast	12-month projection + camps
POST	/api/donors/eligibility	rule-by-rule donor check
GET	/api/map/banks	all banks with geo + stock
GET	/api/banks · /api/states · /api/cities	directory with renamed-city aliases (Mysuru→Mysore…)
GET	/api/compatibility	matrix · rarity · donors-for
GET	/api/overview · /api/facts · /api/donors/stats · /api/emergency/requests	dashboard feeds

📊 Data Source & Integrity

• Blood Bank Directory — National Health Portal (NIHFW), via data.gov.in / ArcGIS Living Atlas India — NDSAP open licence (Government Open Data License – India)
• 2,130 unique licensed banks with real names, districts, lat/lng, categories, contacts
• Inventory, lots and donors are deterministic simulations (fixed seed 2026) layered on the real network topology — every number reproducible
• Narrative statistics (shortfall, wastage, blood deserts) from NBTC/NACO, WHO, e-RaktKosh, and peer-reviewed literature, surfaced in-app with sources

⚠️ Disclaimer

JeevanDhara is a planning & demonstration system. In a real emergency, always contact your nearest blood bank or hospital directly. Inventory figures shown are simulated for the real bank network.

📄 License

MIT © Praveen Sudireddy · Data under Government Open Data License – India (NDSAP)