Architecture at a glance

Three services, a handful of shared packages, one rigorously-enforced dependency direction. The canonical long-form description lives in docs/ARCHITECTURE; this page is the sketch.

The map

The interactive explorer is the most productive way to look around:

Open the interactive explorer → Read the written doc

ASR — Associatie Register

Governs who can participate. Two core aggregates:

Member — onboarding, KvK/KBO/GLEIF/VIES verification, signing-representative eHerkenning check, 4-eyes approval, status transitions.
Connector — registration, kid/JWK binding, X.509 cert thumbprint pinning, status transitions.

Issues the BVAD (Bewijs van Associatie-Deelname) to connectors against RFC 7523 client assertions, signs the trustlist for the association, and performs RFC 8693 token exchange with federated peer associations.

ORS — Orkestratie Register

Governs what happens in a logistics chain. Aggregate:

ChainContext — identifiers (BOL, AWB, …), parties and their roles, delegations, role-bound natural persons (stored as SHA-256 pseudonyms, never as PII).

Issues the BVOD (Bewijs van Orkestratie-Deelname) scoped to (context, subject connector) and pushes events to subscribed connectors via Valkey Streams.

CON — BDI Connector

Runs alongside each member's application. Full token verification pipeline on inbound, backoff-based delivery on outbound, a reverse proxy for legacy upstreams, and pluggable PDP adapters (Cedar / OPA / Keycloak-Authz).

Shared packages

Package	Responsibility
`@bdi/kernel`	Result, branded types, EUID/LEI/VAT/KvK parsers, JWK & thumbprint helpers.
`@bdi/contracts`	Wire schemas for BVAD, BVOD, trustlist, member descriptor.
`@bdi/crypto`	BDI JWS profile, RFC 7523 verifier, key generation, HSM/PKCS#11/step-ca.
`@bdi/crypto-ca`	RFC 8555 ACME server + client, CSR parser, X.509 issuer, OCSP, CRL.
`@bdi/identity`	Keycloak OIDC verifier, eHerkenning SAML broker, `AuthnPort`.
`@bdi/events`	Typed events, Valkey Streams consumer, rate limiter, scheduler.
`@bdi/policy`	PDP port + embedded Cedar-like engine + external adapters.
`@bdi/config`	Env parsing, `*_FILE` secrets, SIGHUP hot-reload, migrations, RLS, YAML.
`@bdi/observability`	Structured logs, metrics registry, trace context, OTLP exporter.
`@bdi/openapi`	OpenAPI 3.1 document builder used by `scripts/generate-openapi.ts`.

Data plane vs. trust plane

The interactive explorer draws these as three horizontal bands:

Trust plane — ASR and its satellites (IdP, registries, CA, peer ASR).
Orchestration plane — ORS and its subscriptions.
Data plane — Connector-to-Connector traffic plus the outbound upstreams.

Tokens issued in the trust plane (BVAD) and orchestration plane (BVOD) are what the data plane verifies. This keeps the runtime data plane ignorant of identity providers and registries — it only needs the ASR's trustlist and the ORS's public keys.