A small open prototype that replays real, de-identified ICU vitals into a multi-bed dashboard and ties alarms, a synthetic health ID, simulated insurance, prescriptions and a discharge summary to one record, using demo data that is not for clinical use.
Open-source tools · How-to · Healthcare
How to use patient-history-tracking: a demo ICU dashboard and linked record
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/patient-history-tracking
Watch the walkthrough
Watch on YouTube: youtu.be/FgShalD-MyY
What it is for
This repository is a learning reference. It shows how an ICU aggregation dashboard can be put together: fetch bedside-monitor numbers, check them against alarm rules, stream them to a screen, and keep a single patient record that other features write into.
It uses open, de-identified surgical cases from VitalDB. The patient names, health ID numbers, insurer and policies are all invented. Nothing connects to a real hospital, a real health ID system or a real insurer.
Who it is for
- Engineers who want to see a live-vitals pipeline (replay, alarm rules, WebSocket, React) in one small codebase
- Health-IT students and researchers learning how a linked patient record is structured
- Non-programmers who want to ask an AI assistant how an ICU dashboard works
- Any clinical use, patient care or monitoring of real people. It is not a medical device.
- Real health ID or insurance integration. Both are simulated.
- Production hosting. It runs as one process with a SQLite file.
What you need
| Requirement | Why | How to get it |
|---|---|---|
| Python 3 with venv | runs the FastAPI backend | python.org or brew install python (the README does not state a minimum version) |
| Node.js and npm | runs the React and Vite dashboard | nodejs.org or brew install node |
| Tesseract (system program) | only for the prescription and lab-report OCR features | brew install tesseract on macOS. pip installs only the Python wrapper. This part was not run in the demo. |
| Internet on first run | the vitaldb library fetches case data at runtime; nothing is bundled | No login or API key is needed |
| Not needed | no GPU, no paid API key, no database server, no Docker | SQLite is created locally |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/patient-history-tracking.git
cd patient-history-tracking
claude # or: geminiInstall
- Get the code
git clone https://github.com/herrrickshaw/patient-history-tracking.git cd patient-history-tracking - Optional: install Tesseract if you want the OCR features
brew install tesseract - Create the backend environment and install dependencies (fastapi, uvicorn, vitaldb, numpy, websockets, pytesseract, Pillow, python-multipart)
cd backend python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt - Start the backend
uvicorn app.main:app --port 8710 - In a second terminal, start the dashboard, then open http://localhost:5273
cd frontend npm install npm run dev -- --port 5273
Quick start: commands and what you should see
List the beds (the demo called the API in-process; with the server running, request the same path on port 8710)
GET /api/bedsSeven beds, Bed-A to Bed-F plus Bed-DEMO, each backed by a VitalDB case (for example Bed-A is case 4096). Bed-DEMO has a 40-second encounter and is marked demo=True.
Watch the live vitals stream
WebSocket /ws/vitalsOne tick per bed with heart rate, oxygen saturation, respiratory rate and systolic blood pressure. At sim_t=8, Bed-A showed HR 76, SpO2 100, RR 19. Some values are None when a case has no reading.
Look up a bed's synthetic health ID
GET /api/beds/Bed-A/identityA generated name, a synthetic ABHA-style number, age 53, sex F, General surgery, Cholecystectomy, plus a disclaimer that the number is not real.
Check simulated insurance and prescriptions
GET /api/beds/Bed-DEMO/insurance
GET /api/beds/Bed-DEMO/prescriptionsAn invented insurer, an eligible status, and an approved claim (CLM-0585570804). Six illustrative orders that show as discontinued after the demo bed's discharge.
Read the append-only record timeline
GET /api/beds/Bed-DEMO/recordAdmission, eligibility check, prescriptions, alerts, discharge, discharge summary and claim in one timeline, 27 events in total.
Get the discharge summary
GET /api/beds/Bed-DEMO/discharge-summaryVitals ranges (for example HR 71 to 82, SpO2 99 to 100), one alert (RR low), the approved claim, and a disclaimer that it is not a real clinical document.
Ways to use it
| Method | How it works |
|---|---|
| Web dashboard | Run the backend and frontend and open http://localhost:5273 for the live bed grid, sparklines and colour-coded alarms. |
| REST and WebSocket API | Call the /api/beds/... endpoints and /ws/vitals directly from scripts or a browser. |
| Read or change the code | Alarm rules are in backend/app/alerts.py. Other modules cover vitals replay, identity, insurance, prescriptions, the record and the discharge summary. |
| Through an AI assistant | Open the folder in Claude Code or Gemini CLI, or upload the README to a chat assistant, and ask questions in plain language. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Explain this repo in plain English. What happens between VitalDB and the dashboard screen?
- Walk me through starting the backend and the frontend step by step on my [Mac / Windows / Linux] machine.
- Show me the alarm rules in backend/app/alerts.py and explain each threshold. Which are illustrative defaults?
- How would I replace the synthetic insurance module with a mock of [another system] for a learning project?
- What would have to change before something like this could be used with real patients? List the gaps honestly.
- Explain the OCR review queue and why the README says handwriting results must never be trusted automatically.
Limits and honest caveats
- DEMO DATA, NOT FOR CLINICAL USE. This is a prototype, not validated, and not a medical device.
- Alarm thresholds are illustrative defaults and have not been clinically reviewed.
- The health ID, insurer, policies, claims and prescriptions are invented. No real ABDM or insurer integration exists.
- Storage is a single SQLite file in one process, so it does not scale across machines.
- The OCR features (local Tesseract) were not exercised in the demo. The README reports handwriting OCR misread 650mg as 850mg, so every extracted result goes to a human review queue.
- VitalDB data is licensed CC BY-NC-SA 4.0 under a data use agreement: non-commercial, and no re-identification. Cite Lee et al., Scientific Data 2022 if you build on it.
- The demo called the API in-process rather than through a running server, so the browser dashboard itself was not shown in the numbers above.
Sources: the repository README (herrrickshaw/patient-history-tracking), backend/requirements.txt and the demo run of 18 October 2026.
- v1.0.0 — 18 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
