Project Hermes

The Plaid for health records. An embeddable Connect Widget that lets a patient authenticate once at a new provider and have their complete longitudinal health record flow directly into the provider's system as structured FHIR data. Patients upload or connect their health records from multiple providers. The system parses, normalizes to FHIR R4B, deduplicates, stores, and generates AI clinical summaries with provenance-linked citations following the International Patient Summary (IPS) standard.

Documentation System

This project uses three interconnected documentation files:

File	Purpose
CLAUDE.md	Session-level operating manual. Rules, stack, structure, mappings, commands.
architecture_L1.md	Level 1 build plan. 38 tasks with code patterns, schemas, and acceptance criteria.
architecture_master.md	Strategic architecture across L1-L3. Migration paths, vendor decisions, cost model.

Tech Stack

Backend - Python 3.12+, FastAPI, SQLModel (SQLite), uvicorn

FHIR - fhir.resources R4B subpackage

Parsing - lxml (XML), PyMuPDF (PDF), Claude Vision (scanned PDFs), Claude API (TXT/HTML extraction)

AI - Anthropic Claude API (domain sub-summaries, meta-summary, hallucination detection)

Frontend - Next.js 14, TypeScript, Tailwind CSS, shadcn/ui, Recharts

Setup

Backend

cd Project_Hermes
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt

Copy .env.example to .env and fill in your API keys:

cp .env.example .env

Start the backend server:

uvicorn backend.main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev

Verify

# Health check
curl http://localhost:8000/api/v1/health

Data Flow

Patient Setup App:    Upload/Connect -> Parser -> Mapper -> FHIR Store -> Dedup -> Review -> Generate Code
Provider Widget:      Enter Code -> Authenticate -> Clinical Display (30-second scannable summary)
AI Pipeline:          FHIR Resources -> Domain Chunker -> Claude API -> Meta-Summary -> Hallucination Check

Every health data point is stored as a valid FHIR R4B resource with full provenance tracking. The AI pipeline generates IPS-structured clinical summaries where every statement links to its source document. The Connect Widget delivers a compact clinical view designed to be scanned by a physician in 30 seconds.

Level 1 Scope

This is a Level 1 prototype, fully built and QA-tested. It runs locally on one machine, handles one patient's data, and is not HIPAA-compliant. Its purpose is to demonstrate the product to investors and physicians. See docs/demo_script.md for the full walkthrough.

Current stats: 86 backend tests passing, 28 API endpoints, 7 parsers, 238 non-duplicate FHIR resources from 19 source files, 13/13 AVIS validation checks passed, 30 QA bugs fixed.

License

Business Source License 1.1. See LICENSE for details.