# terminologyhub/open-termhub architecture

> Architecture diagram of the GitHub repository terminologyhub/open-termhub, 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/terminologyhub/open-termhub
- Repository: https://github.com/terminologyhub/open-termhub

## Overview

Open TermHub is a FHIR terminology server for browsing and querying terminology content, managing local terminology data, and optionally synchronizing content from TermHub. The principal request path is a client request through the terminology REST API, service implementation, repository service, and Lucene search/index layer. Separate R4/R5 FHIR providers expose terminology operations; bulk loading and asynchronous syndication support content updates. The graph uses the README and SOURCE INDEX references for documented or indexed relationships; where unsampled wiring cannot be verified, it is omitted.

Main entry points: [`src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java`](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java) (Entity service), [`src/main/java/com/wci/termhub/syndication/SyndicationManager.java`](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/syndication/SyndicationManager.java) (Syndication manager), [`src/main/java/com/wci/termhub/rest/TerminologyServiceRestImpl.java`](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/rest/TerminologyServiceRestImpl.java) (Terminology REST), [`src/main/java/com/wci/termhub/lucene/LuceneDataAccess.java`](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/lucene/LuceneDataAccess.java) (Lucene data access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surfaces"]
  node_termrest["Terminology REST"]
  node_bulkrest["Bulk load API"]
end

subgraph group_domain["Terminology operations"]
  node_bulkloader["Bulk loader"]
  node_entityservice["Entity service"]
  node_repoapi["Repository service"]
  node_models["Terminology models<br/>[Terminology.java]"]
end

subgraph group_search["Search and persistence"]
  node_searchparams["Search parameters"]
  node_querybuilder["Lucene query builder"]
  node_lucene[("Lucene data access")]
  node_indexmanager[("Index manager")]
  node_ecl["ECL conversion"]
end

subgraph group_fhir["FHIR interfaces"]
  node_fhirrest["FHIR REST"]
  node_r4["FHIR R4 providers"]
  node_r5["FHIR R5 providers"]
end

subgraph group_sync["Content synchronization"]
  node_syndication["Syndication manager"]
  node_jobservice["Syndication jobs"]
  node_scheduler["Syndication scheduler"]
end

node_client(("API client"))
node_termhub(("TermHub service"))

node_client -->|"calls"| node_termrest
node_termrest -->|"delegates"| node_entityservice
node_entityservice -->|"searches"| node_lucene
node_entityservice -->|"builds queries"| node_querybuilder
node_entityservice -->|"uses"| node_searchparams
node_entityservice -->|"implements"| node_repoapi
node_lucene -.->|"manages indexes"| node_indexmanager
node_termrest -.->|"converts ECL"| node_ecl
node_client -->|"calls"| node_fhirrest
node_fhirrest -.->|"serves R4"| node_r4
node_fhirrest -.->|"serves R5"| node_r5
node_client -->|"submits content"| node_bulkrest
node_bulkrest -.->|"loads"| node_bulkloader
node_termhub -->|"provides content"| node_syndication
node_scheduler -->|"schedules"| node_syndication
node_jobservice -->|"tracks jobs"| node_syndication
node_syndication -->|"updates content"| node_entityservice
node_lucene -.->|"indexes entities"| node_models

click node_termrest "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/rest/TerminologyServiceRestImpl.java"
click node_bulkrest "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/rest/BulkLoadRestImpl.java"
click node_fhirrest "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/fhir/rest/FhirServiceRestImpl.java"
click node_r4 "https://github.com/terminologyhub/open-termhub/tree/main/src/main/java/com/wci/termhub/fhir/r4"
click node_r5 "https://github.com/terminologyhub/open-termhub/tree/main/src/main/java/com/wci/termhub/fhir/r5"
click node_bulkloader "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/service/impl/BulkLoaderServiceImpl.java"
click node_entityservice "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java"
click node_repoapi "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/service/EntityRepositoryService.java"
click node_models "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/model/Terminology.java"
click node_searchparams "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/model/SearchParameters.java"
click node_querybuilder "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/lucene/LuceneQueryBuilder.java"
click node_lucene "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/lucene/LuceneDataAccess.java"
click node_indexmanager "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/lucene/LuceneIndexManager.java"
click node_ecl "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/ecl/EclToLuceneConverter.java"
click node_syndication "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/syndication/SyndicationManager.java"
click node_jobservice "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/syndication/SyndicationJobService.java"
click node_scheduler "https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/syndication/SyndicationSchedulerService.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_termrest,node_bulkrest,node_client toneBlue
class node_bulkloader,node_entityservice,node_repoapi,node_models toneAmber
class node_searchparams,node_querybuilder,node_lucene,node_indexmanager,node_ecl toneMint
class node_fhirrest,node_r4,node_r5 toneRose
class node_syndication,node_jobservice,node_scheduler,node_termhub toneIndigo
```

## Components

### API surfaces

- [Terminology REST](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/rest/TerminologyServiceRestImpl.java): `src/main/java/com/wci/termhub/rest/TerminologyServiceRestImpl.java`
- [Bulk load API](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/rest/BulkLoadRestImpl.java): `src/main/java/com/wci/termhub/rest/BulkLoadRestImpl.java`

### Terminology operations

- [Bulk loader](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/service/impl/BulkLoaderServiceImpl.java): `src/main/java/com/wci/termhub/service/impl/BulkLoaderServiceImpl.java`
- [Entity service](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java): `src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java`
- [Repository service](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/service/EntityRepositoryService.java): `src/main/java/com/wci/termhub/service/EntityRepositoryService.java`
- [Terminology models](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/model/Terminology.java): `src/main/java/com/wci/termhub/model/Terminology.java`

### Search and persistence

- [Search parameters](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/model/SearchParameters.java): `src/main/java/com/wci/termhub/model/SearchParameters.java`
- [Lucene query builder](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/lucene/LuceneQueryBuilder.java): `src/main/java/com/wci/termhub/lucene/LuceneQueryBuilder.java`
- [Lucene data access](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/lucene/LuceneDataAccess.java): `src/main/java/com/wci/termhub/lucene/LuceneDataAccess.java`
- [Index manager](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/lucene/LuceneIndexManager.java): `src/main/java/com/wci/termhub/lucene/LuceneIndexManager.java`
- [ECL conversion](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/ecl/EclToLuceneConverter.java): `src/main/java/com/wci/termhub/ecl/EclToLuceneConverter.java`

### FHIR interfaces

- [FHIR REST](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/fhir/rest/FhirServiceRestImpl.java): `src/main/java/com/wci/termhub/fhir/rest/FhirServiceRestImpl.java`
- [FHIR R4 providers](https://github.com/terminologyhub/open-termhub/tree/main/src/main/java/com/wci/termhub/fhir/r4): `src/main/java/com/wci/termhub/fhir/r4`
- [FHIR R5 providers](https://github.com/terminologyhub/open-termhub/tree/main/src/main/java/com/wci/termhub/fhir/r5): `src/main/java/com/wci/termhub/fhir/r5`

### Content synchronization

- [Syndication manager](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/syndication/SyndicationManager.java): `src/main/java/com/wci/termhub/syndication/SyndicationManager.java`
- [Syndication jobs](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/syndication/SyndicationJobService.java): `src/main/java/com/wci/termhub/syndication/SyndicationJobService.java`
- [Syndication scheduler](https://github.com/terminologyhub/open-termhub/blob/main/src/main/java/com/wci/termhub/syndication/SyndicationSchedulerService.java): `src/main/java/com/wci/termhub/syndication/SyndicationSchedulerService.java`

### Other components

- **API client**
- **TermHub service**

## Connections

- API client → Terminology REST: calls (evidence: `README.md`)
- Terminology REST → Entity service: delegates (evidence: `src/main/java/com/wci/termhub/rest/TerminologyServiceRestImpl.java`)
- Entity service → Lucene data access: searches (evidence: `src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java`)
- Entity service → Lucene query builder: builds queries (evidence: `src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java`)
- Entity service → Search parameters: uses (evidence: `src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java`)
- Entity service → Repository service: implements (evidence: `src/main/java/com/wci/termhub/service/impl/EntityServiceImpl.java`)
- Lucene data access → Index manager: manages indexes
- Terminology REST → ECL conversion: converts ECL
- API client → FHIR REST: calls (evidence: `README.md`)
- FHIR REST → FHIR R4 providers: serves R4
- FHIR REST → FHIR R5 providers: serves R5
- API client → Bulk load API: submits content (evidence: `README.md`)
- Bulk load API → Bulk loader: loads
- TermHub service → Syndication manager: provides content (evidence: `README.md`)
- Syndication scheduler → Syndication manager: schedules (evidence: `src/main/java/com/wci/termhub/syndication/SyndicationSchedulerService.java`)
- Syndication jobs → Syndication manager: tracks jobs (evidence: `src/main/java/com/wci/termhub/syndication/SyndicationJobService.java`)
- Syndication manager → Entity service: updates content (evidence: `src/main/java/com/wci/termhub/syndication/SyndicationManager.java`)
- Lucene data access → Terminology models: indexes entities