Architecture
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 19+ Docker Compose services 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 (13 apps + 3 jobs, see ADR-012). Arrows show runtime dependencies.
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 (8 DBs: controlplane, dataplane-fhir, dataplane-omop, identityhub, issuerservice, keycloak, tenant-mgr, provision-mgr) |
| HashiCorp Vault | Infrastructure | :8200 | -- | Secrets management (dev/in-memory mode, lost on restart) |
| NATS JetStream | Infrastructure | :4222 / :8222 | -- | Async event mesh for DSP protocol events |
| Keycloak | Infrastructure | :8080 / :9000 | PostgreSQL | OIDC SSO provider, realm edcv, 7 personas |
| vault-bootstrap | Infrastructure | -- | Vault, Keycloak | Init sidecar: seeds Vault secrets and Keycloak config |
| 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-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 | Graph Explorer: 16 pages, 36 API routes, 7 personas |
| 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: Gaia-X compatible credential attestation
- Federated Catalog: HealthDCAT-AP 3.0 metadata profiles
- 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 ADRs are maintained as standalone Markdown files in docs/ADRs/ .
EDC runtime metadata in PostgreSQL (8 databases), health knowledge graph in Neo4j.
Separate FHIR R4 (PUSH) and OMOP CDM (PULL) data planes for type-safe access.
Graph nodes aligned with HealthDCAT-AP 3.0 profile for EU catalog interoperability.
Client SPA with 36 API routes proxying to Neo4j and EDC-V; static export for demo.
Build EDC-V, DCore, CFM from source using Gradle multi-module layout.
Publish OCI images to GitHub Container Registry for consistent deployments.
W3C DID:web method for decentralised participant identification.
1,613 unit tests with MSW API mocking, 19 Playwright E2E specs, pre-push gate.
EHDS membership, data permits, and org VCs issued via DCP Issuer Service.
Zero WCAG violations enforced by automated axe-core audits in CI.
OWASP ZAP + BSI C5 baseline scans integrated into CI pipeline.
13 Container Apps + 3 jobs on Azure with OIDC federation and VNet isolation.
Gap analysis and alignment roadmap for EU SIMPL-Open programme compatibility.
Scheduled Monday 05:15 UTC reset of demo state for GDPR data minimisation.
Single-VM fallback deployment mode for personal Visual Studio subscription budgets.
Weekday business-hours scaling schedule to reduce Azure Container Apps cost by ~60%.
Azure Files volume mounts for Neo4j, PostgreSQL, and Vault on Container Apps.
Postgres-on-ACA workaround for INF-STG-EU_EHDS subscription policy constraints.