How hapifhir/hapi-fhir-jpaserver-starter works
Project Type and Purpose
• This is a Spring-Boot “starter” Java server application exposing a FHIR REST API and accompanying web UI using the HAPI FHIR JPA module.
• It is intended as a drop-in FHIR server (with optional modules for Clinical Reasoning, CDS Hooks, MDM, subscriptions, Elasticsearch full-text, etc.) that can be run standalone (Jetty/Spring Boot), in Docker, via Kubernetes Helm charts, or in any Servlet 3.0+ container.
File-Structure and Architectural Patterns
• Top‐level: build files (pom.xml, Dockerfile, Helm charts under /charts), CI workflows, docker-compose.yml, configs.
• /src/main/java: SpringBoot application classes under starter/, grouped by feature packages (cdshooks, common, cr, ig, ips, mdm, terminology, web).
• These packages each define Spring @Configuration beans, @Interceptor, @Provider and conditional loading via custom @On* annotations.
• /src/main/resources: application.yaml, cds.application.yaml, logback.xml, mdm-rules.json
• /src/main/webapp: Thymeleaf templates + static assets for the built‐in tester UI.
• Patterns:
• Layered architecture:
– Web layer: Spring MVC Controllers + ServletInit via Application.java.
– Service/Interceptor layer: HAPI FHIR interceptors, providers (custom operations, hooks).
– Persistence layer: Spring Data JPA / Hibernate against H2 or external RDBMS, plus optional Elasticsearch.
• Module‐based configuration: each feature (CDS Hooks, CR, MDM, etc.) lives in its own package and is conditionally enabled.
• Deployment artifacts:
• Jar/WAR → runs in Spring Boot or standard servlet container.
• Docker image with multi-stage build, distroless variant.
• Helm chart for k8s deployment (/charts/hapi-fhir-jpaserver).
• docker-compose.yml for local docker+Postgres.
Key README Insights
• Default DB: H2 in-memory, but supports PostgreSQL or MS SQL via application.yaml overrides.
• Exposed endpoints: / (UI), /fhir (FHIR REST API), /websocket (if subscriptions enabled).
• Optional external dependencies: SMTP server (email subscriptions), Elasticsearch cluster (full-text and LastN), external CDS services (CDS Hooks RESTHook).
• Custom code points: interceptors, custom operations, runtime IG uploads.
Main Components
a. Clients
– Web browser UI (Thymeleaf static template + JS tester)
– REST clients (FHIR API callers, Postman, EHR integrators)
– CDS Hooks external services (if RESTHook enabled)
b. Spring-Boot Application
– Application entry point (Application.java)
– Web Layer: JobController, CdsHooksServlet, RestfulServer
– Feature Modules:
• Common configuration (datasource, JPA, Hibernate)
• CDS Hooks (CdsHooksServlet, CdsHooksProperties)
• Clinical Reasoning (Cql compiler, CrProperties, PostInitProviderRegisterer)
• Implementation Guides (ImplementationGuideOperationProvider)
• IPS, Terminology, MDM modules (conditional configs)
• ElasticsearchConfig (if enabled)
– Interceptor and Operation Providers (hooked into HAPI’s interceptor framework)
c. Persistence Layer
– Relational DB (H2 / Postgres / MS SQL) via Spring Data JPA + Hibernate
– Elasticsearch cluster (optional)
– In-memory topic cache & channel factory for subscriptions
d. External Services
– SMTP server for email subscriptions
– External REST endpoints for RESTHook subscriptions or CDS Hooks
– Message broker (if customized beyond in-memory)
– Kubernetes API (if deployed via Helm chart)
– Docker registry
Relationships and Data Flows
• Client → HTTP → Spring MVC / RestfulServer → HAPI FHIR interceptors/providers → JPA → RDBMS
• If Elasticsearch enabled: JPA events trigger Elasticsearch indexing via ElasticsearchConfig
• Subscriptions: create/activate in DB → in-memory topic cache → on resource change → HTTP/WebSocket/Email notifications to subscribers
• CDS Hooks: incoming hook → CdsHooksServlet → Clinical Reasoning service → RESTHook outbound calls → return CDS cards
• MDM: triggered by resource events via subscriptions → MdmConfig matching rules → write back golden patient links
• Runtime IG installs: POST /ImplementationGuide/$install → resource persisted → FHIR IG loader applies definitions to server context
Architectural Patterns and Design Principles
• Modular feature toggles via Spring conditional annotations (@OnCorsPresent, @OnR4Condition, etc.)
• Layered separation: Web → Service/Interceptor → Persistence → External
• Convention over configuration: auto-discovery of interceptors/providers via Spring context or reflection
• Container‐friendly: externalized configuration via application.yaml, environment variables, volume mounts
• Infrastructure as code: Dockerfiles, docker-compose.yml, Helm charts for k8s