OpenSeva — Student Portal & Guide

▶ Watch the live visit simulation Auto-pilot through every hop — appointment → encounter → pharmacy → lab → claim → adjudication → EOB → copay — as animated 3D bubbles, with the cost adding up in real time. Open →

1 · What you are looking at

OpenSeva is a small but complete healthcare stack: an EMR (the clinical app), a FHIR® database (the medical record), an auth service, an insurance Payer with a Payment-Integrity engine, and supporting tools — all behind one door.

The learning goal isn't "click the app." It's to follow one patient through the system and, at each hand-off (a hop), ask two questions: which building block does the work, and where does cost enter? Roughly a quarter of denied claims trace back to problems that were cheap to fix early and expensive to fix late. By the end you should be able to point at a hop and pitch a concrete way to cut cost.

🧭

Follow the journey

Seven hops from booking to payment, each with its cost lens. Jump to the cost journey.

🔑

Log in & explore

Four roles, real screens. See access & credentials.

🤖

Drive it with AI

Ask Claude to run the stack in plain English via MCP.

2 · How the pieces fit together

Think of it as a small clinic plus an insurer. The EMR is where care is delivered and recorded; every record lives in the FHIR® database; when a bill goes out, the Payer prices it with help from a Payment-Integrity engine and returns an EOB. Here is how the data flows:

Clinician / front desk Insurer ┌─────────────┐ Claim ┌──────────────┐ check ┌────────────────┐ │ EMR │ ────────► │ Payer │ ────────► │ Payment │ │ (the app) │ ◄──────── │ (adjudicate) │ ◄──────── │ Integrity │ └──────┬──────┘ EOB └──────┬───────┘ downcode └────────────────┘ │ reads / writes │ writes ClaimResponse ▼ ▼ ┌──────────────────────────────────────┐ │ FHIR® database (records) │ └──────────────────────────────────────┘

Component	Role in the story	Open it
EMR	The clinical app clinicians & front desk use.	/emr/
FHIR® DB	The medical record — every Patient, Encounter, Claim lives here (on Postgres).	/fhir/
Auth	Logs users in and carries their role.	/auth/
Payer	The insurance company — checks eligibility, adjudicates claims, writes the EOB.	/payer/
Wellness	Prevention program — members share activity data; healthy habits earn premium discounts.	/wellness/
Payment Integrity	Pre-payment checks: downcoding + fraud scoring.	/integrity/
FHIR Admin	Browse/edit the raw records behind the app.	/admin/
Swagger	Interactive OpenAPI explorer for the FHIR API.	/swagger/
Dataset worker	Synthetic-data generation + the AI bridge.	/dataset/

3 · The cost journey — seven hops, one patient

This is the heart of the exercise. For each hop: who acts, the FHIR building block, where cost is incurred, and how it can be cut. Try each one live as you read.

Patient / Receptionist

Hop 1 — Book the appointment

A visit is scheduled. Nothing clinical yet, but the meter is already running.

Cost: staff phone time; empty slots from no-shows waste a clinician's hour.

Cut it: self-service booking + automated reminders fill slots and drop no-shows.

Building block: Appointment · try: EMR → Book Appointment

Receptionist

Hop 2 — Register & verify insurance

Capture who the patient is and whether their plan is active right now (a real-time 270/271 check).

Cost: ~1 in 4 denied claims trace to coverage problems found too late — the most expensive place to learn a plan lapsed is after the visit.

Cut it: check eligibility before the visit. Bad data caught at the desk costs pennies; caught at adjudication it's a denial.

Building block: Coverage, CoverageEligibilityResponse · try: EMR → patient → Insurance tab → Check eligibility (try Dana Lapsed for the failure case)

Doctor

Hop 3 — The visit & documentation

The encounter happens and the clinician documents findings.

Cost: thin notes get the claim downcoded (paid at a lower level) or trigger appeals — unpaid clinical work.

Cut it: complete, specific documentation defends the billed level the first time.

Building block: Encounter, Observation · try: EMR → Encounters

Doctor

Hop 4 — Orders: labs & medications

Tests and prescriptions are ordered.

Cost: duplicate tests and brand-name drugs when a prior result or a generic would do.

Cut it: reuse existing results; prefer generics — direct spend reduction with equal outcomes.

Building block: Observation (lab), MedicationRequest · try: EMR → Medications / Prescriptions

Admin / Biller

Hop 5 — Coding & the claim

The visit is coded and a claim is assembled and submitted to the payer.

Cost: an unclean claim bounces and enters a rework loop — staff time per resubmission, delayed cash.

Cut it: "clean claim first time" — correct codes + supporting notes before it goes out.

Building block: Claim · try: EMR (admin) → Revenue Cycle → submit

Payer + Payment Integrity

Hop 6 — Adjudication & integrity

The insurer prices the claim, runs downcoding + fraud checks, and returns an EOB (billed → allowed → plan paid → patient owes).

Cost: downcoding, denials, and fraud-review holds — value lost between "billed" and "paid".

Cut it: integrity checks before submission; align codes to documentation so the allowed amount holds.

Building block: ClaimResponse (EOB) · try: Payer dashboard + integrity API

Admin / Patient

Hop 7 — Patient responsibility

Whatever the plan didn't cover (copay, deductible) is owed by the patient.

Cost: balances billed after the visit are often never collected — pure leakage.

Cut it: collect the copay at the visit; show price up front so there are no surprises.

Building block: PaymentReconciliation, Invoice · try: EMR → Invoices

Run it live: node simulate-visit.js generates a brand-new patient every run and walks all of these hops — booking → encounter → dictation/orders → pharmacy → lab/imaging → claim → adjudication/EOB → copay — writing real FHIR records and printing the cost at each step. Then verify the patient, claim, and EOB in the UI. Run it a few times to compare a blood panel vs an X-ray vs an ultrasound cost layer.

Your assignment lens: pick any hop above and propose one concrete change (a check, a default, an automation, a data rule) that removes cost without hurting care. The cheapest dollar saved is the denial you never create.

4 · Access & credentials

Open the EMR and sign in as any role. All URLs are relative to this page's origin (…), so they work through whatever address you reached this page on.

Role	Email	Password	Sees / does
Admin / Biller	`admin@emr.local`	`admin123`	Everything + Revenue Cycle back office (claims, EOB, copay), users
Doctor	`doctor@emr.local`	`doctor123`	Encounters, documentation, prescriptions, coding
Receptionist	`reception@emr.local`	`reception123`	Registration, eligibility, copay, scheduling
Patient	`patient@emr.local`	`patient123`	Own chart, booking, own invoices

🏥

EMR application

The main clinical app.

/emr/

💳

Payer dashboard

Claims & eligibility.

/payer/

🏃

Wellness

Prevention & discounts.

/wellness/

🗄️

FHIR Admin

Raw records.

/admin/

🔥

FHIR API

R4 REST.

/fhir/

📘

Swagger

OpenAPI explorer.

/swagger/

🤖

Dataset worker

AI / data.

/dataset/

5 · APIs — the moves behind each screen

Every screen is just an API call. Here are the key ones; the full, clickable & testable catalog (with per-role EMR actions and an MCP export) is the API console.

Do this	Call	Service
Log in (get a token)	`POST /auth/api/login`	Auth
Find / read a patient	`GET /fhir/Patient` · `GET /fhir/Patient/{id}`	FHIR
Insurance on file	`GET /fhir/Coverage?beneficiary=Patient/{id}`	FHIR
Real-time eligibility (270/271)	`POST /payer/api/eligibility`	Payer
List insurers & plans	`GET /payer/api/payers`	Payer
Submit a claim	`POST /payer/api/claims`	Payer
Read the EOB / claim status	`GET /payer/api/claims/{id}`	Payer
Downcoding + fraud check	`POST /integrity/api/check`	Integrity
FHIR capabilities	`GET /fhir/metadata`	FHIR

Tip: open the API console → set the base URL to this origin → press Send on any row to see the live response, then Generate MCP tool catalog.

6 · Drive the stack with Claude (MCP)

The Model Context Protocol lets Claude Desktop operate this stack in plain English — "check eligibility for patient-local", "submit a 99214 claim and show me the EOB". You run a tiny local MCP server that forwards to the URLs above.

Get the code & install: clone the repo, then cd mcp-server && npm install.
Point it at this deployment — add this to Claude Desktop's claude_desktop_config.json (copy):
```
…
```
Get a PIN: in the EMR, open /emr/mcp-connect (or the "Connect AI Assistant" screen) and generate a one-time PIN.
Authenticate in Claude: start a chat and say "authenticate with PIN 123456". Your role's tools unlock.
Ask in plain English, e.g.:
"Find patients named Smith" "Check eligibility for patient-local" "Submit a 99214 claim to BlueShield and show the EOB" "What's my schedule today?"

The MCP server is role-gated (a receptionist gets eligibility tools; an admin gets claims/EOB) — the same permissions you see in the UI. Full details: API console → Export as MCP tools.

7 · Step-by-step: see the whole cost cycle in 8 moves

Open the EMR and accept the one-time disclaimer.
Reception (reception123): open a patient → Insurance → Check eligibility. Try Dana Lapsed to watch bad data become an Inactive result (Hop 2).
Doctor (doctor123): open Encounters, document a visit, review coding (Hops 3–4).
Admin (admin123): Revenue Cycle → submit a claim (Hop 5).
Watch it adjudicate on the Payer dashboard and read the EOB — billed → plan paid → patient owes (Hop 6).
Record the copay and close the balance (Hop 7).
Verify the raw records in the FHIR Admin console or FHIR API.
Now pick one hop and pitch a cost-cutting idea. That's the assignment.

8 · Deep-dive guides

🧭

Student Portal — understand every hop, and where healthcare cost hides