FHIR4Java Agents

A Modern, AI-Powered HL7 FHIR R5 Server Implementation in Java

---

Overview

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

What is HL7 FHIR?

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.

---

Features

Core FHIR Capabilities

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

Search Parameters

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, ap for date/number/quantity
• Chaining: subject:Patient.name=Smith
• Reverse Chaining: _has:Observation:subject:code=1234-5

Enterprise Features

• 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

Plugin Architecture

The application supports a hybrid plugin architecture with two approaches:

1. Native Code Plugins (Spring Bean)

• 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

2. MCP (Model Context Protocol) Plugins

• 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

AI Self-Discovery

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.

AI Agent Integration

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

Detail feature description and implementation plan

Refer to this document for details Design feature description and implementation plan

---

Technology Stack

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

---

Quick Start

Prerequisites

• Java 25
• Maven 3.9+
• Docker & Docker Compose
• PostgreSQL 16+ (or use Docker)
• Redis 7+ (or use Docker)

Run with Docker Compose

# 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/r5

Build from Source

The 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-codegen

Option 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-module

Option 3: Incremental builds (after initial setup)

# After codegen is installed, regular compile works
./mvnw compile

Skip code generation entirely

./mvnw clean compile -Dfhir.codegen.skip=true -pl !fhir4java-codegen

Run BDD tests

./mvnw verify -f fhir4java-server/pom.xml -Dtest=CucumberIT -Dfailsafe.useFile=false

Sample Test Data Generation

# Run this script to generate set of data for commmonly used FHIR resources
cd scripts/datagen
./create_fhir_data.sh

The 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

Example API Calls

# 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"

---

Project Structure

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

---

Documentation

• Implementation Plan - Comprehensive design for the enterprise FHIR server

External Resources

• HL7 FHIR R5 Specification
• FHIR RESTful API
• FHIR Search
• FHIR Operations
• HAPI FHIR Documentation
• Model Context Protocol

---

Use Cases

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

---

Keywords

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

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

---

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

Acknowledgments

• HL7 International for the FHIR specification
• HAPI FHIR for the excellent Java FHIR library
• Anthropic for Claude AI assistance in development