OpenSeva

OpenSeva is a monorepo of six integrated services. Each service has a clearly defined responsibility and communicates over HTTP using FHIR R4 and standard OAuth2/JWT. On top of these services, OpenSeva now simulates a Health Information Exchange — multiple EMRs feeding one shared record.

HIE Simulation Layer New

A data layer on top of either stack — there is no new server. ./seed-hie.sh loads four tenant EMRs into the same FHIR store, each resource tagged by its source org. Tenant scoping works today; the exchange / matching view is the Track E roadmap, not yet built.

Service URLs — Quick Reference

Start the local SQLite dev stack with a single command. All five services launch as background processes.

./run.sh start        # start all 5 services
./run.sh status       # verify health + PIDs

Expected status output — all five services healthy:

  SERVER    PORT    PID     HEALTH
  fhir      8080    12345   healthy
  auth      8088    12346   healthy
  emr       3000    12347   healthy
  portal    8090    12348   healthy
  dataset   8091    12349   healthy

Health Check Links

Presenter Checklist

• FHIR health at :8080 returns {"backend":"sqlite"}
• Auth health at :8088 returns {"status":"ok"}
• EMR frontend loads at :3000 (may take 3–5 s on first load)
• Dataset Worker health at :8091 returns {"status":"ok"}

1. 1

   Open the EMR login page

   Open EMR Login ↗
2. 2

   Enter Doctor credentials

   doctor@emr.local

   copy

   doctor123

   copy

   The EMR uses OAuth2 implicit flow — login redirects to Auth Server at :8088, which returns a JWT in the URL hash.

3. 3

   Navigate to Patients — click Patients in the left sidebar. You will see the seeded demo patients: Alice, Bob, Carol, David.

4. 4

   Open a patient chart — click any patient name to open their chart. Explore the Encounters, Observations, and Appointments tabs.

5. 5

   (Optional) Login as Admin to show the full admin dashboard. The admin account sees all patients and can access system configuration.

   admin@emr.local

   copy

   admin123

   copy

Presenter Checklist

• Logged in as Doctor — EMR home screen visible
• Patient list shows seeded patients (Alice, Bob, Carol, David)
• Patient chart opened — Encounters tab visible
• Observations or appointments visible on the chart

1. 1

   Open the FHIR Admin UI — served by the Portal server on :8090

   Open FHIR Admin ↗
2. 2

   Verify the connection dot is green — top of the page shows the FHIR base URL with a green "●" indicator. If amber, click the "Check" button.

3. 3

   Search Patients — the Search tab is active by default. Select Patient from the resource type dropdown, set count to 20, and click Search.

4. 4

   View raw FHIR JSON — click any row to expand and see the raw FHIR R4 JSON for that resource.

5. 5

   Try other resource types: Encounter, Observation, Practitioner, Organization, PractitionerRole

Presenter Checklist

• FHIR Admin UI loaded — connection indicator green
• Patient search returned seeded patient records
• Raw FHIR JSON visible in the row expander
• At least one other resource type searched successfully

The FHIR Admin UI can import any FHIR R4 transaction bundle. Six pre-built clinical datasets are included.

Pre-built Demo Datasets

1. 1

   Click "Bulk Upload" tab in FHIR Admin UI (second tab from left)

2. 2

   In the "Demo Files" panel on the right, click one of the dataset buttons (e.g., "Emma Chen - Breast Cancer"). The bundle loads into the upload text area.

3. 3

   Click "Upload to FHIR" — the panel below shows a per-resource result table. Green rows = success, red rows = error.

4. 4

   Verify in Search tab — go back to Search, select Patient, and confirm the new patient (Emma Chen) now appears.

Presenter Checklist

• Bulk Upload tab opened
• Demo bundle loaded via the Demo Files panel
• Upload executed — green result rows visible
• New patient appears in Search tab

The Dataset Studio connects to an OpenAI-compatible LLM to generate synthetic FHIR R4 bundles on demand. A template fallback works even without an LLM endpoint.

1. 1

   Click "Dataset Studio" tab in FHIR Admin UI (fourth tab)

2. 2

   Check the Dataset Worker URL — pre-filled as http://localhost:8091. This is the server-side LLM caller that keeps API keys off the browser.

3. 3

   Select provider mode:

   • Template only — generates a deterministic FHIR bundle with no LLM call. Always works. Use this if no LLM is configured.
   • OpenAI-compatible — calls any vLLM / Ollama / OpenAI-style server at the configured base URL.
   • Legacy DGX1 — calls the university's DGX1 server at /v1/text.
4. 4

   Click "Use Template" or "Generate Dataset" — the FHIR JSON textarea fills with a transaction bundle containing Patients, Encounters, Observations, and Practitioners.

5. 5

   Click "Upload to FHIR" — the Dataset Worker validates the bundle and PUTs each resource to HFS. A success/error row appears per resource.

6. 6

   Check Dataset Job History — click "Refresh Jobs" to see the persisted job record: type, status, timestamp, user, and entry count.

Presenter Checklist

• Dataset Studio tab opened
• Template loaded — valid FHIR JSON visible in output area
• Upload executed — green result rows visible
• Dataset Job History shows the new upload job

The MCP Server exposes role-gated EMR tools to Claude via the Model Context Protocol. Users authenticate with a one-time PIN.

PIN Authentication Flow

1. 1

   Open the MCP Connect page in the EMR:

   Open MCP Connect ↗
2. 2

   Log in with your EMR credentials — the page generates a 6-digit PIN visible on screen. The PIN expires in 5 minutes.

3. 3

   Add the MCP server to Claude Desktop — edit ~/.config/claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "openseva-emr": {
         "command": "node",
         "args": ["/path/to/openseva/mcp-server/index.js"]
       }
     }
   }

   copy
4. 4

   In Claude, call authenticate — first call with no arguments to get instructions, then with the PIN:

   authenticate()
   # → Claude shows instructions and MCP connect link
   
   authenticate({"pin": "123456"})
   # → Authenticated as doctor@emr.local (practitioner)
   # → Role-gated tools now available

   copy

Role-Gated MCP Tools

Presenter Checklist

• MCP Connect page opened and PIN visible
• MCP server config shown (Claude Desktop JSON)
• PIN exchange flow explained to advisor
• Role-gated tool table shown

The Docker stack runs all services in containers with PostgreSQL, stable JWT keys, and enforced FHIR authentication. Both stacks can run simultaneously — they use different port ranges.

docker compose --profile admin up -d   # start all services
docker compose --profile admin ps      # verify all containers healthy

Stack Comparison

Health Check Links (Docker)

Presenter Checklist

• All Docker containers show "Up (healthy)" in docker compose ps
• FHIR health at :8180 returns {"backend":"postgres"}
• Auth health at :8188 returns {"db":"connected"}
• EMR login page loads at :3100

In Docker mode, HFS validates every request against an RS256 JWT. Unauthenticated writes are rejected with 401 Unauthorized. This is the key security difference from local dev.

Demonstrate the 401

curl -s -o /dev/null -w "%{http_code}" \
  http://localhost:8180/Patient
# Expected: 401

Authenticated Request (with admin token)

# 1. Login and capture token
TOKEN=$(curl -s -X POST http://localhost:8188/auth/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@emr.local","password":"admin123"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# 2. FHIR Patient search with token
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8180/Patient?_count=5"
# Expected: 200 + FHIR bundle JSON

Verify the JWKS Endpoint

curl http://localhost:8188/.well-known/jwks.json
# Returns: RSA public key used by HFS to validate all JWTs

Presenter Checklist

• Curl without token to :8180 returns 401
• JWKS endpoint at :8188 returns RSA public key JSON
• Curl with admin token returns 200 + FHIR bundle
• JWKS / RS256 JWT flow explained to advisor

1. 1

   Open Docker FHIR Admin:

   Open Docker FHIR Admin ↗
2. 2

   Login via the Auth panel — at the top of the page, enter admin credentials and click "Login". The bearer token is stored in session storage and forwarded to all FHIR and Dataset Worker requests.

   admin@emr.local

   copy

   admin123

   copy
3. 3

   Search Patients — the Search tab uses PostgreSQL via HFS. Note that results are faster and the total field is present (not available in SQLite).

4. 4

   Dataset Studio → Refresh Jobs — click "Refresh Jobs" to load persisted job history from the Docker volume at $DATA_DIR/audit/dataset-jobs.json (default ./docker-data). Jobs survive container restarts.

5. 5

   Open Swagger UI — view the auto-generated OpenAPI spec from HFS's CapabilityStatement:

   Open Swagger UI ↗

Presenter Checklist

• Docker FHIR Admin loaded — admin logged in via Auth panel
• Patient search returns results (Postgres-backed, faster)
• Dataset Job History shows persisted jobs from earlier uploads
• Swagger UI loaded and showing FHIR API endpoints

A snapshot of OpenSeva's current capabilities. Everything marked Working runs today on both stacks and is demoable. The newest additions turn OpenSeva into a hand-over-to-students teaching platform with a multi-EMR exchange.

Most EMR teaching stops at the visit. The Revenue Cycle Simulation lets students experience what happens after a patient appointment — where the bulk of US healthcare administrative cost lives. It is a process teaching tool, not a billing engine: there is no payer adjudication, clearinghouse, real X12/EDI, payment, or denial logic. All codes are clearly labelled educational sample codes, never claimed to be billing-valid, and a human must approve every step. Language stays neutral ("coding review", "claim readiness", "documentation support") — the simulation deliberately does not teach upcoding.

The workflow

Appointment → Check-in → Encounter → Signed Note → Coding Review → Draft Claim → Billing Review → Simulated Submission

1. Sign & Start Coding Review — on a finished encounter the provider signs the note (records a FHIR Provenance attestation) and a coding-review task is created.
2. Coding Review — the helper suggests diagnosis/procedure codes. Each suggestion is explainable: it shows the exact note text that supports it, plus a confidence score and reason. The reviewer accepts, rejects, edits, or adds a code, and can add a documentation note.
3. Draft Claim — after documentation validation, accepted codes are assembled into a draft claim.
4. Billing Review (Admin acts as Billing Specialist) — readiness checklist, status timeline, and a conceptual X12 837-style preview. Send back to coding, mark ready, or Simulate Submit.
5. Submit to Payer — status becomes Submitted and a real FHIR Claim is sent to the standalone Payer App, which adjudicates it; the EMR Claim Status view then shows the live result.

Coding helper — two modes

• AI-assisted — when the local LLM is configured, the note is sent to the Dataset Worker /ai/coding-suggest bridge with strict guardrails (education only, never optimize reimbursement, never invent documentation, only note-supported codes, warnings when documentation is thin). Runs fully on-device on Apple Silicon via the MLX/ module (./MLX/start-llm.sh) — no external API.
• Rule-based fallback — a transparent keyword matcher (diabetes, hypertension, annual wellness, chest pain, follow-up …) that extracts real evidence sentences from the note. Used automatically when the LLM is unavailable, so the workflow always works offline.

Roles

Under the hood

• Data: each claim is a SimulatedClaim persisted as a FHIR Basic resource (stable id simclaim-<encounterId>, full payload in an extension) — shared across roles, persistent, and designed to map to a real FHIR Claim later.
• Audit trail: every action (signed, suggested, accepted/rejected/edited, draft generated, billing review, simulated submit) is recorded on the claim and surfaced in the billing timeline.
• Burden dashboard: an "Educational administrative burden simulation" card shows queue counts, average human touches per claim, and warnings generated — a teaching aid, not financial truth.

Try it

1. Seed the demo scenarios: ./run.sh seed (loads 5 claims incl. an incomplete documentation case).
2. Login as doctor → Revenue Cycle → Coding Review Queue; open a claim and accept codes; Generate Draft Claim.
3. Login as admin → Billing Review; review the checklist + X12 preview; Mark Ready, then Simulate Submit.
4. Open Learning View for the step-by-step diagram of who does what, which FHIR resource is involved, and why each step adds administrative cost.

Revenue Cycle stops when the provider clicks Submit. From there the claim leaves the EMR for a separate insurance-company app running on its own port — exactly like real life, where the payer is a different organisation with its own systems. It is educational only: there is no real payer, clearinghouse, X12 837/835/EDI, CPT/ICD validation, fee schedule, eligibility, or prior authorization. Every amount is a labelled sample. The framing is neutral: the provider wants accurate, documentation-backed payment; the payer wants policy- and documentation-backed payment; the friction between them is the administrative burden.

Two standalone services + the EMR

The pipeline (shown in real time; batch in reality)

received → validate → eligibility / coverage → payment integrity (downcoding + fraud + payable amount) → adjudicate → write FHIR Claim + ClaimResponse

1. Admin submits from Billing Review → Submit Claim to Payer. A modal shows the patient's insurance on file (from Coverage) and a payer dropdown; a real FHIR Claim is POSTed to the Payer App.
2. Validate — missing patient / provider NPI placeholder / diagnosis / procedure / coverage → rejected.
3. Eligibility / coverage — unknown plan, or a service the plan excludes → denied.
4. Payment integrity — the Payer App calls the integrity API: it detects downcoding (high-complexity code vs a per-plan documentation bar), scores fraud/abuse (upcoding pattern, excessive units, dx/proc mismatch, thin doc), and computes the payable amount from the plan's coverage %, copay, and deductible.
5. Adjudicate & persist — outcome is paid / downcoded / denied / rejected; the Payer App writes the ClaimResponse to FHIR. The EMR's Claim Status view polls FHIR and updates live.

Outcomes & sample payment math (simulation only)

Numbers are obvious placeholders — no real fee schedule. Each of the 16 sample insurers (payer-app/data/payers.json) has its own rules, so the same visit pays differently per plan. Example (Aetna): allowed 180 − $50 deductible × 80% − $30 copay = $74; BlueShield: allowed 180 × 85% − $25 = $128.

FHIR resources (the shared DB is the system of record)

• Coverage + insurance Organizations model patient insurance (seed-insurance.sh links 13 patients to plans).
• Claim (built by the EMR, id claim-<encounterId>) carries the note + chosen payer in http://openseva.local/claims/* extensions.
• ClaimResponse (written by the Payer App, id claimresponse-<encounterId>) holds the outcome, adjudication amounts, payment, process notes, and fraud/downcoding extensions. The EMR reads this back for real-time status.

Roles

The Payer App dashboard is a separate service with no EMR login — it is the insurance company's view, deliberately outside the EMR's role model.

Try it

1. Start everything (incl. the two payer services) and seed insurance: ./run.sh start then ./run.sh seed.
2. Login as admin → Revenue Cycle → Billing Review on a ready claim → Submit Claim to Payer (the patient's plan is prefilled from Coverage).
3. Watch Claim Status update live as the payer adjudicates, then open the Payer App dashboard to see the same claim from the insurer's side.
4. Try a downcode (high-complexity code on a short note) and a rejection (a claim missing a diagnosis) to see the other outcomes.

An EMR is one clinic's chart. An EHR is a record designed to follow the patient. A Health Information Exchange (HIE) is the infrastructure that moves records between organisations and assembles one longitudinal record. OpenSeva now simulates an HIE: four EMR "tenants" feed a shared FHIR store, and the genuinely hard interoperability problems — patient matching, consent, deduplication, provenance — become concrete, gradeable student projects.

The cross-org matching scenario (the teaching payoff)

The seed deliberately registers the same human at several orgs with slightly different demographics and a different MRN each — exactly what a Master Patient Index must resolve. No single EMR sees the whole picture.

Load the HIE demo

./run.sh start          # stack up (or: docker compose up -d)
./run.sh seed           # base single-clinic demo (optional)
./seed-hie.sh           # the multi-EMR HIE layer (idempotent)

Verify a tenant-scoped view and confirm Priya's record is split across orgs:

# Hospital B's patients only (→ Priya + Omar)
curl 'http://localhost:8080/Patient?organization=Organization/org-hospital-b'

# Priya's diabetes lives only at Clinic A; her Metformin only at Pharmacy D
curl 'http://localhost:8080/Condition?subject=Patient/hie-a-priya'
curl 'http://localhost:8080/MedicationDispense?subject=Patient/hie-d-priya'

OpenSeva is built to be handed to students: they pick a ticket from ROADMAP.md, build it, and raise a PR; maintainers review and merge. Every ticket lists the FHIR resources, acceptance criteria, and exact files to touch — no reverse-engineering required. Setup and the PR workflow live in CONTRIBUTING.md.