How Do You Build a Custom EHR on Medplum?

If you’re a CTO at a digital health company evaluating infrastructure for a custom clinical platform, you’ve probably narrowed your options to three paths: buy off-the-shelf and fight it, build from scratch and staff 20-50 engineers, or build on a platform that handles the plumbing so you focus on the clinical layer.

Medplum is that third path. And after shipping multiple production platforms on it, I have opinions about where it shines and where it doesn’t.

45% of venture-backed healthcare practices build their own EHR add-ons because the off-the-shelf option doesn’t fit their workflow. Medplum exists for exactly that segment: teams that need custom clinical software without rebuilding FHIR infrastructure from scratch.

This guide is the architecture walkthrough I wish someone had written when I started building on Medplum. Not the docs (those are good). Not a product overview. The builder’s perspective: what the architecture looks like, what we build on top, and what to watch out for.

I. Why Are CTOs Choosing Medplum for Custom EHR?

Six Key Reasons

1. FHIR-Native from Day One

Every query, mutation, and subscription operates on FHIR R4 resources without retrofitting. Applications speak the same data language as Epic, Cerner, and other FHIR-compliant systems from the start.

2. ONC Certification

CHPL listing #11745, Version 5, certified 12/31/2025. Covers 19 criteria including (g)(9), (g)(10), (b)(10), (b)(11). Meets 2015 Edition Cures Base EHR requirements for provider customers needing Medicare incentive program compliance.

3. Apache 2.0 License

Full source code ownership without vendor lock-in. Fork, modify, and self-host freely. No license fees on the open-source core–a primary driver for venture-backed startups.

4. Real Traction

• 20M+ patients on the platform
• 2,100+ GitHub stars
• 500K+ Docker downloads
• Y Combinator-backed

5. Developer-First Architecture

TypeScript end-to-end with React component library, bot framework for server-side logic, and GraphQL alongside REST. Teams already using TypeScript find Medplum native.

6. Wire Compatibility with Epic and Others

Data generated on Medplum is compatible with government-mandated standards via FHIR (g)(10), enabling data exchange with Epic, Cerner, and Athenahealth without custom translation layers.

II. What Does Medplum’s Architecture Look Like Under the Hood?

Seven tightly integrated components form the foundation:

1. FHIR R4 Data Store

PostgreSQL-backed, FHIR-native structure. Every entity is a FHIR resource (Patient, Encounter, Observation, MedicationRequest). Search parameters follow FHIR specifications (: exact,: contains, chained references). Profiles and extensions allow customization without breaking compliance. Bundles support batch operations (creating 50 resources in one transaction).

2. RESTful API + GraphQL

• REST: Full FHIR R4 API with CRUD operations on any resource type and bulk data export for (b)(10) compliance.
• GraphQL: Enables complex queries, reducing multiple REST calls. A single GraphQL query can fetch a Patient with recent Encounters, active Medications, and latest Observations simultaneously, useful for frontend development.

3. Subscription Engine (Real-Time Events)

Event-driven architecture allows defining FHIR Subscriptions on any resource type. When a resource is created, updated, or deleted, Medplum fires webhooks or triggers Bots. Critical for clinical workflows: when a lab result arrives (new Observation), notify the ordering provider; when a patient checks in (Encounter status change), update the waiting room dashboard. Eliminates polling, which doesn’t scale for clinical operations.

Why this matters: Real-time clinical workflows depend on this. When a lab result arrives (new Observation), trigger a notification to the ordering provider. When a patient checks in (Encounter status change), update the waiting room dashboard. Without subscriptions, you’re polling. Polling doesn’t scale for clinical workflows.

4. Bot Framework (Server-Side Logic)

TypeScript functions running server-side in response to events. Clinical business logic resides here:

• Validate incoming data against clinical rules
• Route orders to fulfillment queues
• Generate care plan reminders based on condition triggers
• Transform inbound HL7 messages into FHIR resources
• Implement custom clinical decision support (CDS) logic

Bots are the equivalent of Lambda functions, integrated into the FHIR event model. If you’ve built event-driven systems, this will feel familiar.

5. Identity and Access Management

• SMART on FHIR for third-party app authorization
• OAuth 2.0 + OpenID Connect for authentication
• Google Auth and SAML for enterprise SSO
• RBAC + ABAC via SMART scopes
• Compartment-based security: clinicians see only their patients; department heads see their department; admins see everything.
• Critical for multi-specialty builds where behavioral health data requires different visibility than primary care.

6. React UI Component Library

Pre-built components: patient search, encounter timeline, medication list with interactions, lab results viewer with reference ranges, scheduling calendar, questionnaire renderer. Typically used for internal tools; custom frontends are built for patient-facing experiences.

7. Integration Layer

• FHIR R4 APIs for EHR-to-EHR communication
• HL7 v2 message processing via Medplum Agent (ADT, ORU, ORM)
• SFTP for batch file exchange
• Medplum Agent: runs locally, connects to devices over low-level protocols (bedside monitors, lab instruments, non-FHIR equipment)

III. What Can You Build on Medplum?

Three tiers of capability determine which modules are used based on use case:

Core Infrastructure (Always On)

• FHIR Datastore and API
• Authentication and Authorization
• Compliance layer (HIPAA, SOC 2, CLIA-ready)
• Auditing and logging
• Subscriptions (event-based triggers)

Clinical Modules (Configure per Workflow)

• Charting and Notes: unified medical record view, SOAP capture
• Care Plans: custom templates, tracking, automation
• Medications: ePrescribe-ready, in-house formulary tracking
• Scheduling: patient-facing and internal, rule-based matching
• Questionnaires: intake forms, assessments, ePROs
• Billing and Payments: external billing connector integrations
• Messaging: chat, reminders, SMS, bot-triggered communications
• Analytics and Dashboards: role-based metrics, custom KPIs

Extensions (Enable per Use Case)

• RPM, Sidecar apps (SMART on FHIR launch), CDS
• DME workflows, LIS/LIMS, EMPI
• Interoperability Gateway (FHIR, HL7v2, SFTP)
• Specialty modules: pediatric, radiology, research

Principle: Modular, FHIR-native, API-first. Configure what matters; skip what doesn’t. A fertility clinic doesn’t need DME workflows; a research lab doesn’t need ePrescribe.

IV. What Does Building Production on Medplum Actually Look Like?

I follow a 4-phase engagement model. Each phase has a clear deliverable and a decision gate before the next.

Phase 1: Discovery and Design (2-4 weeks)

• Identify clinical workflows, user roles, and integration requirements
• Map workflows to Medplum’s module architecture
• Decide: which modules configure, which build custom, which skip
• Architecture document + technical specification

Phase 2: Core Setup and Module Development (4-8 weeks)

• Configure Medplum core (access policies, subscriptions, bots)
• Build custom modules (specialty-specific progress notes, lab workflows)
• Build custom frontend (React) if patient-facing experience needed
• Integrate accelerators: PHISecure for HIPAA data handling, ConnectHealth for FHIR client + EHR adapters, Launchpad for MVP framework

These accelerators cover 30-40% of the engineering on a typical build. That’s the difference between a 6-month project and a 3-month project.

Phase 3: Integration and Testing (2-4 weeks)

• Connect to labs, payers, patient apps, external EHRs
• HL7 v2 message processing via Medplum Agent (for device integration)
• End-to-end testing with clinical workflow scenarios
• Compliance verification (HIPAA, access controls, audit logging)

Phase 4: Deployment and Support (Ongoing)

• SaaS (Medplum Cloud + Mindbowser): fastest go-live. ~$2K/month production.
• On-Prem / Private Cloud: host on your AWS, Azure, or GCP. Full data control.
• Post-launch monitoring, bug fixes, feature iterations
• Quarterly compliance reviews

What This Looks Like in Practice (Real Builds)

Precision medicine platform:

A precision medicine platform needed a custom EHR for functional and longevity medicine providers. Off-the-shelf EHRs couldn’t support their data-intensive model: labs, lifestyle inputs, longitudinal tracking, so we built it on Medplum.

• Built: FHIR-native EHR with AI ambient scribe (real-time SOAP transcription), dynamic treatment plan engine, AI inbound assistant for patient scheduling
• Result: 70% reduction in provider documentation time, 60% drop in post-visit task delays. Deployed in under 90 days. Two contracts totaling $305,800 active relationship.

Pediatric care platform:

A multi-location pediatric care group needed smart scheduling and mobile access for parents. Existing EHR had no provider-patient matching logic and limited portal capabilities.

• Built: AI-driven scheduling engine with rule-based matching (age, visit type, location), mobile app for parents, role-based admin portal
• Result: 45% reduction in scheduling friction. 70%+ of families using the mobile app weekly.

RPM integration:

Wearable + vitals integration + alerting for remote monitoring in functional and home health use cases, built using Medplum bots and subscriptions.

A national EHR:

Country-scale custom EHR built for a Caribbean nation’s national health system. Open-source, government deployment. $131K engagement shows Medplum holds at national scale, not just startup MVPs.

The build time advantage: typical Medplum build ships production in 60% less time than a from-scratch build. That’s the math when the platform handles data storage, auth, audit logging, FHIR compliance, and event infrastructure out of the box.

V. How Do You Handle Compliance and Security on Medplum?

Medplum’s compliance posture is strong with one notable gap.

What Medplum provides out of the box:

• HIPAA: BAA available. PHI is encrypted at rest (AES-256) and in transit (TLS 1.3). Role-based access with full audit logging.
• SOC 2 Type II: Ready by design.
• ONC Certification: CHPL #11745. 19 certified criteria including (g)(9), (g)(10).
• CLIA-ready: For lab-related workflows.
• Cures Act compliant: Information blocking rules supported.

What I add on top:

• PHISecure: HIPAA-compliant data handling layer additional encryption, access controls, audit logging for complex data ops (migration, bulk processing, multi-system integration)
• Penetration testing: Per-deployment security assessment
• Custom access policies: Compartment-based security for multi-specialty builds

The honest gap: Medplum is certified on US Core STU 5.0.1. USCDI v3  Mandatory since January 2026 requires US Core 6.1.0. For most custom builds, this doesn’t block compliance your application layer can implement v3 data elements on top of Medplum’s FHIR R4 foundation. If you need full USCDI v3 certification at the platform level, verify Medplum’s update timeline. They’re pursuing HTI-4 compliance for January 2027.

What’s coming (2026 roadmap):

• HITRUST certification for the hosted environment (enterprise trust signal)
• HTI-4 compliance aligned to January 2027 enforcement
• Sharding and archiving for large-scale deployments

Explore a deeper comparison: Headless EHR Comparison: Medplum vs Healthie vs OpenEMR 

VI. How Does Medplum Compare to Other Platforms?

When Medplum wins:

• Full FHIR R4 compliance from the data layer up
• Source code ownership (Apache 2.0)
• TypeScript engineering team
• ONC certification without self-certifying
• Multiple specialties on a shared backend

When Medplum isn’t the best fit:

• Wellness/nutrition platform fast: Healthie has pre-built workflows
• Python-first team: Canvas Medical’s Python SDK is native
• Go live under 30 days with minimal customization: SaaS EHR is faster
• Large health system replacing Epic: not designed for 40-hospital scale

Healthie-specific: Healthie API: How to Supercharge Healthie EHR

VII. What’s on Medplum’s 2026 Roadmap?

I’ve been reading Medplum’s 2026 roadmap and monthly updates. Three themes.

1. Regulatory Readiness

• HITRUST certification for hosted environment (unlocks health system contracts)
• HTI-4 compliance aligned to January 2027 enforcement
• Significant investment for an 8-person team signals serious enterprise intent

2. Scale and Performance

• Sharding and archiving for larger datasets
• Infrastructure investments that benefit every builder on the platform

3. Developer Experience

• Enhanced scheduling and billing (the two modules builders most want Medplum to own)
• AI tooling: MCP support, advanced search, training/testing environments
• Plugin ecosystem: extend Medplum without forking. This is the one I’m watching most closely  if plugins work, it creates a Medplum marketplace where every builder’s work is reusable.

The FHIR R5 question: Medplum’s R5 development is paused. US Regulators Steering Committee (January 2024) said the next US Core targets FHIR R6, bypassing R5. Medplum is staying on R4 and monitoring R6 progress. This is the right call. Design for R4 now; expect R6 in 2028+.