# wso2/fhir-server architecture

> Architecture diagram of the GitHub repository wso2/fhir-server, 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/wso2/fhir-server
- Repository: https://github.com/wso2/fhir-server

## Overview

WSO2 FHIR Server accepts FHIR REST requests, routes them through resource and system interactions, validates and searches resources, and persists versioned data and search indexes in PostgreSQL. Startup configures the database, base definitions, search parameters, tenancy and optional terminology; Implementation Guides can add profiles and search parameters. The graph also preserves documented validation, bundle, operations and observability capabilities. Several runtime files are unsampled, so edges for those documented capabilities cite the README rather than implying unseen call paths.

Main entry points: [`cmd/server/main.go`](https://github.com/wso2/fhir-server/blob/main/cmd/server/main.go) (Server startup), [`internal/handler/handlers.go`](https://github.com/wso2/fhir-server/blob/main/internal/handler/handlers.go) (FHIR interactions), [`internal/handler/router.go`](https://github.com/wso2/fhir-server/blob/main/internal/handler/router.go) (HTTP routing), [`internal/ig/ig.go`](https://github.com/wso2/fhir-server/blob/main/internal/ig/ig.go) (Implementation Guides)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_main["Server startup<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_tenant["Tenant resolution<br/>[tenant.go]"]
  node_seed["Base search seeding<br/>[seed.go]"]
end

subgraph group_api["FHIR API"]
  node_router["HTTP routing<br/>[router.go]"]
  node_handlers["FHIR interactions<br/>[handlers.go]"]
  node_bundles["Bundles and operations<br/>[bundle.go]"]
  node_handlerextras["Metadata operations<br/>[operations.go]"]
end

subgraph group_domain["FHIR semantics"]
  node_base["Base definitions<br/>[basedef.go]"]
  node_ig["Implementation Guides<br/>[ig.go]"]
  node_validation["Resource validation<br/>[validate.go]"]
  node_fhirpath["FHIRPath evaluation<br/>[eval.go]"]
  node_searchparams["Search parameters<br/>[definitions.go]"]
  node_terminology["Terminology client<br/>[client.go]"]
end

subgraph group_persistence["Persistence and search"]
  node_store["Resource lifecycle<br/>[store.go]"]
  node_search["Search execution<br/>[search.go]"]
  node_index["Write-time indexing<br/>[extractor.go]"]
  node_db["PostgreSQL access<br/>[db.go]"]
end

subgraph group_operations["Operations"]
  node_obs["Observability hooks<br/>[obs.go]"]
end

node_consumer(("FHIR client"))
node_postgres[("PostgreSQL")]

node_consumer -->|"sends requests"| node_router
node_main -.->|"loads settings"| node_config
node_main -->|"connects database"| node_db
node_main -.->|"loads definitions"| node_base
node_main -.->|"configures registry"| node_searchparams
node_main -.->|"seeds parameters"| node_seed
node_main -->|"constructs store"| node_store
node_main -.->|"loads guides"| node_ig
node_main -->|"configures client"| node_terminology
node_main -.->|"starts HTTP service"| node_router
node_router -->|"routes interactions"| node_handlers
node_router -->|"resolves tenant"| node_tenant
node_router -->|"applies middleware"| node_obs
node_handlers -->|"reads and writes"| node_store
node_handlers -->|"validates resources"| node_validation
node_handlers -.->|"dispatches bundles"| node_bundles
node_handlers -.->|"offers operations"| node_handlerextras
node_handlers -->|"uses profiles"| node_ig
node_store -->|"executes searches"| node_search
node_store -->|"builds indexes"| node_index
node_store -->|"persists resources"| node_postgres
node_db -.->|"creates schema"| node_postgres
node_search -->|"uses definitions"| node_searchparams
node_search -->|"resolves terminology"| node_terminology
node_index -->|"extracts parameter values"| node_searchparams
node_index -->|"evaluates expressions"| node_fhirpath
node_base -->|"compiles profiles"| node_validation
node_validation -->|"evaluates invariants"| node_fhirpath
node_ig -->|"registers definitions"| node_searchparams
node_ig -.->|"supplies profiles"| node_validation
node_ig -.->|"downloads packages"| node_consumer

click node_main "https://github.com/wso2/fhir-server/blob/main/cmd/server/main.go"
click node_config "https://github.com/wso2/fhir-server/blob/main/internal/config/config.go"
click node_router "https://github.com/wso2/fhir-server/blob/main/internal/handler/router.go"
click node_handlers "https://github.com/wso2/fhir-server/blob/main/internal/handler/handlers.go"
click node_bundles "https://github.com/wso2/fhir-server/blob/main/internal/handler/bundle.go"
click node_handlerextras "https://github.com/wso2/fhir-server/blob/main/internal/handler/operations.go"
click node_tenant "https://github.com/wso2/fhir-server/blob/main/internal/tenant/tenant.go"
click node_obs "https://github.com/wso2/fhir-server/blob/main/internal/obs/obs.go"
click node_base "https://github.com/wso2/fhir-server/blob/main/internal/basedef/basedef.go"
click node_ig "https://github.com/wso2/fhir-server/blob/main/internal/ig/ig.go"
click node_validation "https://github.com/wso2/fhir-server/blob/main/internal/validate/validate.go"
click node_fhirpath "https://github.com/wso2/fhir-server/blob/main/internal/fhirpath/eval.go"
click node_searchparams "https://github.com/wso2/fhir-server/blob/main/internal/searchparam/definitions.go"
click node_store "https://github.com/wso2/fhir-server/blob/main/internal/store/store.go"
click node_search "https://github.com/wso2/fhir-server/blob/main/internal/store/search.go"
click node_index "https://github.com/wso2/fhir-server/blob/main/internal/index/extractor.go"
click node_db "https://github.com/wso2/fhir-server/blob/main/internal/db/db.go"
click node_terminology "https://github.com/wso2/fhir-server/blob/main/internal/terminology/client.go"
click node_seed "https://github.com/wso2/fhir-server/blob/main/internal/seed/seed.go"

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_main,node_config,node_tenant,node_seed,node_consumer toneBlue
class node_router,node_handlers,node_bundles,node_handlerextras,node_postgres toneAmber
class node_base,node_ig,node_validation,node_fhirpath,node_searchparams,node_terminology toneMint
class node_store,node_search,node_index,node_db toneRose
class node_obs toneIndigo
```

## Components

### Server runtime

- [Server startup](https://github.com/wso2/fhir-server/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Configuration](https://github.com/wso2/fhir-server/blob/main/internal/config/config.go): `internal/config/config.go`
- [Tenant resolution](https://github.com/wso2/fhir-server/blob/main/internal/tenant/tenant.go): `internal/tenant/tenant.go`
- [Base search seeding](https://github.com/wso2/fhir-server/blob/main/internal/seed/seed.go): `internal/seed/seed.go`

### FHIR API

- [HTTP routing](https://github.com/wso2/fhir-server/blob/main/internal/handler/router.go): `internal/handler/router.go`
- [FHIR interactions](https://github.com/wso2/fhir-server/blob/main/internal/handler/handlers.go): `internal/handler/handlers.go`
- [Bundles and operations](https://github.com/wso2/fhir-server/blob/main/internal/handler/bundle.go): `internal/handler/bundle.go`
- [Metadata operations](https://github.com/wso2/fhir-server/blob/main/internal/handler/operations.go): `internal/handler/operations.go`

### FHIR semantics

- [Base definitions](https://github.com/wso2/fhir-server/blob/main/internal/basedef/basedef.go): `internal/basedef/basedef.go`
- [Implementation Guides](https://github.com/wso2/fhir-server/blob/main/internal/ig/ig.go): `internal/ig/ig.go`
- [Resource validation](https://github.com/wso2/fhir-server/blob/main/internal/validate/validate.go): `internal/validate/validate.go`
- [FHIRPath evaluation](https://github.com/wso2/fhir-server/blob/main/internal/fhirpath/eval.go): `internal/fhirpath/eval.go`
- [Search parameters](https://github.com/wso2/fhir-server/blob/main/internal/searchparam/definitions.go): `internal/searchparam/definitions.go`
- [Terminology client](https://github.com/wso2/fhir-server/blob/main/internal/terminology/client.go): `internal/terminology/client.go`

### Persistence and search

- [Resource lifecycle](https://github.com/wso2/fhir-server/blob/main/internal/store/store.go): `internal/store/store.go`
- [Search execution](https://github.com/wso2/fhir-server/blob/main/internal/store/search.go): `internal/store/search.go`
- [Write-time indexing](https://github.com/wso2/fhir-server/blob/main/internal/index/extractor.go): `internal/index/extractor.go`
- [PostgreSQL access](https://github.com/wso2/fhir-server/blob/main/internal/db/db.go): `internal/db/db.go`

### Operations

- [Observability hooks](https://github.com/wso2/fhir-server/blob/main/internal/obs/obs.go): `internal/obs/obs.go`

### Other components

- **FHIR client**
- **PostgreSQL**

## Connections

- FHIR client → HTTP routing: sends requests (evidence: `README.md`)
- Server startup → Configuration: loads settings
- Server startup → PostgreSQL access: connects database (evidence: `cmd/server/main.go`)
- Server startup → Base definitions: loads definitions
- Server startup → Search parameters: configures registry
- Server startup → Base search seeding: seeds parameters
- Server startup → Resource lifecycle: constructs store (evidence: `cmd/server/main.go`)
- Server startup → Implementation Guides: loads guides
- Server startup → Terminology client: configures client (evidence: `cmd/server/main.go`)
- Server startup → HTTP routing: starts HTTP service
- HTTP routing → FHIR interactions: routes interactions (evidence: `internal/handler/router.go`)
- HTTP routing → Tenant resolution: resolves tenant (evidence: `internal/handler/router.go`)
- HTTP routing → Observability hooks: applies middleware (evidence: `internal/handler/router.go`)
- FHIR interactions → Resource lifecycle: reads and writes (evidence: `internal/handler/handlers.go`)
- FHIR interactions → Resource validation: validates resources (evidence: `internal/handler/handlers.go`)
- FHIR interactions → Bundles and operations: dispatches bundles
- FHIR interactions → Metadata operations: offers operations
- FHIR interactions → Implementation Guides: uses profiles (evidence: `internal/handler/handlers.go`)
- Resource lifecycle → Search execution: executes searches (evidence: `internal/store/store.go`)
- Resource lifecycle → Write-time indexing: builds indexes (evidence: `internal/store/store.go`)
- Resource lifecycle → PostgreSQL: persists resources (evidence: `README.md`)
- PostgreSQL access → PostgreSQL: creates schema
- Search execution → Search parameters: uses definitions (evidence: `internal/store/search.go`)
- Search execution → Terminology client: resolves terminology (evidence: `internal/store/search.go`)
- Write-time indexing → Search parameters: extracts parameter values (evidence: `internal/index/extractor.go`)
- Write-time indexing → FHIRPath evaluation: evaluates expressions (evidence: `internal/index/extractor.go`)
- Base definitions → Resource validation: compiles profiles (evidence: `internal/basedef/basedef.go`)
- Resource validation → FHIRPath evaluation: evaluates invariants (evidence: `internal/validate/validate.go`)
- Implementation Guides → Search parameters: registers definitions (evidence: `internal/ig/ig.go`)
- Implementation Guides → Resource validation: supplies profiles
- Implementation Guides → FHIR client: downloads packages (evidence: `internal/ig/ig.go`)