Evidence-linked medical records

Every medical fact has a history.

┌─────────────────────────────────────────────────────────────────┐
│  Upload → Extract → Structure → Trace → Verify → Summarize     │
└─────────────────────────────────────────────────────────────────┘

---

⚡ TraceMD turns medical PDFs into structured, reviewable records — with every fact linked to its source.

🎮 Demo • ✨ Features • 🏗️ Architecture • 🚀 Get Started • 🔍 Trace to Source

---

🎯 The Problem

❌ Generic AI Document Tools	✅ TraceMD
Output a confident summary	Output structured facts with provenance
Errors are invisible	Errors flagged with confidence tiers
Source gone after summarizing	Real PDF, deep-linked to page
Classification is LLM guesswork	Deterministic parser, no override
"Believe the AI"	"Don't trust us. Verify us."

⚠️ TraceMD is an information organization tool. It does not diagnose, recommend treatment, or replace a clinician.

---

🔗 The Evidence Chain

    📄 Report (PDF / image / text)
           │
           ▼
    🤖 Gemini extraction with source citations
           │
           ▼
    🛡️  Zod schema validation — malformed extractions REJECTED
           │
           ▼
    📊 Deterministic reference-range parser
           │     value < low → 🔴 LOW
           │     value > high → 🔴 HIGH
           │     otherwise → 🟢 NORMAL
           ▼
    💾 Fact + provenance + evidence PERSISTED
           │
           ▼
    📛 Trace Passport → 🔍 Trace to Source (REAL PDF, correct page)
           │
           ▼
    ✅ Human verification (edit / verify, with audit trail)
           │
           ▼
    📝 Record Brief — safety-filtered, from structured facts ONLY

---

---

✨ Signature Features

📛 Trace Passport

Click any fact in the medical record to see:

• Value — 10.9 g/dL
• Reference Range — 12–16 g/dL
• Status — 🔴 LOW (deterministic)
• Confidence — HIGH / MEDIUM / LOW
• Source — CBC_September_2026.pdf
• Page — Page 1
• Evidence — the exact extracted line

🔍 Trace to Source ⭐ Hero Feature

Open the actual source document in an embedded PDF viewer:

• ✅ Deep-linked to the correct page
• ✅ Traced fact highlighted in the context panel
• ✅ Evidence line displayed beside the document
• ✅ Real PDF bytes — no placeholders, no fakes
• ✅ For demo reports: PDFs generated from the same strings as stored evidence

🎯 "Don't trust us. Verify us." No synthetic coordinate overlays. No faked highlighting. The trace is truthful by design.

✅ Review Workflow

Facts needing human attention are queued:

• Edit if the extracted value needs correction
• Verify when a human has reviewed it
• Audit trail preserved

Verification means "a human reviewed this" — NEVER "a doctor confirmed this".

📝 Record Brief

A safe summary generated strictly from structured facts:

• 🚫 No diagnosis
• 🚫 No treatment recommendations
• 🚫 No dosage advice
• 🚫 No risk scores

"AI-generated summary based on structured record information. Not medical advice."

---

Feature Set

Feature	Description
Patient intake	Create records with name, age, sex
Report ingestion	PDF, PNG, JPEG, or plain-text up to 10 MB, with MIME + extension validation
Structured extraction	Gemini with Zod-validated output
Deterministic classification	LOW / NORMAL / HIGH / UNABLE_TO_CLASSIFY — never invented
Trace Passport	Click any fact to inspect its full provenance
Trace to Source	Open the real document at the correct page
Human verification	Edit/verify with an audit trail
Timeline	Track changes across multiple reports over time
Record Brief	Safety-filtered summary from structured facts only
Demo data	Synthetic patient (Alex Morgan) seeds automatically on first visit

Feature set

• Patient intake — create records with name, age, sex
• Report ingestion — PDF, PNG, JPEG, or plain-text up to 10 MB, with MIME
  • extension validation and server-generated storage paths
• Structured extraction — Gemini with Zod-validated output
• Deterministic classification — LOW / NORMAL / HIGH / UNABLE_TO_CLASSIFY; a missing range is reported as "Not provided", never invented
• Confidence tiers — qualitative HIGH / MEDIUM / LOW based on observable extraction signals, no fake percentages
• Trace Passport + Trace to Source — described above
• Human review — edit values, verify facts, full audit history
• Timeline — values across report dates (e.g. Hemoglobin 13.2 → 12.4 → 11.8 → 10.9 g/dL), reported numerically without clinical interpretation
• Record Brief — safety-filtered summary from structured facts
• Demo dataset — a synthetic patient (Alex Morgan) with six reports across 2026 seeds automatically on first visit, so the product is explorable in seconds

---

---

🎮 Demo Experience

A fresh deployment auto-seeds a synthetic patient:

👤 Alex Morgan — 34F

Date	Report	Facts
January 2026	CBC Panel	7 facts
March 2026	CBC Panel	7 facts
June 2026	Chemistry + Lipids	9 facts
September 2026	CBC + Thyroid + Vitamins	12 facts

🏠 Dashboard → 📋 Reports → 📄 Medical Record → 👆 Click fact
    → 📛 Trace Passport → 🔍 View Source → 📕 REAL PDF
    → ✅ Review → 📈 Timeline → 📝 Record Brief

🧪 All demo values are clearly synthetic — no real patient data anywhere.

---

🏗️ Architecture

Technology Stack

Layer	Technology	Purpose
🖥️ Framework	Next.js 15 App Router	React 19 server components
📝 Language	TypeScript (strict)	Type safety
🎨 Styling	Tailwind CSS 4	Custom clinical design system
🔌 API	Next.js Route Handlers	Validated inputs, safe errors
🗄️ Database	PostgreSQL + Drizzle ORM	Supabase-compatible
📄 PDF	pdf-lib	Server-side document generation
🤖 AI	Google Gemini	Medical fact extraction
🛡️ Validation	Zod	Schema enforcement
🧪 Testing	Vitest + Testing Library	Unit + component + pipeline

---

🧪 Quality Gates

  🔍 npm run lint          → ✅ ESLint clean
  📋 npm run typecheck     → ✅ TypeScript clean
  🧪 npm test              → ✅ 49 tests passed
  🔗 npm run test:db       → ✅ DB integration tests
  📦 npm run build         → ✅ Production build

Test File	Coverage
referenceRange.test.ts	Deterministic range parsing + classification
extraction.test.ts	Zod schema validation + normalization
safety.test.ts	Safety filter (blocks diagnosis/treatment)
pdf.test.ts	Demo PDF generation
api.test.ts	Full API integration

---

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• Supabase account (free tier works)
• Google Gemini API key

Quick Start

# 1️⃣  Clone
git clone https://github.com/RARPlayzDev/Trace-MD.git
cd Trace-MD

# 2️⃣  Install
npm install

# 3️⃣  Configure
cp .env.example .env.local
# Add: DATABASE_URL + GOOGLE_API_KEY

# 4️⃣  Migrate
npm run db:migrate

# 5️⃣  Run
npm run dev

→ Open localhost:3000 ←

---

☁️ Deployment

Designed for Vercel + Supabase

# Set environment variables:
DATABASE_URL=postgresql://...
GOOGLE_API_KEY=...

Variable	Description
DATABASE_URL	Supabase connection string
GOOGLE_API_KEY	Gemini API key

🔒 Both variables are server-side only — never exposed to the client.

---

⚠️ Honest Limitations

Limitation	Detail
🔓 No authentication	Single-user demo scope. Not for real PHI.
📄 No pixel highlighting	Deep-links to page + shows evidence line. No overlay rectangles.
🚫 No clinical interpretation	Status badges classify against reference ranges — not diagnoses.
📊 No calibrated confidence	Tiers are heuristic, not probabilistic.

---

🛡️ Responsible Use

TraceMD organizes information — it does not practice medicine.

• ❌ Does not diagnose conditions
• ❌ Does not recommend treatment
• ❌ Does not alter medication
• ❌ Does not replace a licensed clinician

Always review extracted facts against the original report, especially:

• Values marked NEEDS_REVIEW
• Low-confidence facts
• Unparseable reference ranges

---

---

⭐ If TraceMD helps you, give it a star!

Made with ❤️ for evidence-based medicine

⬆ Back to Top