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, we 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 we wish someone had written when we 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 reasons, in the order they usually matter to technical decision-makers:

A. FHIR-native from day one

Not retrofitted. Not a FHIR API bolted onto a proprietary database. The data model IS FHIR R4 resources. Every query, every mutation, every subscription operates on FHIR. This means your application speaks the same data language as Epic, Cerner, and every other FHIR-compliant system from the first line of code.

B. Apache 2.0 license

Full source code ownership. Fork it, modify it, self-host it. No vendor lock-in. No license fees on the open-source core. This is the reason funded startups choose Medplum over SaaS EHR vendors – you own the IP.

C. Real traction, not vaporware

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

D. Developer-first architecture

TypeScript end-to-end. React component library. Bot framework for server-side logic. GraphQL alongside REST. If your engineering team writes TypeScript, Medplum feels native. If they don’t, the learning curve exists.

E. Wire compatibility with Epic+

Data generated on Medplum is compatible with government-mandated standards via FHIR (g)(10). Your Medplum application can exchange data with Epic, Cerner, and athenahealth through standardized FHIR APIs without custom translation layers.

For context on how Medplum compares to other headless platforms, see our existing blog on what Medplum is.

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

Seven components, tightly integrated. Understanding these is the difference between building fast and fighting the framework.

A. FHIR R4 Data Store

PostgreSQL-backed, FHIR-native. Every entity in the system is a FHIR resource – Patient, Encounter, Observation, MedicationRequest, etc. No ORM mapping. No impedance mismatch. You query FHIR resources directly.

• Search parameters follow the FHIR spec (:exact, :contains, chained references)
• Profiles and extensions let you customize resources without breaking compliance
• Bundles for batch operations (create 50 resources in one transaction)

B. RESTful API + GraphQL

• REST: Full FHIR R4 API. CRUD operations on any resource type. Bulk data export for (b)(10).
• GraphQL: For complex queries that would require multiple REST calls. Especially useful for frontend development – fetch a Patient with their recent Encounters, active Medications, and latest Observations in one query.

B. Subscription Engine (Real-Time Events)

Event-driven architecture. Define a FHIR Subscription on any resource type – when that resource is created, updated, or deleted, Medplum fires a webhook or triggers a Bot.

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.

D. Bot Framework (Server-Side Logic)

This is where Medplum diverges from being “just a FHIR server.” Bots are TypeScript functions that run server-side in response to events. They’re where your clinical business logic lives:

• Validate incoming data against clinical rules
• Route orders to the right fulfillment queue
• Generate care plan reminders based on condition triggers
• Transform inbound HL7 messages into FHIR resources
• Implement custom CDS logic

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

E. 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
• Role-based and attribute-based access control (RBAC + ABAC) via SMART scopes

The access policy model supports compartment-based security – a clinician sees only the patients assigned to them, a department head sees all patients in their department, an admin sees everything. This is critical for multi-specialty builds where behavioral health data has different visibility rules than primary care.

F. React UI Component Library

Pre-built React components for common healthcare UI patterns:

• Patient search and demographics
• Encounter timeline
• Medication list with interactions
• Lab results viewer with reference ranges
• Scheduling calendar
• Questionnaire renderer

You can use these as-is for rapid prototyping or as building blocks for fully custom UIs. We typically use them for internal tools and build custom frontends for patient-facing experiences.

G. Integration Layer

• FHIR R4 APIs for EHR-to-EHR communication
• HL7 v2 message processing (ADT, ORU, ORM) via the Medplum Agent
• SFTP for batch file exchange
• The Medplum Agent runs in your local network and connects to devices over low-level protocols – this is how you integrate bedside monitors, lab instruments, and other devices that don’t speak FHIR

III. What Can You Build on Medplum?

Medplum provides three tiers of capability. Which ones you use depends on your use case.

A. Core Infrastructure (Always On)

These run whether you configure them or not:

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

B. Clinical Modules (Configure per Workflow)

Each is API-accessible and customizable:

• Charting and Notes – unified medical record view, SOAP capture
• Care Plans – custom templates, tracking, and automation
• Medications – ePrescribe-ready, in-house formulary tracking
• Scheduling – patient-facing and internal, rule-based matching logic
• 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 and custom KPIs

C. Extensions (Enable per Use Case)

• Remote Patient Monitoring (RPM)
• Sidecar apps for Epic, Cerner, athenahealth (SMART on FHIR launch)
• Clinical Decision Support
• Durable Medical Equipment workflows
• LIS/LIMS (diagnostics)
• EMPI (Master Patient Index)
• Interoperability Gateway (FHIR, HL7v2, SFTP)
• Pediatric, radiology, research-specific modules

The principle: All modules are modular, FHIR-native, and API-first. Configure what you need without platform bloat. A fertility clinic doesn’t need DME workflows. A research lab doesn’t need ePrescribe. You turn on what matters.

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

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

A. 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

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

• Configure Medplum core (access policies, subscriptions, bots)
• Build custom modules (e.g., specialty-specific progress notes, lab workflows)
• Build a custom frontend (React) if a patient-facing experience is needed
• Integrate accelerators: PHISecure (HIPAA data handling), HealthConnect CoPilot (FHIR client + EHR adapters), Launchpad (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.

C. 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)

D. Phase 4: Deployment and Support (Ongoing)

• Choose deployment model:
• SaaS (Medplum Cloud + Mindbowser): Fastest go-live. Managed hosting, security, compliance, and updates. ~$2K/month production.
• On-Prem / Private Cloud: Host on your AWS, Azure, or GCP. Full control over data and access. Mindbowser manages infrastructure.
• Post-launch monitoring, bug fixes, feature iterations
• Quarterly compliance reviews

E. What This Looks Like in Practice (Real Builds, Anonymized)

1. Functional medicine platform

A digital health company needed a custom EHR for precision and functional medicine providers. Off-the-shelf EHRs couldn’t support their data-intensive model – labs, lifestyle inputs, longitudinal tracking.

• Built: FHIR-native EHR on Medplum core with AI-powered SOAP notes (voice-enabled transcription), dynamic treatment plan engine, and patient summary dashboard
• Result: 70% reduction in documentation time. Deployed in under 90 days with full IP ownership.

2. Pediatric care platform

A multi-location pediatric care group needed smart scheduling and mobile access for parents. The 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 use the mobile app weekly.

3. RPM integration

Built using Medplum bots and subscriptions – wearable + vitals integration + alerting for remote monitoring in functional and home health use cases.

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

Building a clinical platform and evaluating Medplum? Tell us about your workflow, and we’ll scope the architecture – which modules to configure, which to build custom, and the estimated timeline. For Medplum-specific engagements, see our Medplum integration services.

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

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

A. 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. Audit logging, access controls, and infrastructure meet SOC 2 requirements.
• ONC Certification: CHPL #11745. 19 certified criteria including the critical (g)(9) and (g)(10).
• CLIA-ready: For lab-related workflows
• Cures Act compliant: Information blocking rules supported

B. What we add on top

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

The honest gap: Medplum is currently certified with US Core STU 5.0.1 via the SVAP process. USCDI v3 (mandatory since January 2026) requires US Core 6.1.0. This means Medplum’s ONC certification is based on the previous US Core version. 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. But 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, which will likely address this.

C. What’s coming (2026 roadmap)

• HITRUST certification for the hosted environment – the enterprise trust signal many health systems require
• HTI-4 compliance aligned to January 2027 enforcement
• Sharding and archiving for large-scale deployments

VI. How Does Medplum Compare to Other Platforms?

Four options for building a custom clinical platform. Medplum is one of them.

A. When Medplum wins:

• You need full FHIR R4 compliance from the data layer up
• You want source code ownership (Apache 2.0)
• Your team writes TypeScript
• You need ONC certification without self-certifying
• You’re building for multiple specialties on a shared backend

B. When Medplum isn’t the best fit:

• You need a wellness/nutrition platform fast -> Healthie has pre-built patient engagement workflows
• Your team is Python-first and doesn’t want TypeScript -> Canvas Medical’s Python SDK is native
• You need to go live in under 30 days with minimal customization -> SaaS EHR is faster
• You’re a large health system replacing Epic -> Medplum isn’t designed for enterprise EHR replacement at 40-hospital scale

For the full platform comparison, read our headless EHR comparison: Medplum vs Healthie vs OpenEMR. For Healthie-specific workflows, see our Healthie API guide.

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

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

A. Regulatory Readiness

• HITRUST certification for the hosted environment – this is the enterprise trust signal that unlocks health system contracts
• HTI-4 compliance aligned to January 2027 enforcement – Medplum is preemptively certifying so builders don’t have to
• These are significant investments for an 8-person team. It signals they’re serious about enterprise healthcare, not just startup MVPs.

B. Scale and Performance

• Sharding and archiving for larger datasets – critical as Medplum deployments grow beyond the 20M patient mark
• Infrastructure investments that benefit every builder on the platform

C. Developer Experience

• Enhanced scheduling and billing – the two modules most builders want Medplum to own so they don’t have to build
• AI tooling – MCP support, advanced search, training/testing environments for AI-first clinical apps
• Plugin ecosystem – extending Medplum without forking the codebase. This is the one I’m watching most closely. If plugins work well, it creates a Medplum marketplace that makes every builder’s work reusable.

The FHIR R5 question: Medplum’s R5 development is paused. The US Regulators Steering Committee announced (January 2024) that the next version of US Core will be based on FHIR R6, effectively bypassing R5. Medplum is staying on R4/US Core alignment and monitoring R6 progress. This is the right call. Building for R5 when regulators are targeting R6 would waste engineering cycles on a dead-end version. If you’re planning a build, design for R4 now and expect R6 in 2028+.