Solution Strategy

Strategic Overview

The Connected Trade Network solves the container-transport data-sharing challenge by introducing a single, verifiable identity layer (the Association Register) and a standard way to register endpoints so that data providers and consumers can discover and authenticate each other without bespoke bilateral integration. Authorisation stays where the data already lives: each provider decides locally — on the basis of the verified identity — whether the request is allowed. The 2026 delivery sticks to this minimum so participants can start exchanging operational data quickly; broader components (orchestrator-bound registers, dossier-level proof of involvement, full PKI federation) are deliberately deferred to later phases.

CTN as BDI Implementation

CTN is a specific implementation of the Basic Data Infrastructure (BDI) framework for the container-transport domain. BDI provides the principles and patterns for sovereign data exchange between organisations; CTN applies them to container-transport coordination.

Key BDI Foundations Used by CTN:

• Association-Based Model: container-transport associations onboard participants and manage compliance.
• Digital Trust Framework: identity management and access control using OAuth 2.0 and signed JWTs.
• Event-Driven Communication: real-time notifications of operational changes (subscribe-and-receive from the source).
• Zero Trust Security: continuous verification; no implicit trust.
• Data Sovereignty: data remains with the provider, accessed through controlled interfaces.
• Federative Architecture: distributed governance, no central data repository.

For complete BDI framework specifications, see BDI Framework Principles.

Core Strategic Decisions

1. The Association Register (ASR) is the foundation

Decision: The 2026 delivery is built around a production-ready ASR. Everything else hangs off it.

Rationale:

• Identity and discovery are the prerequisites for any other CTN capability. Until parties can find each other and verify each other, no data product matters.
• A single source of truth for participant status (active, suspended, re-verified, off-boarded) avoids the bilateral re-verification overhead that today slows onboarding.

Implementation:

• Self-service onboarding with eHerkenning-based authentication of authorised representatives.
• Automated checks against KvK, KBO, VIES and GLEIF; re-verification at least annually, quarterly where risk requires.
• Issuance of VAD tokens (JWS-signed JWTs) and M2M OAuth client credentials.
• JWKS endpoint for public-key discovery.

2. Endpoint registration over bespoke integration

Decision: Data providers register their endpoints in the ASR (OpenAPI spec + metadata); data consumers register their applications and obtain credentials. The ASR validates and publishes both sides; consumers and providers find each other through the discovery API.

Rationale:

• Removes the N×M integration cost that today blocks adoption of new data products.
• Makes data products discoverable across the network at a single well-known location.
• Standardises authentication: one OAuth client-credentials flow regardless of provider.

3. Local authorisation at the data provider

Decision: CTN does not run a central policy decision point. Each data provider validates the VAD and applies its own policy locally.

Rationale:

• Keeps the data owner in control of every release decision.
• Avoids a central rule engine that everyone would have to trust to enforce their policies correctly.
• Aligns with BDI principles 5 (Data at the Source) and 6 (Local Decision-Making).

4. Use case first: Visibility Achterland Containerlogistiek

Decision: The first practical case combines Portbase data with inland-terminal operational data into one dashboard for import containers moving over barge into the hinterland.

Rationale:

• Low operational risk — no intervention in primary terminal processes.
• Touches the parties that benefit most from end-to-end visibility (terminals, barge operators, BCOs, forwarders).
• Reuses the same plumbing (ASR + endpoint registration + OAuth) that subsequent use cases will need; the next use case is mostly endpoint registration.

5. Phased delivery; defer the heavyweight components

Decision: Orchestration Register, dossier-level authorisation, dual-token validation, an OPA-based policy engine, and full PKI federation are deferred to later phases. See the Implementation Roadmap. Design notes for those components are parked under docs/_out-of-scope-2026/ (gitignored) until they are needed.

Rationale:

• Smaller blast radius for the 2026 delivery; clear win condition for the delivery team.
• Avoids forcing every participant to operate components they do not yet need.
• Lets the architecture grow when adoption justifies it, not before.

Technology Decisions

Concrete vendor and product choices are kept out of this document where possible; the Constraints chapter lists the binding choices, and the Deployment View lists the deployed services. The cloud-agnostic intent is real: Azure is the reference implementation, but the architecture avoids constructs that cannot be expressed on AWS or a self-hosted equivalent.

Reference selections

Capability	Reference choice	Notes
OAuth / OIDC server	Keycloak (self-hosted)	EU-controlled; supports client credentials, federation, SAML; integrates with eHerkenning.
Database	PostgreSQL (managed)	JSON support; ACID; portable across clouds.
API gateway	Cloud-managed API gateway (e.g. Azure API Management)	OAuth introspection, rate limiting.
Secret store	Cloud-managed key vault	HSM-backed signing keys for VAD JWS.
Identifier enrichment	KvK API, KBO API, GLEIF, VIES	See Identifier Enrichment Architecture.

Data architecture

• Transactional data: PostgreSQL for ACID guarantees (participant records, endpoint registrations, OAuth clients).
• Audit logs: structured JSON to the cloud-provider’s log platform; export available for compliance use.
• No central data lake: data products stay at the provider; CTN brokers identity and discovery, not data content.

Security architecture

Defence in depth:

1. Network: private endpoints, WAF, TLS 1.3 only.
2. Identity: OAuth 2.0 client credentials for M2M; eHerkenning for human authorised representatives.
3. Application: JWS-signed JWT validation against JWKS; short-lived tokens.
4. Data: encryption at rest (AES-256) and in transit.
5. Monitoring: centralised audit log and threat detection.

Zero Trust: every request authenticated and authorised; no implicit trust between services.

Integration Patterns

API design

• OpenAPI 3.x: contract-first; required for endpoint registration.
• REST: standard HTTP verbs; resource-oriented URLs.
• Versioning: URL path versioning (/v1, /v2).
• Pagination: cursor-based for large datasets.
• Idempotency: safe retries on POST via idempotency keys.

Async patterns

• Subscribe-and-receive at the source: consumers subscribe to provider events over the provider’s own webhook/event channel; CTN does not relay event payloads.
• Circuit breaker: resilience for external calls.
• Retry with backoff: transient failure handling.

Quality Tactics

Performance

• Database optimisation: indexes, partitioning on participant ID.
• Async processing for re-verification.
• Connection pooling.

Scalability

• Horizontal scaling for stateless services.
• Auto-scaling based on metrics.
• Read replicas for the discovery API.

Reliability

• Health checks; proactive monitoring.
• Graceful degradation: providers can keep operating on locally-cached VAD validation when the ASR is briefly unavailable (within token expiry window).
• Idempotency for safe retries.

BDI Framework Alignment

BDI Principle Implementation Matrix

BDI Principle	CTN Implementation (2026)
1. Physical-Digital Connection	Registered endpoints map physical transport events (gate-in/out, ETAs) to discoverable digital data products.
2. Event-Driven Architecture	Provider-published events over standard webhooks; consumers subscribe at the source.
3. Zero Trust	VAD-validated authorisation on every request; no implicit trust.
4. Dynamic Data	Data fetched on demand from the source; no central cached copy goes stale.
5. Data at Source	Data providers retain ownership and control; CTN never relays data content.
6. Local Decision-Making	Each provider runs its own authorisation policy on validated VAD claims.
7. Coherent Security	TLS 1.3, JWS-signed JWTs, OAuth client credentials, JWKS discovery, eHerkenning.

Interoperability

• With other BDI Associations: standard OAuth 2.0 and JWT enable cross-association identity verification; the ASR exposes a JWKS endpoint and a discovery API that any BDI-compliant peer can query.
• With other data spaces: standards-based protocols (OAuth 2.0, OpenID Connect, JWT) keep the door open to IDSA, GAIA-X, and similar initiatives. Common semantic models for logistics (e.g. DCSA standards) are reused where applicable.

Risk Mitigation

Risk	Mitigation Strategy
Slow participant onboarding	Self-service flow with eHerkenning; automated registry checks; clear administrator workflow.
Endpoint quality variance	Mandatory OpenAPI spec + automated validation; reachability check at registration.
Integration challenges	One standard auth flow; discovery API; reference connector.
Security breaches	Defence in depth; continuous monitoring; periodic external pentest.
Vendor lock-in	Cloud-agnostic design; portable components (Keycloak, PostgreSQL).

Success Metrics

Technical KPIs:

• API response time <500ms (P95)
• Token issuance <100ms
• ASR availability >99.9%

Business KPIs:

• Participant onboarding time <24 hours (happy path)
• Endpoint registration (validate + publish) <10 minutes
• Visibility use case live with the agreed set of inland terminals and barge operators

---

This solution strategy provides the architectural foundation for the 2026 delivery of the Connected Trade Network. Later-phase components are tracked in the Roadmap.