Engineering Case Study
Peerbits built a complete SMART App Launch → OAuth 2.0 + PKCE → patient‑context → FHIR resource access → Observation write‑back flow, and validated every step against Epic's FHIR R4 sandbox.
7
FHIR RESOURCES
80%+
TEST COVERAGE
201
WRITE STATUS
SMART launch flow
VERIFIEDOAuth 2.0 + PKCE
COMPLETEObservation write-back
201 OKReusable FHIR SDK
BUILTSMART launch flows supported
FHIR resources tested
Read / write operations completed
OAuth flows validated
Production readiness areas covered
Automated test coverage
Transparency note: internal Peerbits engineering demonstration, built and tested against Epic's non‑production sandbox. Not a client deployment; no live patient data was used. Epic is referenced only to identify the sandbox platform — nothing here implies Epic endorsement or certification.
CATEGORY
Healthtech · Interoperability
STANDARD
FHIR R4 · SMART App Launch
ENVIRONMENT
Epic non‑production sandbox
STACK
React + TypeScript, Node.js + NestJS, Redis
TIMELINE
3 weeks · 2 sprints
Why This Was Needed
Healthcare applications live or die by how easily they can plug into an EHR. Before diving into implementation, it's worth being explicit about what problem this solves and why it matters to a technical buyer evaluating an EHR integration partner.
THE PROBLEM
Every EHR exposes patient data differently, and most healthcare applications need to launch from inside the EHR, act on behalf of a specific clinician and patient, and read or write clinical data without ever seeing raw credentials.
THE SOLUTION SHAPE
Standardizes how an app is launched from within or alongside an EHR.
Authorizes the app without exposing credentials to the browser.
Standardizes the data model so the same code works across EHR vendors.
Build once, connect to any SMART-compatible EHR with configuration, not a rewrite.
Solution Approach
React SPA
Vite + TypeScript
BFF
Node.js + NestJS
SMART Launch
PKCE · scopes
Epic Auth Server
OAuth2 · OIDC
FHIR R4 APIs
Epic sandbox
Redis
cache · session
Credentials never reach client-side code — all auth proxied through the BFF
Handles only UI rendering and state; talks to the backend-for-frontend only, never to Epic directly.
Proxies the SMART on FHIR auth flow, normalizes FHIR responses, adds caching and audit logging. Credentials never reach client-side code.
Caches FHIR responses (5-minute TTL) and holds session tokens server-side.
Epic FHIR R4 sandbox plus Epic OAuth authorization server as the external system.
Technical Implementation
The launch sequence end-to-end — from app launch to the first authorized FHIR call.
Scopes used:
openid fhirUser launch/patient patient/Patient.read patient/Condition.read patient/Observation.read patient/Observation.write patient/MedicationRequest.read patient/AllergyIntolerance.read patient/Encounter.read
STEP 1
Discover authorization config via Epic .well-known/smart-configuration endpoint.
STEP 2
Generate code verifier and derive the code challenge (BASE64URL-SHA256), stored server-side.
STEP 3
Redirect the browser to Epic with the requested scopes and challenge.
STEP 4
User authenticates and selects patient context on Epic login screen; Epic redirects back with an authorization code and state.
STEP 5
Backend validates state (CSRF protection) and exchanges the code for tokens server-side — never in the browser.
STEP 6
Backend calls permitted FHIR endpoints; proactively refreshes before expiry and clears sessions on logout.
Coverage
Read, write, and search coverage across the FHIR resources exercised in the sandbox.
| Resource | Read | Write | Search | Status |
|---|---|---|---|---|
| Patient | ✔ | – | ✔ | Verified complete |
| Condition | ✔ | – | ✔ | Verified complete |
| Observation | ✔ | ✔ | ✔ | Verified complete |
| MedicationRequest | ✔ | – | ✔ | Verified complete |
| AllergyIntolerance | ✔ | – | ✔ | Verified complete |
| Encounter | ✔ | – | ✔ | Verified complete |
| DocumentReference | ✔ | – | ✔ | Verified complete |
Deepest Implementation
One of the strongest parts of this build: writing a structured clinical Observation back to Epic, not just reading data out.
OBSERVATION · EXAMPLE
LOINC CODE
8867-4 (Heart rate)
STATUS
final
VALUE
76
UNIT
beats/min
EFFECTIVE DATE
2026-07-14T09:12:00Z
Validation Process
Every claim in this case study was validated, not assumed.
SMART Launch — run end-to-end against the live sandbox launch URL.
FHIR APIs — every resource call executed against Epic FHIR R4 sandbox, not mocked.
Postman — a maintained collection covering auth, read, and write requests.
Capability testing — checked resource support against Epic CapabilityStatement.
Resource validation — responses checked against the FHIR R4 schema.
Reusable FHIR client package — one framework-agnostic, raw typed client per resource, reusable across FHIR-based projects.
Unit tests (Vitest) — ≥ 80% line coverage on the BFF and SDK.
Integration tests (Supertest) — full launch-to-write flow tested against the sandbox in CI.
E2E tests (Playwright) — five journeys through the patient-facing UI, sandbox-authenticated.
Performance baseline — recorded response times under sandbox rate limits.
What We Learned
The specific, sometimes unglamorous things that made this implementation real rather than a demo.
The patient and encounter context returned at token exchange has to be persisted and re-used consistently, or later FHIR calls silently return the wrong patient data.
Epic enforces requested scopes strictly; a resource left out of the initial scope request fails at call time, not at launch, so scope planning has to happen up front.
Synthetic sandbox patients don't always have data for every resource type, which looks like a bug until you cross-check against the sandbox patient roster.
Access tokens expire mid-session; refreshing proactively (rather than on 401) avoided dropped requests during longer clinical workflows.
Not every resource is populated or writable in the sandbox the same way it would be in production, so capability statements need to be checked per environment, not assumed from documentation.
Security & Operational Controls
Code verifier/challenge prevents authorization-code interception.
CSRF protection on every redirect back from Epic.
Tokens held server-side only; never exposed to the browser.
TLS enforced end-to-end, including sandbox calls.
Only the scopes required by the demo were requested.
Every FHIR read/write logged with actor, resource, and timestamp.
Engineering Outcomes
Successfully completed against Epic sandbox, end to end.
Workflow validated, including token refresh and session teardown.
Completed and confirmed via a 201 Created sandbox response.
FHIR client SDK, BFF auth module, and test harness ready for reuse.
Demonstrated across read, write, and search on seven FHIR resources.
What Would Change for Production
A sandbox demo proves engineering capability — it is not a production deployment. Here is exactly what changes when this moves into a live EHR integration.
Formal app registration with the target EHR vendor, replacing the sandbox client ID.
Epic (or equivalent) certification/approval process before production access.
Client secrets and signing keys managed through a secrets manager, not config files.
Explicit consent capture and management, tied to the data actually being accessed.
Uptime, latency, and error-rate monitoring on every FHIR call.
Respecting and gracefully handling the EHR vendor production rate limits.
Exponential backoff and idempotent retries for transient FHIR failures.
Tenant isolation and audit-grade logging suitable for a compliance review.
Beyond This Project
The FHIR client, the SMART auth module, and the test harness were built to be adapted to other SMART-compatible EHR platforms — not rewritten for each one.
This implementation was validated using the Epic SMART on FHIR sandbox environment. The architecture and reusable integration components are designed to accelerate production integrations with SMART on FHIR-compliant EHR platforms, subject to each vendor onboarding and certification process.
Tech Stack Used
Frontend
BFF / API layer
Cache + session
Interop standard
Authorization
EHR
Unit / integration
E2E tests
CI pipeline
Talk to the engineers who built and validated this SMART on FHIR flow, sandbox to production checklist included.
Discuss Your Epic or FHIR IntegrationDelivered industry-focused flawless digital products engaging India’s top talent every client desires.
Healthtech ,
Remote patient monitoring app helps to bridge the gap between patients and healthcare providers. It tracks the vitals of the patients and sends it to the doctors.
Healthtech , AWS / Cloud ,
A healthcare startup struggled with increasing loads of data and manual infrastructure management as its business expanded. Peerbits successfully built cloud infrastructure using AWS for their system possessing auto-scaling, automated and more.
Healthtech ,
Bluecheck is an app for Android and iOS that calculates your BMI based on the information you input at the time of registration, lets you monitor s...
