Architecture
Last updated
Interactive diagrams of the Health Dataspace v2 architecture — 5-layer graph model, data flows, deployment topology, service dependencies, and identity trust framework.
1. Five-Layer Knowledge Graph
The Neo4j knowledge graph organises health data across five architectural layers: DSP Marketplace (connector discovery), HealthDCAT-AP (dataset metadata), FHIR R4 (clinical data), OMOP CDM (research analytics), and Ontology (terminology alignment).
2. Data Flow Pipeline
Synthetic patient data flows from Synthea generation through FHIR R4 resource loading into Neo4j, then transforms to OMOP CDM for research analytics. Each stage preserves full provenance through graph relationships.
3. Deployment Topology
The full JAD stack runs 25 Docker Compose services (profiles included) across six layers: infrastructure (Traefik, PostgreSQL, Vault, NATS, Keycloak), EDC-V / DCore (Control Plane, dual Data Planes), Identity (Identity Hub, Issuer Service), CFM (Tenant/Provision Managers, 4 background agents), Application (Neo4j, Proxy, UI), and a static GitHub Pages export. The same topology is deployed to Azure Container Apps at ehds.mabu.red (21 Container Apps and 9 Container Apps jobs on 2026-10-04, see ADR-012). Arrows show runtime dependencies.
Operating hours on Azure
The Azure deployment runs Monday to Friday, 05:00 to 18:00 UTC, and is stopped outside those hours (ADR-053). Stopping is a real stop through the Container Apps API, not scale-to-zero, because nearly every service is called by another one and would never reach zero replicas. The UI is the exception: it sleeps at zero replicas, wakes for a visitor and serves an offline notice that links the static export.
| Step | Evening stop (18:00 UTC) | Morning start (05:00 UTC, Mon to Fri) |
|---|---|---|
| 1 | UI to offline mode, min 0 | PostgreSQL Flexible Server, wait until Ready |
| 2 | 20 Container Apps stopped, consumers first | Vault, Keycloak, Neo4j, NATS, proxy, enricher |
| 3 | PostgreSQL Flexible Server stopped | EDC control plane, data planes, identity, CFM |
| 4 | UI back online, then the Keycloak login check |
Berlin public holidays skip the start. The catalog crawler runs in office hours only. A night or weekend session holds the stack with the repository variable LIVE_DEMO_HOLD_UNTIL; see the off-hours runbook.
4. Service Dependencies
Complete inventory of all services in the docker-compose.yml and docker-compose.jad.yml stacks, their exposed ports, upstream dependencies, and purpose.
| Service | Layer | Port(s) | Depends On | Purpose |
|---|---|---|---|---|
| Traefik | Infrastructure | :80 / :8090 | -- | API gateway, reverse proxy, *.localhost routing |
| PostgreSQL 17 | Infrastructure | :5432 | -- | Shared database (9 DBs: cfm, controlplane, dataplane, dataplane_omop, identityhub, issuerservice, keycloak, redlinedb, taskdb) |
| HashiCorp Vault | Infrastructure | :8200 | -- | Secrets store with file storage, so a restart keeps every key (since 2026-09-26; on Azure it stores in the Flexible Server, ADR-046) |
| NATS JetStream | Infrastructure | :4222 / :8222 | -- | Async event mesh for DSP protocol events |
| Keycloak | Infrastructure | :8080 / :9000 | PostgreSQL | OIDC SSO provider, realm edcv, 8 demo users across 5 roles |
| vault-bootstrap | Infrastructure | -- | Vault, Keycloak | Init sidecar: seeds Vault secrets and Keycloak config |
| vault-unseal | Infrastructure | -- | Vault | Sidecar: initialises Vault once, then unseals it after every restart |
| siglet | Infrastructure | -- | Vault | Token signing and certificate exchange for the EDC 0.18 data planes (#97) |
| Control Plane | EDC-V / DCore | :11003 | PostgreSQL, Vault, NATS, Keycloak | EDC-V runtime: DSP negotiation, management API, policy engine |
| Data Plane FHIR | EDC-V / DCore | :11002 | PostgreSQL, Vault, Control Plane | DCore data plane for FHIR R4 resource transfer |
| Data Plane OMOP | EDC-V / DCore | :11012 | PostgreSQL, Vault, Control Plane | DCore data plane for OMOP CDM data transfer |
| Identity Hub | Identity | :11005 | PostgreSQL, Vault, Keycloak | DCP: DID resolution, Verifiable Credential storage |
| Issuer Service | Identity | :10013 | PostgreSQL, Vault, Keycloak | VC issuance: EHDS membership, data permits, org credentials |
| Tenant Manager | CFM | :11006 | PostgreSQL, Keycloak | CFM: multi-tenant participant management |
| Provision Manager | CFM | :11007 | PostgreSQL, Keycloak, Control Plane | CFM: automated resource provisioning |
| cfm-cp-shim | CFM | -- | Control Plane | nginx shim: the CFM agents call Management API v5alpha, EDC 0.18 serves v5beta (#181) |
| cfm-keycloak-agent | CFM | -- | Keycloak | Background: syncs Keycloak realm configuration |
| cfm-edcv-agent | CFM | -- | Control Plane | Background: manages EDC-V connector lifecycle |
| cfm-registration-agent | CFM | -- | Identity Hub | Background: handles participant DID registration |
| cfm-onboarding-agent | CFM | -- | Tenant Manager | Background: automates tenant onboarding workflows |
| Neo4j 5 | Application | :7474 / :7687 | -- | Knowledge graph: 5-layer model, APOC + n10s plugins |
| Neo4j SPE2 | Application | :7475 / :7688 | -- | Secondary graph instance (federated profile) |
| Neo4j Proxy | Application | :9090 | Neo4j, Control Plane | Express bridge: FHIR/OMOP REST endpoints over Neo4j |
| Next.js UI | Application | :3000 / :3003 | Neo4j Proxy | Persona overviews, catalog, governance and exchange: 50 pages, 75 API routes |
| jad-seed | Seed | -- | All services | One-shot: phases 1-7 data seeding (Synthea, FHIR, OMOP, DSP) |
| GitHub Pages | Static | -- | Next.js UI (static export) | Public demo site with mock data fixtures |
5. DSP Contract Negotiation
The Dataspace Protocol (DSP) governs how data holders and data users negotiate access to health datasets. The EHDS regulation adds HDAB approval as a pre-requisite for data permit issuance before contract negotiation can proceed.
6. Identity & Trust Framework
The Decentralized Claims Protocol (DCP) manages identity, credentials, and trust. Identity Hub stores DIDs and Verifiable Credentials, the Issuer Service mints EHDS-specific credentials, and Keycloak provides SSO/OIDC authentication.
7. SIMPL-Open & Compliance
This reference implementation aligns with the EU SIMPL-Open programme for federated data spaces. The architecture satisfies EHDS regulation, DSP 2025-1, DCP v1.0, and supply chain transparency requirements.
SIMPL-Open Alignment
- DSP 2025-1: Sovereign data exchange via Control Plane
- DCP v1.0: DID:web identity + Verifiable Credentials
- Trust Framework: W3C Verifiable Credentials issued over DCP against the issuer's definitions
- Federated Catalog: HealthDCAT-AP 2.1 metadata profiles (ADR-003)
- SBOM: CycloneDX 1.5 supply chain transparency
Regulatory Compliance
- EHDS Art. 3-12: Patient rights (access, rectification, portability)
- EHDS Art. 50-51: Secondary use — HDAB approval, data permits
- GDPR Art. 15-22: Data subject rights enforcement
- EU CRA Art. 13: SBOM mandate, vulnerability disclosure
- BSI C5: Cloud security baseline (DEV, OPS controls)
8. Architecture Decision Records
All 54 ADRs are maintained as standalone Markdown files in docs/ADRs/ .
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Superseded
Superseded
Accepted
Accepted
Accepted
Accepted
Accepted
Superseded
Superseded
Accepted
Accepted
Accepted
Superseded
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Accepted
Superseded
Accepted
Proposed
Proposed
Accepted
Proposed
Accepted