Delivery journal · The context behind the implementationDiscuss a similar challenge ↗
Case study, United States

Medplum EHR for a consumer health records company: a clinician web app on FHIR

We built the clinician side of a consumer health records product: chart, timeline, labs, care plans, tasks, scheduling, messages and invoices, all on a self-hosted Medplum FHIR server, with the company's own sign-in and strict separation between practices.

November 22, 2026 · 14 min read · Jitendra Choudhary, CTO & Co-Founder

Medplum EHR clinician web app on a laptop and phone: patient timeline with summary panel, and the task list

This was custom healthcare software development on an open-source FHIR server, so the company got a working EHR in months and kept its data in a standard shape.

Why a consumer health records company needed an EHR

The company already had an app where people keep their health story: readings, documents, health journeys and reading material. Clinicians caring for those people still worked in other systems. The company wanted a professional web app on the same kind of record, so the two sides could share data later without translation.

Speed to a real chart

Building an EHR data layer from scratch takes years. The company needed a usable chart in months.

Standard data

A private schema would make every future connection a custom project. FHIR R4 makes the record portable.

One login across products

The company runs its own sign-in. Clinicians should not get a second password.

Practices kept apart

Each practice must see only its own patients and staff, with no chance of leakage.

  1. 1

    Apr 2025

    FHIR server live on the company's cloud; first chart screens

  2. 2

    May

    Company sign-in working end to end

  3. 3

    June

    Care plans, scheduling and booking complete

  4. 4

    July

    Email notices, messages, invoices, education library

  5. 5

    August

    Multi-tenant setup proven, scope for phase two

Dates from the project channel, read Nov 22, 2026.

Four roles, one record: what each person does

Screens below follow the delivered app: its layout from screen recordings, and its routes, tabs and form labels from the code.

The physician before a visit

Opens one chart and sees the story: allergies, problems, medications, vitals, then the timeline of readings, labs and messages.

  1. Reads the summary

    Allergies, problem list with codes, active medications, latest vitals.

  2. Scans the timeline

    Visits, labs, orders, messages and images in one list, loaded in one batch.

  3. Checks a trend

    Lab values over time against the normal range.

  4. Writes and signs

    The encounter note, linked to the visit and its orders.

  5. Updates the plan

    Goals, activities and reading material for the patient.

Medplum EHR patient timeline with allergies, problem list, medications and vitals panel

Patient timeline, with the summary panel.

Lab results list with a hemoglobin trend chart against the normal range

Lab results, with the trend for the selected test.

New encounter form with SOAP note and linked orders

Encounter note, linked to vitals and orders.

Care plan with activities and goal progress

Care plan: activities, goals and progress.

The nurse or care coordinator

Works the task list urgent first, answers messages, sends questionnaires before visits and attaches reading material from the company's library.

Task list with an urgent callback task and its detail panel

Tasks, with owner, due date and history.

Patient messages inbox with a conversation thread

Messages with patients.

Questionnaire response with answers and total score

Questionnaire response and history.

Attach education material from the company library to a care plan activity

Reading material from the company's library, attached to a care plan.

The front desk and the practice admin

Set availability once for weeks, block time, confirm or decline requests with an email to the patient, book in five steps and issue invoices.

Weekly schedule with appointments, open slots and appointment requests

Schedule, with requests waiting for a decision.

Five-step booking wizard on the select time step

Booking wizard, step 3 of 5.

Set availability form creating repeating slots with a preview

Set availability, with the slots it will create.

Invoice with charge items and codes

Invoice from the visit.

What we built: 23 clinician scenarios on one FHIR record

The web app has 47 page routes. They group into 25 scenarios, and 23 of them shipped to the client's development environment. Medications and vaccinations have routes but were left for a later phase.

Sign in

One company account through Keycloak. The app exchanges that token for a FHIR server session.

Patients

A searchable list, a new patient form with Form and JSON views, and edit.

Chart summary

Allergies with onset and reaction, problem list, medications, vitals, smoking status.

Timeline

Visits, messages, readings and files in one feed, loaded with one batch request.

Encounters

Visit details, height, weight and blood pressure, with a questionnaire attached.

Lab results

Results with trend charts, and new measurements added in place.

Diagnostic reports

A custom form whose pickers show only this patient's results, specimens and images.

Care plans

Goals and activities: medication, service and education requests, with library material.

Questionnaires and tasks

Open forms as tasks, answers saved as questionnaire responses.

Mail

A practitioner inbox and per-patient threads, newest first.

Scheduling

Calendar and agenda, set and block availability, a five-step booking, confirm or decline.

Admin and billing

Practitioners, organizations, and invoices built from charge items.

Clinician chart with allergies, problem list, medications and vitals, and the add allergy form

Chart summary. Every value is a FHIR resource on the server.

New diagnostic report form with results, specimen and performer pickers

The report form we rebuilt, so every picker shows this patient only.

Clinician mail inbox with patient conversations and a reply box

Mail. Messages are FHIR Communication records.

Appointment requests with confirm and decline

Requests. Confirm or decline, and the patient gets an email.

Block availability modal over a weekly calendar

Block time. Free slots change in one transaction.

Admin list of organizations and the new organization form

Organizations. Each one sees only its own users and patients.

Ask anything: an AI assistant on the patient's own record

The patient app has an AI health assistant, shown here on the company's test site. The company built the assistant. We wrote the clinician-side connection, which was finished and waiting on a Keycloak token when this phase closed. The design keeps the assistant safe in plain ways: it does not diagnose and sends the person to their provider, it recommends vetted articles from the company library, and it keeps a chat history.

AI health assistant in the patient app: chat history, a grounded answer, a recommended library article

Layout from the test site.

One test answer walked back an earlier claim. The lesson we carry into AI work: ground every answer in the library and in the person's own FHIR records, and test the same question several times for consistent answers before release.

Citations are what make an answer checkable. A record value is quoted with its date, and each library source appears as a "Read article" card the person can open. No source means no claim.

Ask anything answer grounding: retrieve own FHIR records and library articles, answer only from them, cite sourcesOpen full size

The FHIR complexity under a simple screen

A clinician sees one form. Underneath, every save is a FHIR write that has to be safe to repeat, scoped to the right organization, coded in a standard vocabulary and traceable. Each item below says whether we built it, designed it, or relied on Medplum for it.

Idempotent write path: transaction bundles built, conditional create and webhook dedupe designedOpen full size
Idempotency and retriesBuiltDesigned
Built: availability, blocking and the booking step each send one transaction Bundle, so a slot is never half held. Designed: creates that can repeat carry a business key and use a conditional create on that key, and a registration webhook that arrives twice is matched on the Keycloak user id before anything is created.
Deduplication across two organizationsDesigned
One person can be entered by a clinic and also sign up in the patient app. The identity rules look up the Keycloak id in Patient.identifier first, then run a demographic search, and link a possible match only after the patient or staff confirm it. Two accounts for one person are merged, and the duplicate is set inactive with a replaced-by link. The flow is below.
Versioning and concurrencyMedplum provides
Medplum keeps every version of a resource and returns an ETag. An update can send If-Match with that version, so two people editing one chart cannot silently overwrite each other. This phase used plain updates. Version-checked updates are the next step for shared charts.
Search and pagingBuilt
Screens use standard search parameters: subject and patient references, _sort by date or last update, _count, _include on Observation:subject and the :not modifier on Task status. The timeline loads five resource types in one batch request. Lists page on the server, never in the browser.
References across projectsDesigned
Each organization is its own Medplum project. A patient seen by two organizations needs one identity and clear rules for which project holds the record and who may read it. The design keeps one Patient per person, keyed by the Keycloak id, and shares by link and permission instead of copying the chart.
AccessPolicy and compartmentsBuiltMedplum provides
Medplum enforces access policies on the server per project, and one organization could not see the other's users in testing. In the app, an access policy also hides fields a form should not show, such as the managing organization on a new patient. The FHIR Patient compartment is the natural unit for a patient's own access.
Subscriptions and webhooksDesigned
Medplum supports FHIR Subscriptions and bots. We evaluated them for calendar sync and for registration events and documented the approach. This phase shipped without them. The phase 2 registration design uses a Keycloak extension webhook into our API.
TerminologyBuilt
Vitals are coded in LOINC: blood pressure panel 85354-9, heart rate 8867-4, weight 29463-7, height 8302-2, temperature 8310-5, oxygen saturation 2708-6, glucose 15074-8, head circumference 9843-4, smoking status 72166-2. Activity and status fields accept SNOMED CT codes. Medication coding in RxNorm is planned with the medications tab.
Validation and profilesMedplum provides
Medplum validates every write against the base FHIR R4 definitions, so a malformed resource is refused at the server. This phase used base resources without custom profiles. US Core profiles are the next step when outside systems start reading the data.
AuditMedplum provides
Medplum records version history for every resource and can write AuditEvent records for access. Provenance for imported records, to show where a value came from, belongs to the records import design in What comes next.
Patient dedupe decision flow across two organizations: identifier lookup, demographic search, confirm, link, create or mergeOpen full size

Care plans in full

A care plan is the most connected record in the app. One plan writes a CarePlan, its Goals and one request per activity, and the patient sees the same plan with its reading material.

Care plan resource graph: CarePlan, Goal, MedicationRequest, ServiceRequest, CommunicationRequest, library article, Task, patient appOpen full size
Care plan detail with activities and goal progress

Plan detail: goals with targets, and activities with their status.

New care plan with an education activity and a library article attached

An education activity with an article from the company library.

Part of the planFHIR resourceWhat it does
The planCarePlanTitle, status, intent and the patient. The viewer shows nested goals and activities, which the stock viewer did not.
TargetsGoalWhat the patient is working toward, with a target and status.
Medication activityMedicationRequest, intent orderA drug to take as part of the plan.
Service activityServiceRequest, intent orderA test or referral. It shows on the Tasks tab.
Education activityCommunicationRequestReading material from the company library, searched from the form.
Follow-up workTaskWork owned by staff or the patient, such as a questionnaire to return.

The patient app reads the same CarePlan, so the person sees their goals and the attached articles without a second copy. Review caught one bug worth naming: picking a second article replaced the first, and deleting one removed it from other activities. The rule we took from it: attachments belong to one activity, never to the plan as a whole.

The architecture

One Next.js app, built on Medplum's React components and Mantine, talks to one FHIR server. Sign-in goes through the company's Keycloak. Email goes through Amazon SES. There is no private database to keep in sync.

Medplum EHR system architecture: Next.js web app, Keycloak sign-in, Medplum FHIR server with access policies, email and content libraryOpen full size

Standard records are what make later connections cheap. See our healthcare interoperability work for how FHIR data moves between systems.

Map of each EHR screen to the FHIR resources it reads and writes

FHIR compatibility: what is standard, and what that buys

The app stores everything as FHIR R4 resources on Medplum. It writes 20 resource types, from Patient and Encounter to CarePlan, Appointment and Invoice. It uses standard search parameters, sorting, _include, a batch Bundle for the timeline and transaction Bundles for scheduling. Any FHIR R4 client can read the same data. Records from outside systems can arrive later without a new database.

Matrix of 16 clinician scenarios against the FHIR resources each one reads or writesOpen full size

Why a custom interface on Medplum, and not Medplum's own app

Medplum's app is built for administrators and developers. Clinicians needed the company's own design, its own words and fewer screens. We kept the Medplum client, React provider, types and test mocks. We rebuilt 26 component groups where the stock ones stopped short. The app has 126 test files, most of them on the invoice and form sections.

What we kept from the Medplum SDK and what we rebuilt as custom componentsOpen full size
Deployment of Medplum on AWS: app, API and storage endpoints, PostgreSQL, Redis, Keycloak and SES
What the clinician web app connects to: Medplum, Keycloak, Amazon SES, company content API

The hard problems, and how we solved them

Medplum gives a strong FHIR server and good components. A product on top of it still meets real limits. These are the ones we hit and what we did.

Identity and tenancy: one sign-in, separate organizations, one patient record

The company runs one Keycloak realm for practitioners and patients. In the first phase, two organizations were set up by hand, each with its own Medplum project. A practitioner signs in through Keycloak, and the app swaps that token for a Medplum session. The second phase was designed: registration on a Keycloak screen, a Keycloak extension that calls our API, Medplum admin APIs that create the organization, project and user, and invites for doctors from inside the app.

Identity and tenancy: Keycloak realm, Medplum projects per organization, patient sharing, phase 1 and phase 2Open full size

The patient app and the clinician app must find the same person. We wrote the identity rules: the Keycloak id is saved in Patient.identifier under its own system, a clinic-made record is linked only after a confirmation step, and a fuzzy match never links on its own.

Patient identity resolution: search by identifier, then demographics, confirm before linking, merge rulesOpen full size
Sign-in sequence: Keycloak authorization code with PKCE, then token exchange at the Medplum FHIR server
Company sign-in into the FHIR server+
The FHIR server's built-in external login did not fit a company-run Keycloak with a custom-branded login page. We wrote the flow by hand: authorization code with PKCE at Keycloak, then an RFC 8693 token exchange at the FHIR server, so it issues its own session token. We proved it as a working demo in May, then moved it into the main code.
Users who exist in two places+
A person must exist in Keycloak and in the FHIR server to sign in, and the FHIR server expects its own password for a user. We kept the password in Keycloak only and linked the two: the Keycloak user id is saved as an identifier on the Patient or Practitioner, so other company apps can find the same person.
Practices that must never see each other+
We chose one Medplum project per organization, inside one Keycloak realm. Two test organizations were set up by hand, and one organization could not see the other's users. Medplum would not create a second organization on the same domain, so the second one moved to a subdomain. Self-service creation of an organization was designed for the next phase.
A patient who must never be created twice+
A patient can start in the patient app or be entered by a clinic first. We designed the matching: look up by the Keycloak identifier, then by name, birth date and contact, and link a possible match only after the patient or staff confirm it. Two accounts for one person merge into one record, with the duplicate marked as replaced. When unsure, the system keeps two records and a person resolves them later, because a wrong link would show one person's data to another.
Registration with no callback+
Medplum's admin APIs create a user and a project but send no callback. The phase 2 design has a custom Keycloak registration call our API, a Keycloak extension send a webhook, and our API create the Medplum records and check the result itself.
Stock components that stopped short+
The patient summary could not add a dated allergy or plot glucose and blood pressure. The report form searched with empty filters, so its dropdowns stayed blank. The care plan viewer showed only top-level fields. We rebuilt the summary and vitals, wrote a report form that filters by patient, and built a care plan view for nested goals and activities.
Booking without double booking+
Set Availability and Block Availability each write all their slots in one FHIR transaction bundle. The booking step creates the appointment as proposed, then holds every chosen slot as busy-tentative in one transaction, so a slot is never half held. Confirm and decline send the patient an email through Amazon SES.
Booking flow: five steps ending in one FHIR transaction bundle for slot and appointment
A domain run from another cloud account+
The company's domain lived in a different AWS account from the one running the FHIR server, and the standard setup needs certificates in one region. We worked the naming and certificates out with the company's team so the app, API and storage endpoints came up on their domain.

Why Medplum: a FHIR-native backend made a FHIR EHR faster to build

The company wanted standard data from day one. Starting on a FHIR server meant the data model, API, auth and permissions already existed, and the team spent its time on clinician screens. Our assessment of the options, for this kind of product:

MedplumHAPI FHIRCloud FHIR stores (Azure, Google, AWS HealthLake)Firebase or a custom database
Time to first screenDays. Server, auth and React components readyWeeks. Server ready, auth and UI to buildWeeks. Store ready, app layer to buildMonths. Data model, API and FHIR mapping to build
FHIR coverageR4 REST, search, batch and transactionThe broadest, including most operationsR4 store, operations vary by vendorNone until you write it
Auth and permissionsOAuth, external identity providers, access policies per projectAdd your own, such as Keycloak and interceptorsCloud identity and rolesYour own rules
Workflow logicBots and subscriptions on the serverInterceptors in JavaCloud functions and eventsYour own code
App SDKTypeScript client, React components, mocks for testsJava client, no UI kitGeneric SDKsNo health SDK
Running costOpen source, self-hosted on the client's cloud accountOpen source, self-hostedPay per use, tied to one cloudLow to start, high to make compliant

We would choose Medplum again for a FHIR EHR with a custom interface. We built on it before for a neonatal and maternity EHR, and we compare the managed options in our FHIR data store comparison. We would also make two choices earlier: plan the custom components from the first design review, and set up identity and tenancy before the first clinical screen.

Buy, build or reuse

CapabilityChoiceWhy
FHIR server and data storeReuse: Medplum, self-hostedOpen source, FHIR R4, access policies and transactions built in. Saves years of data-layer work.
Chart and form building blocksReuse, then extendMedplum React components where they fit. Custom components where they stopped short.
Sign-inReuse the company's KeycloakOne login across the company's products. We built the link to the FHIR server.
EmailBuy: Amazon SESAlready in the company's cloud account.
Screens, booking, tenancy, care plansBuildThis is the product. It had to match the company's design and workflow.

Security as standard practice

  • The development environment sits behind the company's VPN.
  • Each tenant is its own FHIR project, with role-based access policies.
  • The FHIR server issues its own token for each session, after the company sign-in.
  • The development environment held test patients only, inside the company's own cloud account.

Before production we would move tokens out of browser session storage, remove a debug log of the access token and replace placeholder extension URLs with published profiles.

What we learned

LessonWhat we now do by default
Check every design against the stock component in week one.Map each screen to a Medplum component or a custom build, with an estimate, before the sprint starts.
Prove sign-in across two systems in a demo first.Build the identity flow as a small working demo, then move it into the product.
Design tenancy before the first clinical screen.Decide projects, realms and access policies up front, and test isolation with two organizations.
Agree who a patient is before importing anyone.Write identity rules first: identifier lookup, confirm before linking, merge with a replaced-by link.
Make every repeatable write safe to repeat.Use transaction bundles and business keys, and plan conditional creates for imports and webhooks.
Code clinical data in standard vocabularies from the start.Use LOINC for vitals and SNOMED CT for clinical codes, so outside systems can read the data.
Ground AI answers and show their sources.Answer only from retrieved records and articles, cite each one, and test the same question many times.
Make work traceable for the client.Ticket id in every commit, pull requests to the develop branch, acceptance criteria per ticket.

How this engagement ran

Time and material. The code lived in the company's own repository and cloud account from day one. Two-week sprints in the company's ticket tracker, a demo every week, acceptance criteria on each ticket and the ticket id in every commit.

The same company also asked us to rebuild its consumer mobile app. That was a separate assignment, told in our health data aggregation app case study.

What comes next

Designs for phase two. Not in the delivered code.

Concept: importing outside records into the chart with duplicates flagged

Concept. Import records from the patient app and outside sources, with duplicates checked.

Concept: consent and access list per patient

Concept. Who can see this patient's data, why, and until when.

Building an EHR on Medplum?

Tell us your sign-in, your tenancy model and the screens you need. We will show where Medplum fits as is and where it needs product engineering on top.

Book a 30-min call

Sources: the web app repository (routes, 26 resource types, 128 test files, counted Nov 22, 2026) and the project channel, Apr to Sep 2025. No outcome numbers are claimed.

Questions buyers ask

What is Medplum and why build an EHR on it?
Medplum is an open-source FHIR server with React components, access policies and transactions built in. Building on it skips years of data-layer work, so the team spends its time on the screens and workflows that make the product.
How long did the clinician web app take?
The FHIR server and first chart screens were live within about a week of kickoff in April 2025. Sign-in worked end to end in May, scheduling and care plans in June, and messages, invoices and email notices in July.
Can Medplum use our existing Keycloak or SSO?
Yes, with some work. We used authorization code with PKCE at Keycloak, then an RFC 8693 token exchange at the FHIR server. The Keycloak user id is stored on the Patient or Practitioner so other apps can find the same person.
How do you keep practices from seeing each other's data in Medplum?
One Medplum project per organization, inside one Keycloak realm. Two test organizations were set up by hand first, and one could not see the other's users or patients. The self-service flow, where registration creates the organization, project and user through Medplum admin APIs, was designed for the next phase.
Which Medplum components did you have to replace?
The patient summary and vitals charts, the diagnostic report form and the care plan viewer. We kept Medplum components wherever they fit the design.
How do you prevent double booking on a FHIR server?
Availability, blocks and bookings are written as FHIR transaction bundles. The slot and the appointment are saved together or not at all.
Does the web app have its own database?
No. Every screen reads and writes FHIR resources on the server. That keeps one source of truth and makes later connections simpler.
Can this connect to Epic, Cerner or the patient's own app later?
The data is already FHIR R4, which is what those connections use. Importing from the company's patient app and outside records is designed for phase two and is not in the delivered code.
Where is it hosted?
On the company's own AWS account, using Medplum's standard AWS setup: app, API and storage endpoints, a managed PostgreSQL database and Redis. The development environment sits behind a VPN.
How do you stop the same patient being created twice across a patient app and a clinician app?
Look the patient up by the sign-in identifier saved in Patient.identifier. If nothing matches, search by name, birth date and contact, and link a possible match only after the patient or staff confirm it. When unsure, keep two records and let a person merge them, because a wrong link exposes one person's data to another.