# hapifhir/hapi-fhir architecture

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

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

## Overview

HAPI FHIR is a Java API and framework for building HL7 FHIR clients and servers. A typical resource workflow begins with a FHIR resource represented using a version-specific model; server requests are captured as request details and can be handled by storage services, while clients construct REST queries. The repository also contains parsing, validation, terminology, narrative, FHIRPath, batch, and specialized server capabilities. The README establishes the client/server product scope; source excerpts and the source index support only a limited set of internal links, so uncertain runtime wiring is omitted.

Main entry points: [`hapi-fhir-base/src/main/java/ca/uhn/fhir/context/FhirContext.java`](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/FhirContext.java) (Version context), [`hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/dao/JpaStorageResourceParser.java`](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/dao/JpaStorageResourceParser.java) (JPA resource handling), [`hapi-fhir-jpaserver-searchparam/src/main/java/ca/uhn/fhir/jpa/searchparam/extractor/SearchParamExtractorService.java`](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-jpaserver-searchparam/src/main/java/ca/uhn/fhir/jpa/searchparam/extractor/SearchParamExtractorService.java) (Search indexing), [`hapi-fhir-server/src/main/java/ca/uhn/fhir/rest/api/server/RequestDetails.java`](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-server/src/main/java/ca/uhn/fhir/rest/api/server/RequestDetails.java) (Server request)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_models["FHIR model and context"]
  node_resource["FHIR resources<br/>[IResource.java]"]
  node_context["Version context<br/>[FhirContext.java]"]
  node_runtime_model["Runtime definitions"]
  node_search_params["Search definitions"]
end

subgraph group_formats["Parsing and validation"]
  node_parser["FHIR parsers<br/>[JsonParser.java]"]
  node_validator["Validation support"]
  node_fhirpath["FHIRPath<br/>[IFhirPath.java]"]
  node_narrative["Narrative generation"]
end

subgraph group_api["Client and server APIs"]
  node_client["FHIR client"]
  node_repository_query["Repository queries"]
  node_server_request["Server request"]
end

subgraph group_services["Storage and extensions"]
  node_dao_registry["DAO registry<br/>[DaoRegistry.java]"]
  node_jpa_resource["JPA resource handling"]
  node_search_extract["Search indexing"]
  node_search_query["JPA search queries"]
  node_mdm["Master data matching"]
  node_cds["CDS Hooks"]
  node_batch["Bulk export jobs"]
end

node_consumer(("FHIR application"))
node_database[("FHIR database")]

node_consumer -->|"uses client"| node_client
node_consumer -->|"sends requests"| node_server_request
node_context -->|"scans types"| node_runtime_model
node_search_extract -->|"uses context"| node_context
node_search_extract -->|"reads definitions"| node_search_params
node_jpa_resource -->|"uses context"| node_context
node_jpa_resource -->|"uses definitions"| node_runtime_model
node_search_query -->|"implements query builder"| node_repository_query
node_server_request -.->|"handles resources"| node_database

click node_resource "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/model/api/IResource.java"
click node_context "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/FhirContext.java"
click node_runtime_model "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/RuntimeResourceDefinition.java"
click node_search_params "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/RuntimeSearchParam.java"
click node_parser "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/parser/JsonParser.java"
click node_validator "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/support/IValidationSupport.java"
click node_fhirpath "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/fhirpath/IFhirPath.java"
click node_narrative "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/narrative/INarrativeGenerator.java"
click node_client "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-client/src/main/java/ca/uhn/fhir/rest/client/method/BaseQueryParameter.java"
click node_repository_query "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/repository/impl/MultiMapRepositoryRestQueryBuilder.java"
click node_server_request "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-server/src/main/java/ca/uhn/fhir/rest/api/server/RequestDetails.java"
click node_dao_registry "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-storage/src/main/java/ca/uhn/fhir/jpa/api/dao/DaoRegistry.java"
click node_jpa_resource "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/dao/JpaStorageResourceParser.java"
click node_search_extract "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-jpaserver-searchparam/src/main/java/ca/uhn/fhir/jpa/searchparam/extractor/SearchParamExtractorService.java"
click node_search_query "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-storage/src/main/java/ca/uhn/fhir/jpa/repository/searchparam/SearchParameterMapRepositoryRestQueryBuilder.java"
click node_mdm "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-jpaserver-mdm/src/main/java/ca/uhn/fhir/jpa/mdm/svc/MdmControllerSvcImpl.java"
click node_cds "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-server-cds-hooks/src/main/java/ca/uhn/hapi/fhir/cdshooks/controller/CdsHooksController.java"
click node_batch "https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-storage-batch2-jobs/src/main/java/ca/uhn/fhir/batch2/jobs/export/BulkExportJobService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_resource,node_context,node_runtime_model,node_search_params toneBlue
class node_parser,node_validator,node_fhirpath,node_narrative,node_database toneAmber
class node_client,node_repository_query,node_server_request toneMint
class node_dao_registry,node_jpa_resource,node_search_extract,node_search_query,node_mdm,node_cds,node_batch toneRose
class node_consumer toneIndigo
```

## Components

### FHIR model and context

- [FHIR resources](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/model/api/IResource.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/model/api/IResource.java`
- [Version context](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/FhirContext.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/context/FhirContext.java`
- [Runtime definitions](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/RuntimeResourceDefinition.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/context/RuntimeResourceDefinition.java`
- [Search definitions](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/RuntimeSearchParam.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/context/RuntimeSearchParam.java`

### Parsing and validation

- [FHIR parsers](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/parser/JsonParser.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/parser/JsonParser.java`
- [Validation support](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/context/support/IValidationSupport.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/context/support/IValidationSupport.java`
- [FHIRPath](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/fhirpath/IFhirPath.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/fhirpath/IFhirPath.java`
- [Narrative generation](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/narrative/INarrativeGenerator.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/narrative/INarrativeGenerator.java`

### Client and server APIs

- [FHIR client](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-client/src/main/java/ca/uhn/fhir/rest/client/method/BaseQueryParameter.java): `hapi-fhir-client/src/main/java/ca/uhn/fhir/rest/client/method/BaseQueryParameter.java`
- [Repository queries](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-base/src/main/java/ca/uhn/fhir/repository/impl/MultiMapRepositoryRestQueryBuilder.java): `hapi-fhir-base/src/main/java/ca/uhn/fhir/repository/impl/MultiMapRepositoryRestQueryBuilder.java`
- [Server request](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-server/src/main/java/ca/uhn/fhir/rest/api/server/RequestDetails.java): `hapi-fhir-server/src/main/java/ca/uhn/fhir/rest/api/server/RequestDetails.java`

### Storage and extensions

- [DAO registry](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-storage/src/main/java/ca/uhn/fhir/jpa/api/dao/DaoRegistry.java): `hapi-fhir-storage/src/main/java/ca/uhn/fhir/jpa/api/dao/DaoRegistry.java`
- [JPA resource handling](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/dao/JpaStorageResourceParser.java): `hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/dao/JpaStorageResourceParser.java`
- [Search indexing](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-jpaserver-searchparam/src/main/java/ca/uhn/fhir/jpa/searchparam/extractor/SearchParamExtractorService.java): `hapi-fhir-jpaserver-searchparam/src/main/java/ca/uhn/fhir/jpa/searchparam/extractor/SearchParamExtractorService.java`
- [JPA search queries](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-storage/src/main/java/ca/uhn/fhir/jpa/repository/searchparam/SearchParameterMapRepositoryRestQueryBuilder.java): `hapi-fhir-storage/src/main/java/ca/uhn/fhir/jpa/repository/searchparam/SearchParameterMapRepositoryRestQueryBuilder.java`
- [Master data matching](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-jpaserver-mdm/src/main/java/ca/uhn/fhir/jpa/mdm/svc/MdmControllerSvcImpl.java): `hapi-fhir-jpaserver-mdm/src/main/java/ca/uhn/fhir/jpa/mdm/svc/MdmControllerSvcImpl.java`
- [CDS Hooks](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-server-cds-hooks/src/main/java/ca/uhn/hapi/fhir/cdshooks/controller/CdsHooksController.java): `hapi-fhir-server-cds-hooks/src/main/java/ca/uhn/hapi/fhir/cdshooks/controller/CdsHooksController.java`
- [Bulk export jobs](https://github.com/hapifhir/hapi-fhir/blob/master/hapi-fhir-storage-batch2-jobs/src/main/java/ca/uhn/fhir/batch2/jobs/export/BulkExportJobService.java): `hapi-fhir-storage-batch2-jobs/src/main/java/ca/uhn/fhir/batch2/jobs/export/BulkExportJobService.java`

### Other components

- **FHIR application**
- **FHIR database**

## Connections

- FHIR application → FHIR client: uses client
- FHIR application → Server request: sends requests
- Version context → Runtime definitions: scans types (evidence: `hapi-fhir-base/src/main/java/ca/uhn/fhir/context/FhirContext.java`)
- Search indexing → Version context: uses context (evidence: `hapi-fhir-jpaserver-searchparam/src/main/java/ca/uhn/fhir/jpa/searchparam/extractor/SearchParamExtractorService.java`)
- Search indexing → Search definitions: reads definitions (evidence: `hapi-fhir-jpaserver-searchparam/src/main/java/ca/uhn/fhir/jpa/searchparam/extractor/SearchParamExtractorService.java`)
- JPA resource handling → Version context: uses context (evidence: `hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/dao/JpaStorageResourceParser.java`)
- JPA resource handling → Runtime definitions: uses definitions (evidence: `hapi-fhir-jpaserver-base/src/main/java/ca/uhn/fhir/jpa/dao/JpaStorageResourceParser.java`)
- JPA search queries → Repository queries: implements query builder (evidence: `hapi-fhir-storage/src/main/java/ca/uhn/fhir/jpa/repository/searchparam/SearchParameterMapRepositoryRestQueryBuilder.java`)
- Server request → FHIR database: handles resources
