# ferrohealth/ferroehr architecture

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

- Interactive diagram: https://gitdiagram.com/ferrohealth/ferroehr
- Repository: https://github.com/ferrohealth/ferroehr

## Overview

FerroEHR is an openEHR clinical data repository: applications submit versioned clinical records and queries through its REST interface, which mediates access and delegates operations to the database-backed service. The repository also includes the FerroEHR Viewer and integrations for terminology, change feeds, and multimedia. The graph reflects documented product capabilities and sampled routing/state code; most domain handlers and service internals were not sampled, so their internal call paths are not asserted.

Main entry points: [`app/ferroehr-rest/src/api/mod.rs`](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/mod.rs) (API hub), [`app/ferroehr-server/src/lib.rs`](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-server/src/lib.rs) (CDR service), [`app/ferroehr-rest/src/state.rs`](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/state.rs) (Shared app state), [`app/ferroehr-rest/src/api/ehr/openapi_routes.rs`](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/ehr/openapi_routes.rs) (EHR operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Clients"]
  node_apps(("Clinical applications"))
end

subgraph group_rest["REST and access"]
  node_router["REST router<br/>[router.rs]"]
  node_api["API hub<br/>[mod.rs]"]
  node_state["Shared app state<br/>[state.rs]"]
  node_access["Access controls<br/>[admission.rs]"]
  node_ehr_routes["EHR operations<br/>[openapi_routes.rs]"]
  node_demographics["Demographics API<br/>[party.rs]"]
  node_admin["Administrative API<br/>[operations.rs]"]
  node_query_api["Query API<br/>[openapi_routes.rs]"]
  node_formats["Format dispatch<br/>[dispatch.rs]"]
  node_committal["Version committal<br/>[committal.rs]"]
  node_version_ids["Version identifiers<br/>[version_id.rs]"]
  node_audit["Request audit<br/>[middleware.rs]"]
end

subgraph group_clinical["Clinical services"]
  node_service["CDR service<br/>[lib.rs]"]
  node_aql["AQL engine<br/>[exec.rs]"]
  node_definitions["Templates and validation<br/>[adl2_engine.rs]"]
  node_party_store["Identifier protection<br/>[engine.rs]"]
  node_db[("PostgreSQL store<br/>[pool.rs]")]
end

subgraph group_integration["Integrations"]
  node_terminology["Terminology service<br/>[terminology.rs]"]
  node_outbox["Change-event feed<br/>[mod.rs]"]
  node_multimedia["Multimedia storage<br/>[blob.rs]"]
end

subgraph group_viewer["Viewer"]
  node_viewer["Web viewer<br/>[routes.rs]"]
  node_viewer_request["Viewer requests<br/>[request.rs]"]
  node_viewer_scope["Viewer authorization scope<br/>[scope.rs]"]
end

node_apps -->|"send requests"| node_router
node_router -->|"routes requests"| node_api
node_api -->|"checks access"| node_access
node_api -.->|"dispatches EHR"| node_ehr_routes
node_api -.->|"dispatches demographics"| node_demographics
node_api -->|"dispatches admin"| node_admin
node_api -->|"dispatches queries"| node_query_api
node_api -->|"provides state"| node_state
node_ehr_routes -->|"uses state"| node_state
node_demographics -->|"uses state"| node_state
node_admin -->|"uses state"| node_state
node_query_api -->|"uses state"| node_state
node_state -->|"holds service"| node_service
node_ehr_routes -.->|"commits versions"| node_committal
node_ehr_routes -.->|"negotiates formats"| node_formats
node_demographics -->|"dispatches formats"| node_formats
node_demographics -->|"uses version IDs"| node_version_ids
node_api -->|"logs requests"| node_audit
node_service -.->|"persists records"| node_db
node_query_api -.->|"executes AQL"| node_aql
node_service -.->|"validates templates"| node_definitions
node_service -.->|"protects identifiers"| node_party_store
node_service -.->|"publishes changes"| node_outbox
node_apps -.->|"uses terminology"| node_terminology
node_service -.->|"stores media"| node_multimedia
node_apps -->|"uses viewer"| node_viewer
node_viewer -->|"handles requests"| node_viewer_request
node_viewer_request -->|"checks scope"| node_viewer_scope
node_viewer -->|"calls public API"| node_router

click node_router "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/router.rs"
click node_api "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/mod.rs"
click node_state "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/state.rs"
click node_access "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/extensions/access/admission.rs"
click node_ehr_routes "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/ehr/openapi_routes.rs"
click node_demographics "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/demographic/party.rs"
click node_admin "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/admin/operations.rs"
click node_query_api "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/query/openapi_routes.rs"
click node_formats "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/formats/dispatch.rs"
click node_committal "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/overview/committal.rs"
click node_version_ids "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/overview/version_id.rs"
click node_audit "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/system_log/middleware.rs"
click node_service "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-server/src/lib.rs"
click node_aql "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/aql/exec.rs"
click node_definitions "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/service/definition/adl2_engine.rs"
click node_party_store "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/identifier_protection/engine.rs"
click node_db "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/db/pool.rs"
click node_terminology "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/extensions/terminology.rs"
click node_outbox "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/extensions/outbox/mod.rs"
click node_multimedia "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-ext/src/multimedia/blob.rs"
click node_viewer "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-viewer/src/routes.rs"
click node_viewer_request "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-viewer/src/request.rs"
click node_viewer_scope "https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-viewer/src/scope.rs"

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_apps toneBlue
class node_router,node_api,node_state,node_access,node_ehr_routes,node_demographics,node_admin,node_query_api,node_formats,node_committal,node_version_ids,node_audit toneAmber
class node_service,node_aql,node_definitions,node_party_store,node_db toneMint
class node_terminology,node_outbox,node_multimedia toneRose
class node_viewer,node_viewer_request,node_viewer_scope toneIndigo
```

## Components

### Clients

- **Clinical applications**

### REST and access

- [REST router](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/router.rs): `app/ferroehr-rest/src/router.rs`
- [API hub](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/mod.rs): `app/ferroehr-rest/src/api/mod.rs`
- [Shared app state](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/state.rs): `app/ferroehr-rest/src/state.rs`
- [Access controls](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/extensions/access/admission.rs): `app/ferroehr-rest/src/extensions/access/admission.rs`
- [EHR operations](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/ehr/openapi_routes.rs): `app/ferroehr-rest/src/api/ehr/openapi_routes.rs`
- [Demographics API](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/demographic/party.rs): `app/ferroehr-rest/src/api/demographic/party.rs`
- [Administrative API](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/admin/operations.rs): `app/ferroehr-rest/src/api/admin/operations.rs`
- [Query API](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/api/query/openapi_routes.rs): `app/ferroehr-rest/src/api/query/openapi_routes.rs`
- [Format dispatch](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/formats/dispatch.rs): `app/ferroehr-rest/src/formats/dispatch.rs`
- [Version committal](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/overview/committal.rs): `app/ferroehr-rest/src/overview/committal.rs`
- [Version identifiers](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/overview/version_id.rs): `app/ferroehr-rest/src/overview/version_id.rs`
- [Request audit](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/system_log/middleware.rs): `app/ferroehr-rest/src/system_log/middleware.rs`

### Clinical services

- [CDR service](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-server/src/lib.rs): `app/ferroehr-server/src/lib.rs`
- [AQL engine](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/aql/exec.rs): `app/ferroehr/src/aql/exec.rs`
- [Templates and validation](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/service/definition/adl2_engine.rs): `app/ferroehr/src/service/definition/adl2_engine.rs`
- [Identifier protection](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/identifier_protection/engine.rs): `app/ferroehr/src/identifier_protection/engine.rs`
- [PostgreSQL store](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/db/pool.rs): `app/ferroehr/src/db/pool.rs`

### Integrations

- [Terminology service](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-rest/src/extensions/terminology.rs): `app/ferroehr-rest/src/extensions/terminology.rs`
- [Change-event feed](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr/src/extensions/outbox/mod.rs): `app/ferroehr/src/extensions/outbox/mod.rs`
- [Multimedia storage](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-ext/src/multimedia/blob.rs): `app/ferroehr-ext/src/multimedia/blob.rs`

### Viewer

- [Web viewer](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-viewer/src/routes.rs): `app/ferroehr-viewer/src/routes.rs`
- [Viewer requests](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-viewer/src/request.rs): `app/ferroehr-viewer/src/request.rs`
- [Viewer authorization scope](https://github.com/ferrohealth/ferroehr/blob/main/app/ferroehr-viewer/src/scope.rs): `app/ferroehr-viewer/src/scope.rs`

## Connections

- Clinical applications → REST router: send requests
- REST router → API hub: routes requests (evidence: `app/ferroehr-rest/src/api/mod.rs`)
- API hub → Access controls: checks access (evidence: `app/ferroehr-rest/src/api/mod.rs`)
- API hub → EHR operations: dispatches EHR (evidence: `app/ferroehr-rest/src/api/ehr/openapi_routes.rs`)
- API hub → Demographics API: dispatches demographics (evidence: `app/ferroehr-rest/src/api/demographic/party.rs`)
- API hub → Administrative API: dispatches admin (evidence: `app/ferroehr-rest/src/api/admin/openapi_routes.rs`)
- API hub → Query API: dispatches queries (evidence: `app/ferroehr-rest/src/api/query/openapi_routes.rs`)
- API hub → Shared app state: provides state (evidence: `app/ferroehr-rest/src/state.rs`)
- EHR operations → Shared app state: uses state (evidence: `app/ferroehr-rest/src/api/ehr/openapi_routes.rs`)
- Demographics API → Shared app state: uses state (evidence: `app/ferroehr-rest/src/api/demographic/party.rs`)
- Administrative API → Shared app state: uses state (evidence: `app/ferroehr-rest/src/api/admin/operations.rs`)
- Query API → Shared app state: uses state (evidence: `app/ferroehr-rest/src/api/query/openapi_routes.rs`)
- Shared app state → CDR service: holds service (evidence: `app/ferroehr-rest/src/state.rs`)
- EHR operations → Version committal: commits versions
- EHR operations → Format dispatch: negotiates formats
- Demographics API → Format dispatch: dispatches formats (evidence: `app/ferroehr-rest/src/api/demographic/party.rs`)
- Demographics API → Version identifiers: uses version IDs (evidence: `app/ferroehr-rest/src/api/demographic/party.rs`)
- API hub → Request audit: logs requests (evidence: `app/ferroehr-rest/src/api/mod.rs`)
- CDR service → PostgreSQL store: persists records
- Query API → AQL engine: executes AQL
- CDR service → Templates and validation: validates templates
- CDR service → Identifier protection: protects identifiers
- CDR service → Change-event feed: publishes changes
- Clinical applications → Terminology service: uses terminology
- CDR service → Multimedia storage: stores media
- Clinical applications → Web viewer: uses viewer
- Web viewer → Viewer requests: handles requests (evidence: `app/ferroehr-viewer/src/routes.rs`)
- Viewer requests → Viewer authorization scope: checks scope (evidence: `app/ferroehr-viewer/src/request.rs`)
- Web viewer → REST router: calls public API
