A Modern, AI-Powered HL7 FHIR R5 Server Implementation in Java
FHIR4Java Agents is an enterprise-grade HL7 FHIR server implementation built with Java and Spring Boot. This project demonstrates the powerful combination of healthcare interoperability standards (FHIR R4B, R5 or future versions) with modern AI capabilities.
The server is designed to be configuration-driven, allowing healthcare organizations to:
- Support standard FHIR R5 resources, FHIR R4B resources and any future FHIR versions out of the box
- Support custom resources by defining custom resources without manual coding
- Extend functionality through a flexible plugin architecture
- Leverage AI for intelligent plugin discovery and orchestration
HL7 FHIR (Fast Healthcare Interoperability Resources) is the modern standard for exchanging healthcare information electronically. FHIR combines the best features of HL7's previous standards while leveraging the latest web technologies.
Key FHIR Resources:
- Organization - Healthcare oganization information
- Patient - Demographics and administrative information
- Encounter - Healthcare interactions
- Observation - Measurements, vital signs, lab results
- Condition - Problems, diagnoses
- Procedure - Clinical procedures
- MedicationRequest - Prescriptions
- CarePlan - Intention of how one or more practitioners intend to deliver care for a particular patient, group or community for a period of time, possibly limited to care for a specific condition or set of conditions.
| Feature | Description |
|---|---|
| FHIR R5 Support | Full support for HL7 FHIR R5 specification |
| RESTful API | Complete FHIR RESTful API implementation |
| CRUD Operations | Create, Read, Update, Delete for all resource types |
| Search | Advanced search with all standard parameters, modifiers, and prefixes |
| Extended Operations | Support for $validate, $merge, $everything |
| History | Full resource history and versioning |
| Validation | Resource validation against StructureDefinitions |
| CapabilityStatement | Auto-generated CapabilityStatement |
Full support for FHIR Search including:
- Common Parameters:
_id,_lastUpdated,_tag,_profile,_security,_source,_text,_content,_filter - Search Modifiers:
:exact,:contains,:missing,:not,:above,:below,:in,:not-in,:of-type - Search Prefixes:
eq,ne,gt,lt,ge,le,sa,eb,apfor date/number/quantity - Chaining:
subject:Patient.name=Smith - Reverse Chaining:
_has:Observation:subject:code=1234-5
- Multi-tenancy Ready - Support for multiple organizations
- Caching - Two-level caching (L1 in-memory + L2 Redis)
- Audit Logging - Comprehensive audit trail for compliance
- Performance Monitoring - Built-in telemetry and tracing
- High Availability - Designed for scalability with PostgreSQL
The application supports a hybrid plugin architecture with two approaches:
- Embedded plugins running in the same JVM
- Best for performance-critical operations
- Tight integration with Spring ecosystem
- Business logic plugins execute before/after FHIR operations
- Any Programming Language: Write plugins in Python, Node.js, Go, Rust, or any language
- Run Anywhere: Plugins can run as separate processes, containers, or remote services
- Hot-Pluggable: Update plugins without restarting the main server
- Fault Isolation: Plugin crashes don't affect the main FHIR server
With MCP protocol support, the application enables AI-powered plugin discovery:
- AI agents can dynamically discover available plugins and their capabilities at runtime
- Plugins expose their tools and resources through the standardized MCP interface
- AI can intelligently select and orchestrate plugins based on the task requirements
- No hardcoded plugin dependencies - the system adapts to available capabilities
This architecture aligns with the industry-standard Model Context Protocol adopted by Anthropic, OpenAI, Microsoft, and the Linux Foundation.
The fhir4java-mcp module provides MCP tools that enable AI agents to interact with the FHIR server:
| Tool | Description |
|---|---|
| fhir_discover | Discover FHIR server capabilities including available resources, search parameters, operations, and event subscription options |
| fhir_query | Query FHIR resources with support for read, search, history, and extended operations |
| fhir_mutate | Create, update, patch, and delete FHIR resources with dry-run validation support |
| Real-Time Events | Subscribe to resource changes via Server-Sent Events (SSE) or register webhooks for push notifications |
Refer to this document for details Design feature description and implementation plan
| Component | Technology |
|---|---|
| Language | Java 25 |
| Framework | Spring Boot 3.x |
| FHIR Library | HAPI FHIR |
| Database | PostgreSQL 16 with JSONB |
| Cache | Redis 7.x |
| Testing | JUnit 5, Cucumber BDD, TestContainers |
| Build | Maven |
| Containerization | Docker, Docker Compose |
- Java 25
- Maven 3.9+
- Docker & Docker Compose
- PostgreSQL 16+ (or use Docker)
- Redis 7+ (or use Docker)
# Clone the repository
git clone https://github.com/sg-victorchai/fhir4java-agents.git
cd fhir4java-agents
# Start all services
docker compose up -d
# Server will be available at http://localhost:8080/fhir/r5The project includes a Maven plugin module (fhir4java-codegen) that must be installed before building other modules. Use one of the following approaches:
Option 1: Using module exclusion (recommended)
# Install the codegen plugin first
./mvnw clean install -pl fhir4java-codegen
# Build remaining modules (excluding codegen from reactor)
./mvnw clean compile -pl !fhir4java-codegenOption 2: Using the skip-codegen-module profile
# Install the codegen plugin first
./mvnw clean install -pl fhir4java-codegen
# Build using the profile
./mvnw clean compile -P skip-codegen-moduleOption 3: Incremental builds (after initial setup)
# After codegen is installed, regular compile works
./mvnw compileSkip code generation entirely
./mvnw clean compile -Dfhir.codegen.skip=true -pl !fhir4java-codegenRun BDD tests
./mvnw verify -f fhir4java-server/pom.xml -Dtest=CucumberIT -Dfailsafe.useFile=false# Run this script to generate set of data for commmonly used FHIR resources
cd scripts/datagen
./create_fhir_data.shThe script allows you to specify the different parameters to generate realistic clinical workflow and data from encounter, observation, medication, procedure and care plan. The coded data elements use clinical terminologies such as SNOMED CT, LOINC, RxNorm and CPT as illustrated below
==========================================
SUMMARY
==========================================
Organization: Good Faith Clinic (ID: c86e204e-a1a3-4bb2-89ab-f315f10a58b8)
Date Range: 2023 - 2025
Batch Number: SIT02
Created:
- 1 Organization (Good Faith Clinic)
- 500 Patients (Singaporean names with batch suffix -SIT02)
- 3000 Encounters (6 per patient)
- 600000 Observations with LOINC codes:
* 4548-4: Hemoglobin A1c (Diabetes)
* 1558-6: Fasting glucose (Diabetes)
* 8480-6: Systolic BP (Hypertension)
* 8462-4: Diastolic BP (Hypertension)
* 2093-3: Total Cholesterol (Hyperlipidemia)
- 15000 MedicationRequests with RxNorm codes:
* 860975: Metformin 500 MG (Diabetes)
* 314076: Lisinopril 10 MG (Hypertension)
* 617311: Atorvastatin 20 MG (Cholesterol)
* 329528: Amlodipine 5 MG (Hypertension)
* 859751: Rosuvastatin 10 MG (Cholesterol)
- 6000 CarePlans with SNOMED CT coded goals:
* Diabetes Management (HbA1c target < 7.0%)
* Hypertension Management (BP target < 130/80)
* Hyperlipidemia Management (LDL target < 100)
- 1500 Procedures with SNOMED CT codes (3 per patient):
* 252416005: Blood pressure measurement
* 710824005: Electrocardiogram monitoring
* 413467001: Blood glucose monitoring
* 271442007: Foot examination
* 170258001: Diabetic retinal screening
Total: 626001 FHIR Resources
The sample data generation script is created by AI, you can get AI to further enhance to meet your data generation needs
# Get CapabilityStatement
curl http://localhost:8080/fhir/r5/metadata
# Create a Patient
curl -X POST http://localhost:8080/fhir/r5/Patient \
-H "Content-Type: application/fhir+json" \
-d '{"resourceType":"Patient","name":[{"family":"Smith","given":["John"]}]}'
# Search for Patients
curl "http://localhost:8080/fhir/r5/Patient?family=Smith"fhir4java-agents/
├── db/ # Database scripts (init, migrations, indexes)
├── docker/ # Docker and docker-compose files
├── infrastructure/ # AWS CDK deployment scripts
├── fhir4java-core/ # Core FHIR processing (config, validation, resource registry)
├── fhir4java-persistence/ # JPA entities, repositories, search implementation
├── fhir4java-api/ # FHIR RESTful APIs and real-time event APIs
│ ├── controller/ # - FHIR CRUD, search, operations endpoints
│ ├── event/ # - SSE streaming, webhook delivery
│ └── subscription/ # - Subscription management
├── fhir4java-plugin/ # Plugin framework (SPI and implementations)
├── fhir4java-mcp/ # MCP (Model Context Protocol) implementation
│ ├── tools/ # - fhir_discover, fhir_query, fhir_mutate
│ └── agent/ # - AI agent webhook handler, SSE client
├── fhir4java-codegen/ # Code generator for custom FHIR resources
├── fhir4java-server/ # Spring Boot application
│ └── src/main/resources/
│ └── fhir-config/ # FHIR configuration files
│ ├── resources/ # - Resource configs (patient.yml, observation.yml)
│ ├── r5/ # - R5 searchparameters, operations, profiles
│ └── r4b/ # - R4B searchparameters, operations, profiles
└── scripts/ # Utility scripts (datagen, etc.)
- Implementation Plan - Comprehensive design for the enterprise FHIR server
- HL7 FHIR R5 Specification
- FHIR RESTful API
- FHIR Search
- FHIR Operations
- HAPI FHIR Documentation
- Model Context Protocol
FHIR4Java Agents is suitable for:
- Healthcare Information Exchange (HIE) - Connecting disparate healthcare systems
- Electronic Health Records (EHR) - Building modern EHR backends
- Clinical Decision Support - Integrating AI with clinical data
- Patient Portals - Providing patients access to their health data
- Research Platforms - Supporting clinical research data management
- Health App Development - Backend for mobile health applications
- Interoperability Solutions - Connecting legacy systems with modern FHIR APIs
FHIR HL7 FHIR R5 Healthcare Interoperability Java FHIR Server Spring Boot FHIR HAPI FHIR Healthcare API Medical Records EHR Integration Clinical Data Health Information Exchange REST API JSON Healthcare Standards Interoperability Patient Data Clinical Resources SMART on FHIR Healthcare IT
Contributions are welcome! Please read our contributing guidelines before submitting pull requests.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- HL7 International for the FHIR specification
- HAPI FHIR for the excellent Java FHIR library
- Anthropic for Claude AI assistance in development