Developer Guide

Onboarding

New to the project? Follow this quick-start path to get productive within your first day.

Working on the Project

How a change reaches the live hub, how it is tested through the APIs, and what each part of the stack is. Each page is published from the docs folder of the repository.

JAD Stack Architecture

The full JAD (Java Application Deployment) stack runs 27 Docker Compose services orchestrated via docker-compose.yml + docker-compose.jad.yml. Services are grouped into five layers:

Plus 4 background CFM agents (keycloak, edcv, registration, onboarding) and 1 one-shot seed container. Vault-bootstrap runs as a sidecar.

Prerequisites

Quick Start: Minimal Stack

Run Neo4j + Next.js UI with synthetic data. No JAD services needed.

docker compose up -d

# Initialize schema (idempotent — safe to re-run)
cat neo4j/init-schema.cypher | \
  docker exec -i health-dataspace-neo4j \
  cypher-shell -u neo4j -p healthdataspace

# Load synthetic data (127 patients, 5300+ nodes)
cat neo4j/insert-synthetic-schema-data.cypher | \
  docker exec -i health-dataspace-neo4j \
  cypher-shell -u neo4j -p healthdataspace

cd ui
npm install
npm run dev          # → http://localhost:3000

npm test             # Run the Vitest unit suite
npm run lint         # ESLint (max 55 warnings)

Quick Start: Full JAD Stack

The bootstrap script starts all 27 services with health checks, initializes Vault secrets, imports the Keycloak realm, and runs the 7-phase seed pipeline.

# Full stack — takes ~3-5 min on first run
./scripts/bootstrap-jad.sh

# Check status & endpoints
./scripts/bootstrap-jad.sh --status

# Run all 7 seed phases (sequential, strict order)
./jad/seed-all.sh

# Resume from a specific phase
./jad/seed-all.sh --from 3

# Run only one phase
./jad/seed-all.sh --only 5

# Live UI (production build)
open http://localhost:3003

# Keycloak Admin Console
open http://keycloak.localhost  # admin / admin

# Neo4j Browser
open http://localhost:7474      # neo4j / healthdataspace

# Traefik Dashboard
open http://traefik.localhost

./scripts/bootstrap-jad.sh --ui-only   # Rebuild UI only (fast)
./scripts/bootstrap-jad.sh --seed      # Re-run seed pipeline
./scripts/bootstrap-jad.sh --pull      # Pull latest images
./scripts/bootstrap-jad.sh --down      # Stop all services
./scripts/bootstrap-jad.sh --reset     # Stop + remove volumes

Data Seeding Pipeline

The 7-phase seed pipeline populates the dataspace with tenants, credentials, policies, assets, and contracts. Phases must run in strict order; each depends on the previous.

Project Structure

├── .github/workflows/         # CI/CD (pr-gate, test, compliance, security-scan, deploy-azure, pages, ...)
├── connector/                 # EDC-V connector (Gradle multi-module)
│   ├── controlplane/          # DSP + Management API
│   ├── dataplane/             # FHIR + OMOP data planes
│   └── identityhub/           # DCP Identity Hub
├── docs/                      # Architecture docs, journeys, ADRs, reports
├── jad/                       # JAD infrastructure configs
│   ├── keycloak-realm.json    # Keycloak realm (edcv, 7 users, 6 roles)
│   ├── edcv-assets/           # Contract definitions & ODRL policies
│   ├── seed-*.sh              # 7-phase seed scripts
│   └── openapi/               # OpenAPI specifications
├── k8s/                       # Kubernetes / OrbStack manifests
├── neo4j/                     # Cypher scripts & data
│   ├── init-schema.cypher     # Constraints, indexes, vector indexes
│   ├── insert-synthetic-schema-data.cypher
│   └── fhir-to-omop-transform.cypher
├── scripts/                   # Automation (bootstrap, synthea, compliance)
├── services/neo4j-proxy/      # Express bridge (Neo4j ↔ UI)
├── ui/                        # Next.js 15 application
│   ├── src/app/               # 64 pages, 84 API routes
│   ├── src/components/        # Shared React components
│   ├── src/lib/               # auth.ts, api.ts, graph-constants.ts
│   ├── __tests__/unit/        # Vitest unit tests
│   ├── __tests__/e2e/         # Playwright specs (journeys/)
│   └── public/mock/           # 38 JSON fixtures for static export
├── docker-compose.yml         # Minimal stack (Neo4j + UI)
└── docker-compose.jad.yml     # Full JAD stack (24 services)

Neo4j Graph Schema

The 5-layer knowledge graph spans 27 node labels with 70+ indexes and 3 vector indexes for GraphRAG. Schema defined in neo4j/init-schema.cypher (idempotent, safe to re-run).

PostgreSQL Schema

PostgreSQL serves as the runtime store for all JAD services: EDC-V state machines, Keycloak identity, and CFM tenant metadata. Neo4j holds the health knowledge graph. This split follows ADR-1.

Integration Flows

Two canonical flows cover 90% of real-world EHDS integrations. Pick the one that matches your role, then use the Scalar API Reference to try each endpoint from the browser.

API Reference

84 Next.js API routes (111 operations) proxy to Neo4j and the EDC-V services; the table is generated from ui/src/app/api/. Every route needs a session (ADR-044) except the sign-in flows, the Keycloak address for the sign-in banner, the health probe, and the Klarbefund app's account creation, which answers only a verified Apple App Attest attestation (ADR-054). Routes are disabled in the static export; mock data is served from ui/public/mock/*.json.

Testing

npm test               # Run once
npm run test:watch     # Watch mode
npm run test:coverage  # With v8 coverage

npm run test:e2e       # Headless (chromium)
npm run test:e2e:ui    # Interactive UI

# Against JAD stack
PLAYWRIGHT_BASE_URL=http://localhost:3003 \
  npm run test:e2e

./scripts/run-dsp-tck.sh

./scripts/run-dcp-tests.sh

./scripts/run-ehds-tests.sh

Quality Gates

Four-stage quality pipeline aligned with BSI C5, OWASP Top 10, EHDS regulation, and WCAG 2.2 AA.

CI/CD Pipeline

Live Stack Off Hours

Outside office hours the Azure stack is stopped, database included, and ehds.mabu.red answers every page with an offline notice and every data route with 503. Local development is not affected: docker compose and npm run dev know nothing of the schedule. To see the notice locally, start the UI with LIVE_DEMO_OFFLINE=true.

# 1. Hold it: no scheduled stop before this instant (UTC)
gh variable set LIVE_DEMO_HOLD_UNTIL --body "2026-10-10T22:00Z"

# 2. Start it (any day, about ten minutes, green only if a login works)
gh workflow run aca-schedule.yml -f action=start

# 3. Optional: one catalog crawl, it runs in office hours only
az containerapp job start --name mvhd-catalog-crawler --resource-group rg-mvhd-dev

# 4. Done: release the hold and stop it again
gh variable delete LIVE_DEMO_HOLD_UNTIL
gh workflow run aca-schedule.yml -f action=stop

Latest Reports

Security and Data Protection

Tested by the project itself with tools anyone can run on the repository; every finding is fixed or named as open. The test of 2026-10-15 found ten findings, F1 to F10: after the fixes nine are closed and one is reviewed and accepted (F3, the published development default key of the local compose stack). None of this is an independent penetration test or a certification. The reports are published under /docs/security.

Run it again: scripts/security/generate-sbom.sh --check, scripts/security/scan-repo.sh, scripts/security/check-hub-blackbox.sh and swift test --filter SecurityPostureTests in clients/ios. Decisions: ADR-011 (testing strategy) and ADR-060 (the app lock; why pinning and jailbreak detection were declined).

Writing the Documentation

The documentation is part of the repository and the hub publishes it from there. Every page under /docs gets an index of its headings at the right (a disclosure at the top on a phone), and every diagram or screenshot opens full screen with zoom on click.

Choose the kind of page by its reader. A report, guide or runbook read from start to end is Markdown under docs/, which the hub publishes; a page that shows live facts, diagrams and links into the hub is a hand-written React page. Both get numbered headings and the index at the right without further work.

Data Flow

Release Notes

The version is the one in ui/package.json; when a merge to main changes it, release.yml tags it and publishes the release. How releases and the TestFlight builds of the iPhone app work

Planning & Issues

Conventions