Building FhirHub: A Modern Healthcare Data Platform
By David Le
Healthcare data is fragmented. Patient records live across disconnected EHRs, labs send results via fax, and clinicians toggle between a dozen systems during a single encounter. The promise of interoperability has been around for decades, but the tooling to actually build standards-compliant healthcare applications remains inaccessible to most developers.
FhirHub is my answer to that problem. It's an open-source clinical data platform built on FHIR R4 that unifies patient demographics, vitals, labs, medications, and conditions into a single interface -- with proper authentication, role-based access, and bulk data export baked in from the start.
This post kicks off a 19-part series covering every layer of the system, from Docker infrastructure to single-machine k3s deployment.
Why I Built This
I wanted to prove that a single developer could build a production-grade healthcare application using modern open-source tools. No proprietary middleware. No vendor lock-in. Just FHIR, Docker, and widely-adopted frameworks.
The goals were:
- Standards-first: Every clinical data point flows through FHIR R4 resources
- Secure by default: SMART on FHIR authentication with fine-grained RBAC
- Developer-friendly: One
docker-compose upto run the entire stack - Real clinical logic: AHA blood pressure guidelines, lab reference ranges, clinical alerts
Tech Stack
Frontend
| Technology | Version | Purpose |
|---|---|---|
| Next.js | 16.1.5 | React framework with App Router |
| React | 19.2.3 | UI library |
| TypeScript | ^5 | Type safety |
| Tailwind CSS | ^4 | Utility-first CSS |
| DaisyUI | ^5.5.14 | Component library |
| Recharts | ^3.7.0 | Vitals charting |
| Keycloak-JS | ^26.0.0 | OIDC authentication |
| Zod | ^3.24.0 | Runtime validation |
| Vitest | ^4.0.18 | Testing framework |
Backend
| Technology | Version | Purpose |
|---|---|---|
| .NET | 8.0 | API framework |
| Hl7.Fhir.R4 | 6.0.2 | FHIR client library |
| FluentValidation | 11.3.0 | Request validation |
| JWT Bearer | 8.0.23 | Token authentication |
| Serilog | 8.0.3 | Structured logging |
| Swashbuckle | 6.4.0 | OpenAPI/Swagger |
Infrastructure
| Service | Image | Purpose |
|---|---|---|
| HAPI FHIR | hapiproject/hapi:latest | FHIR R4 server |
| Keycloak | keycloak:26.0 | Identity provider |
| PostgreSQL (HAPI) | postgres:18-alpine | FHIR data store |
| PostgreSQL (Keycloak) | postgres:18-alpine | Auth data store |
| FhirHub API | Custom .NET 8 | API gateway |
Architecture Overview
Feature Overview
FhirHub covers the full spectrum of a clinical data platform:
- Patient Management -- Search, create, and view patient demographics with FHIR Patient resources
- Vitals Tracking -- Record and chart blood pressure, heart rate, temperature, O2 saturation, respiratory rate, and weight with interactive Recharts visualizations
- Clinical Reference Ranges -- AHA blood pressure guidelines, 21+ lab reference ranges with FHIR interpretation codes
- Conditions & Medications -- View and create Condition and MedicationRequest resources
- Lab Results -- Lab panels with reference range highlighting
- Bulk Data Export -- 4-step wizard supporting NDJSON, JSON Bundle, and CSV formats with job lifecycle management
- SMART on FHIR -- Keycloak OIDC with PKCE, launch context simulator, token inspector, scope visualizer
- Role-Based Access -- 17 authorization policies across 6 roles (admin, practitioner, nurse, front_desk, patient)
- Dashboard -- Metrics, recent patients, activity feed, alerts panel, system status
- Admin Panel -- User management, audit logs
- Clinical Alerts -- Automated alerts for abnormal values
- Patient Timeline -- Chronological view of all clinical events
Series Roadmap
| # | Post | Topic |
|---|---|---|
| 1 | This post | Introduction and overview |
| 2 | Architecture Deep Dive | Docker Compose, data flow, auth flow |
| 3 | Getting Started | Setup and first run |
| 4 | SMART on FHIR Auth | Keycloak OIDC + PKCE |
| 5 | FHIR Resources | Patient, Observation, Condition |
| 6 | Vitals Charting | Recharts line charts |
| 7 | Clinical Ranges | AHA guidelines, lab ranges |
| 8 | Bulk Export | Export wizard and job lifecycle |
| 9 | .NET API Gateway | Middleware pipeline |
| 10 | Docker Compose | Infrastructure setup |
| 11 | Next.js Frontend | App Router, components |
| 12 | Keycloak Config | Realm and role setup |
| 13 | HAPI FHIR Setup | FHIR server configuration |
| 14 | Docker Multi-Stage Builds | Dockerfiles, Compose strategy |
| 15 | CI/CD with GitHub Actions | Reusable workflows, pipelines |
| 16 | Helm Charts | Kubernetes packaging |
| 17 | GitOps with ArgoCD | Multi-environment deployment |
| 18 | Monitoring | Prometheus, Grafana, Loki |
| 19 | Single-Node k3s | k3s deployment on one machine |
What's Next
In Part 2, we'll break down the Docker Compose architecture, trace a request from the browser through the API to HAPI FHIR, and examine how authentication flows through the system.