# agilehealthinformatics/structured-clinical-document-poc architecture

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

- Interactive diagram: https://gitdiagram.com/agilehealthinformatics/structured-clinical-document-poc
- Repository: https://github.com/agilehealthinformatics/structured-clinical-document-poc

## Overview

SCDPOC is a synthetic-data demonstrator for preserving a clinical document while exchanging its computable FHIR IPS. Its main journey composes and validates an IPS, renders it for people, packages it in a PDF/A-3 envelope, then publishes and serves the representations through XDS/MHD; lifecycle, integrity, and cross-border exchange extend that journey. The map also includes the documented conformance checker and EHDS preview. Several runtime modules were not sampled, so those branches rely on README claims and are linked only where documented.

Main entry points: [`src/scdpoc/app.py`](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/app.py) (HTTP application), [`src/scdpoc/xds/actors.py`](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/actors.py) (XDS actors), [`src/scdpoc/crossborder/service.py`](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/service.py) (Consumer exchange), [`src/scdpoc/pdfa/packager.py`](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/packager.py) (PDF/A packager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clinical["Clinical document"]
  node_app["HTTP application<br/>[app.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_composer["IPS composer<br/>[composer.py]"]
  node_validator["IPS validator<br/>[validator.py]"]
  node_view["Clinical view model<br/>[view.py]"]
  node_html["HTML rendition<br/>[html.py]"]
  node_labels["Rendition labels<br/>[labels.py]"]
  node_pdf["PDF rendition<br/>[pdf.py]"]
end

subgraph group_preservation["Preservation assurance"]
  node_packager["PDF/A packager<br/>[packager.py]"]
  node_preflight["PDF/A preflight<br/>[preflight.py]"]
  node_vera["veraPDF validation<br/>[verapdf.py]"]
  node_extract["IPS extraction<br/>[extract.py]"]
  node_fidelity["Rendition fidelity<br/>[fidelity.py]"]
  node_integrity["Integrity checks<br/>[integrity.py]"]
  node_lifecycle["Issuance lifecycle<br/>[lifecycle.py]"]
  node_preservation_log[("Preservation events<br/>[preservation.py]")]
end

subgraph group_exchange["Discovery and exchange"]
  node_xds["XDS actors<br/>[actors.py]"]
  node_xds_model["XDS metadata model<br/>[model.py]"]
  node_ebrim["ebRIM metadata<br/>[ebrim.py]"]
  node_xds_store[("XDS persistence<br/>[store.py]")]
  node_xds_endpoints["XDS endpoints<br/>[endpoints.py]"]
  node_mhd["MHD façade<br/>[router.py]"]
end

subgraph group_crossborder["Cross-border services"]
  node_crossborder_service["Consumer exchange<br/>[service.py]"]
  node_initiating["Initiating gateway<br/>[initiating.py]"]
  node_gateway["Responding gateway<br/>[gateway.py]"]
  node_translate["IPS translation<br/>[translate.py]"]
  node_ehds["EHDS export preview<br/>[adapter.py]"]
end

subgraph group_assurance["Controls and conformance"]
  node_checker["Conformance checker<br/>[checker.py]"]
  node_conformance["Conformance kit<br/>[conformance_kit.py]"]
  node_safety["Synthetic-data safeguards<br/>[safety.py]"]
end

node_user(("Demonstrator user"))

node_user -->|"uses"| node_app
node_app -->|"loads settings"| node_config
node_app -->|"wires actors"| node_xds
node_app -->|"mounts routes"| node_xds_endpoints
node_app -->|"mounts routes"| node_mhd
node_app -->|"mounts routes"| node_gateway
node_app -->|"applies safeguards"| node_safety
node_app -.->|"orchestrates journey"| node_composer
node_composer -->|"validates IPS"| node_validator
node_composer -->|"derives view"| node_view
node_view -->|"renders HTML"| node_html
node_view -->|"renders pages"| node_pdf
node_html -->|"uses labels"| node_labels
node_pdf -->|"uses labels"| node_labels
node_pdf -->|"provides rendition"| node_packager
node_packager -->|"runs preflight"| node_preflight
node_packager -.->|"validates optionally"| node_vera
node_packager -->|"embeds IPS"| node_extract
node_fidelity -->|"checks fidelity"| node_html
node_integrity -->|"checks embedded bytes"| node_extract
node_lifecycle -->|"records transitions"| node_preservation_log
node_xds -->|"uses metadata"| node_xds_model
node_xds -->|"persists entries"| node_xds_store
node_xds_endpoints -->|"routes operations"| node_xds
node_xds_endpoints -->|"serializes metadata"| node_ebrim
node_ebrim -->|"maps metadata"| node_xds_model
node_mhd -->|"serves discovery"| node_xds
node_crossborder_service -->|"requests exchange"| node_initiating
node_initiating -->|"calls remotely"| node_gateway
node_gateway -->|"queries repository"| node_xds
node_crossborder_service -->|"verifies received IPS"| node_validator
node_crossborder_service -->|"translates projection"| node_translate
node_crossborder_service -->|"builds preview"| node_ehds
node_conformance -->|"runs checks"| node_checker
node_checker -->|"checks IPS"| node_validator
node_checker -->|"checks envelope"| node_extract
node_checker -->|"checks PDF/A"| node_preflight

click node_app "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/app.py"
click node_config "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/config.py"
click node_composer "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/ips/composer.py"
click node_validator "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/ips/validator.py"
click node_view "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/ips/view.py"
click node_html "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/render/html.py"
click node_labels "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/render/labels.py"
click node_pdf "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/render/pdf.py"
click node_packager "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/packager.py"
click node_preflight "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/preflight.py"
click node_vera "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/verapdf.py"
click node_extract "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/extract.py"
click node_fidelity "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/fidelity.py"
click node_integrity "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/integrity.py"
click node_lifecycle "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/lifecycle.py"
click node_preservation_log "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/preservation.py"
click node_xds "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/actors.py"
click node_xds_model "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/model.py"
click node_ebrim "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/ebrim.py"
click node_xds_store "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/store.py"
click node_xds_endpoints "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/endpoints.py"
click node_mhd "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/mhd/router.py"
click node_crossborder_service "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/service.py"
click node_initiating "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/initiating.py"
click node_gateway "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/gateway.py"
click node_translate "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/translate.py"
click node_ehds "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/ehds/adapter.py"
click node_checker "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/checker.py"
click node_conformance "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/conformance_kit.py"
click node_safety "https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/safety.py"

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_app,node_config,node_composer,node_validator,node_view,node_html,node_labels,node_pdf,node_user toneBlue
class node_packager,node_preflight,node_vera,node_extract,node_fidelity,node_integrity,node_lifecycle,node_preservation_log toneAmber
class node_xds,node_xds_model,node_ebrim,node_xds_store,node_xds_endpoints,node_mhd toneMint
class node_crossborder_service,node_initiating,node_gateway,node_translate,node_ehds toneRose
class node_checker,node_conformance,node_safety toneIndigo
```

## Components

### Clinical document

- [HTTP application](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/app.py): `src/scdpoc/app.py`
- [Runtime settings](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/config.py): `src/scdpoc/config.py`
- [IPS composer](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/ips/composer.py): `src/scdpoc/ips/composer.py`
- [IPS validator](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/ips/validator.py): `src/scdpoc/ips/validator.py`
- [Clinical view model](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/ips/view.py): `src/scdpoc/ips/view.py`
- [HTML rendition](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/render/html.py): `src/scdpoc/render/html.py`
- [Rendition labels](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/render/labels.py): `src/scdpoc/render/labels.py`
- [PDF rendition](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/render/pdf.py): `src/scdpoc/render/pdf.py`

### Preservation assurance

- [PDF/A packager](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/packager.py): `src/scdpoc/pdfa/packager.py`
- [PDF/A preflight](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/preflight.py): `src/scdpoc/pdfa/preflight.py`
- [veraPDF validation](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/verapdf.py): `src/scdpoc/pdfa/verapdf.py`
- [IPS extraction](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/pdfa/extract.py): `src/scdpoc/pdfa/extract.py`
- [Rendition fidelity](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/fidelity.py): `src/scdpoc/fidelity.py`
- [Integrity checks](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/integrity.py): `src/scdpoc/integrity.py`
- [Issuance lifecycle](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/lifecycle.py): `src/scdpoc/lifecycle.py`
- [Preservation events](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/preservation.py): `src/scdpoc/preservation.py`

### Discovery and exchange

- [XDS actors](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/actors.py): `src/scdpoc/xds/actors.py`
- [XDS metadata model](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/model.py): `src/scdpoc/xds/model.py`
- [ebRIM metadata](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/ebrim.py): `src/scdpoc/xds/ebrim.py`
- [XDS persistence](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/store.py): `src/scdpoc/xds/store.py`
- [XDS endpoints](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/xds/endpoints.py): `src/scdpoc/xds/endpoints.py`
- [MHD façade](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/mhd/router.py): `src/scdpoc/mhd/router.py`

### Cross-border services

- [Consumer exchange](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/service.py): `src/scdpoc/crossborder/service.py`
- [Initiating gateway](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/initiating.py): `src/scdpoc/crossborder/initiating.py`
- [Responding gateway](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/gateway.py): `src/scdpoc/crossborder/gateway.py`
- [IPS translation](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/crossborder/translate.py): `src/scdpoc/crossborder/translate.py`
- [EHDS export preview](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/ehds/adapter.py): `src/scdpoc/ehds/adapter.py`

### Controls and conformance

- [Conformance checker](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/checker.py): `src/scdpoc/checker.py`
- [Conformance kit](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/conformance_kit.py): `src/scdpoc/conformance_kit.py`
- [Synthetic-data safeguards](https://github.com/agilehealthinformatics/structured-clinical-document-poc/blob/main/src/scdpoc/safety.py): `src/scdpoc/safety.py`

### Other components

- **Demonstrator user**

## Connections

- Demonstrator user → HTTP application: uses (evidence: `README.md`)
- HTTP application → Runtime settings: loads settings (evidence: `src/scdpoc/app.py`)
- HTTP application → XDS actors: wires actors (evidence: `src/scdpoc/app.py`)
- HTTP application → XDS endpoints: mounts routes (evidence: `src/scdpoc/app.py`)
- HTTP application → MHD façade: mounts routes (evidence: `src/scdpoc/app.py`)
- HTTP application → Responding gateway: mounts routes (evidence: `src/scdpoc/app.py`)
- HTTP application → Synthetic-data safeguards: applies safeguards (evidence: `src/scdpoc/app.py`)
- HTTP application → IPS composer: orchestrates journey
- IPS composer → IPS validator: validates IPS (evidence: `README.md`)
- IPS composer → Clinical view model: derives view (evidence: `src/scdpoc/ips/composer.py`)
- Clinical view model → HTML rendition: renders HTML (evidence: `src/scdpoc/render/html.py`)
- Clinical view model → PDF rendition: renders pages (evidence: `src/scdpoc/render/pdf.py`)
- HTML rendition → Rendition labels: uses labels (evidence: `src/scdpoc/render/html.py`)
- PDF rendition → Rendition labels: uses labels (evidence: `src/scdpoc/render/pdf.py`)
- PDF rendition → PDF/A packager: provides rendition (evidence: `README.md`)
- PDF/A packager → PDF/A preflight: runs preflight (evidence: `src/scdpoc/pdfa/preflight.py`)
- PDF/A packager → veraPDF validation: validates optionally
- PDF/A packager → IPS extraction: embeds IPS (evidence: `README.md`)
- Rendition fidelity → HTML rendition: checks fidelity (evidence: `src/scdpoc/fidelity.py`)
- Integrity checks → IPS extraction: checks embedded bytes (evidence: `src/scdpoc/integrity.py`)
- Issuance lifecycle → Preservation events: records transitions (evidence: `README.md`)
- XDS actors → XDS metadata model: uses metadata (evidence: `src/scdpoc/xds/actors.py`)
- XDS actors → XDS persistence: persists entries (evidence: `src/scdpoc/xds/actors.py`)
- XDS endpoints → XDS actors: routes operations (evidence: `src/scdpoc/xds/endpoints.py`)
- XDS endpoints → ebRIM metadata: serializes metadata (evidence: `src/scdpoc/xds/endpoints.py`)
- ebRIM metadata → XDS metadata model: maps metadata (evidence: `src/scdpoc/xds/ebrim.py`)
- MHD façade → XDS actors: serves discovery (evidence: `src/scdpoc/mhd/router.py`)
- Consumer exchange → Initiating gateway: requests exchange (evidence: `src/scdpoc/crossborder/service.py`)
- Initiating gateway → Responding gateway: calls remotely (evidence: `src/scdpoc/crossborder/initiating.py`)
- Responding gateway → XDS actors: queries repository (evidence: `src/scdpoc/crossborder/gateway.py`)
- Consumer exchange → IPS validator: verifies received IPS (evidence: `src/scdpoc/crossborder/service.py`)
- Consumer exchange → IPS translation: translates projection (evidence: `src/scdpoc/crossborder/service.py`)
- Consumer exchange → EHDS export preview: builds preview (evidence: `src/scdpoc/crossborder/service.py`)
- Conformance kit → Conformance checker: runs checks (evidence: `src/scdpoc/conformance_kit.py`)
- Conformance checker → IPS validator: checks IPS (evidence: `src/scdpoc/checker.py`)
- Conformance checker → IPS extraction: checks envelope (evidence: `src/scdpoc/checker.py`)
- Conformance checker → PDF/A preflight: checks PDF/A (evidence: `src/scdpoc/checker.py`)