# hapifhir/hapi-fhir-jpaserver-starter architecture

> Architecture diagram of the GitHub repository hapifhir/hapi-fhir-jpaserver-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hapifhir/hapi-fhir-jpaserver-starter
- Repository: https://github.com/hapifhir/hapi-fhir-jpaserver-starter

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        direction TB
        Browser["Web Browser UI"]:::external
        RESTClient["REST Clients (FHIR API)"]:::external
        CDSExternal["External CDS Hooks Services"]:::external
    end

    %% Spring-Boot Server
    subgraph "Spring Boot Application"    
        direction TB

        subgraph "Web Layer"
            direction TB
            Application["Application.java"]:::core
            AppProps["AppProperties.java"]:::core
            JobController["JobController"]:::core
            CdsHooksServlet["CdsHooksServlet"]:::optional
            CustomContentConfig["CustomContentFilesConfigurer"]:::core
            WebAppConfig["WebAppFilesConfigurer"]:::core
            RestfulServer["RestfulServer (HAPI FHIR)"]:::core
        end

        subgraph "Feature Modules"
            direction TB
            subgraph "Common Config" 
                direction TB
                StarterJpaConfig["StarterJpaConfig.java"]:::core
                FhirServerConfigR4["FhirServerConfigR4.java"]:::core
            end
            ElasticsearchConfig["ElasticsearchConfig.java"]:::optional
            subgraph "CDS Hooks Module"
                direction TB
                CdsHooksProps["CdsHooksProperties.java"]:::optional
                StarterCdsHooksConfig["StarterCdsHooksConfig.java"]:::optional
            end
            subgraph "Clinical Reasoning Module"
                direction TB
                PostInitProvider["PostInitProviderRegisterer.java"]:::optional
                CrR4Config["StarterCrR4Config.java"]:::optional
                CrDstu3Config["StarterCrDstu3Config.java"]:::optional
            end
            subgraph "Implementation Guides Module"
                direction TB
                IGR4Provider["ImplementationGuideR4OperationProvider.java"]:::optional
                IGR5Provider["ImplementationGuideR5OperationProvider.java"]:::optional
            end
            StarterIpsConfig["StarterIpsConfig.java"]:::optional
            MdmConfig["MdmConfig.java"]:::optional
            TerminologyConfig["TerminologyConfig.java"]:::optional
            subgraph "Validation Factories"
                direction TB
                RepoValFactoryR4["RepositoryValidationInterceptorFactoryR4.java"]:::core
            end
        end

        subgraph "Persistence Layer"
            direction TB
            RDBMS["Relational DB (H2/Postgres/MS SQL)"]:::core
            ESCluster["Elasticsearch Cluster"]:::optional
            TopicCache["In-memory Topic Cache"]:::core
            ChannelFactory["Channel Factory"]:::core
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SMTP["SMTP Server"]:::external
        RESTHookExt["External RESTHook Endpoints"]:::external
        MsgBroker["Message Broker"]:::external
        K8sAPI["Kubernetes API"]:::external
        DockerRegistry["Docker Registry"]:::external
    end

    %% Data Flows
    Browser -->|HTTP/8080| RestfulServer
    RESTClient -->|FHIR REST Call| RestfulServer
    RestfulServer -->|invokes| StarterJpaConfig
    RestfulServer -->|invokes| FhirServerConfigR4
    RestfulServer -->|uses| RepoValFactoryR4
    RestfulServer -->|handles| CdsHooksServlet
    CdsHooksServlet -->|reads| CdsHooksProps
    CdsHooksServlet -->|invokes| StarterCdsHooksConfig
    PostInitProvider -->|registers| RestfulServer
    RestfulServer -->|JPA Save/Query| RDBMS
    RDBMS -->|events| ElasticsearchConfig
    ElasticsearchConfig -.->|indexes| ESCluster
    RestfulServer -->|onResourceChange| TopicCache
    TopicCache -->|publishes| ChannelFactory
    ChannelFactory -->|notifies| Browser
    ChannelFactory -->|emails| SMTP
    CdsHooksServlet -->|outbound RESTHook| RESTHookExt
    TopicCache -->|MDM Trigger| MdmConfig
    MdmConfig -->|writes| RDBMS

    %% Deployment Artifacts
    Dockerfile["Dockerfile"]:::external
    Compose["docker-compose.yml"]:::external
    HelmChart["charts/hapi-fhir-jpaserver/"]:::external
    Browser -->|pull image| Dockerfile
    Dockerfile -->|runs| SpringBootApplication
    HelmChart -->|deploys| SpringBootApplication
    K8sAPI -->|manages| HelmChart
    Compose -->|spins up| SpringBootApplication
    Compose -->|spins up| RDBMS

    %% Click Events
    click Application "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/Application.java"
    click AppProps "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/AppProperties.java"
    click StarterJpaConfig "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/common/StarterJpaConfig.java"
    click FhirServerConfigR4 "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/common/FhirServerConfigR4.java"
    click ElasticsearchConfig "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/common/ElasticsearchConfig.java"
    click JobController "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/web/JobController.java"
    click CustomContentConfig "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/web/CustomContentFilesConfigurer.java"
    click WebAppConfig "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/web/WebAppFilesConfigurer.java"
    click CdsHooksServlet "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/cdshooks/CdsHooksServlet.java"
    click CdsHooksProps "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/cdshooks/CdsHooksProperties.java"
    click StarterCdsHooksConfig "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/cdshooks/StarterCdsHooksConfig.java"
    click PostInitProvider "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/cr/PostInitProviderRegisterer.java"
    click CrR4Config "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/cr/StarterCrR4Config.java"
    click CrDstu3Config "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/cr/StarterCrDstu3Config.java"
    click IGR4Provider "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/ig/ImplementationGuideR4OperationProvider.java"
    click IGR5Provider "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/ig/ImplementationGuideR5OperationProvider.java"
    click StarterIpsConfig "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/ips/StarterIpsConfig.java"
    click MdmConfig "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/mdm/MdmConfig.java"
    click TerminologyConfig "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/terminology/TerminologyConfig.java"
    click RepoValFactoryR4 "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/java/ca/uhn/fhir/jpa/starter/common/validation/RepositoryValidationInterceptorFactoryR4.java"
    click ApplicationYaml "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/application.yaml"
    click CdsAppYaml "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/cds.application.yaml"
    click MdmRules "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/mdm-rules.json"
    click Dockerfile "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/tree/master/Dockerfile"
    click Compose "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/docker-compose.yml"
    click HelmChart "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/tree/master/charts/hapi-fhir-jpaserver/"
    click K8sAPI "https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/.github/workflows/maven.yml"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef optional fill:#E6FFEA,stroke:#22863A,color:#22863A,stroke-dasharray: 5 5
    classDef external fill:#FFF5E6,stroke:#D9822B,color:#D9822B
```
