Deze documentatie wordt actief uitgebreid — kom regelmatig terug.

ADR-00009: Layered Source Code Structure for BDI and CTN

Approval Status

Status flow: Proposed → Accepted → Reviewed → Approved (or Rejected), or Not Required. A superseded ADR keeps its file; only its status changes to Superseded by NNNNN.

Governance body	Status	Last update
CTN Project Team	Approved	2026-06-08
CTN Technical Advisory Board	Approved	—
CTN Steering Committee	Not Required	—
BDI Conformance Team	Proposed	—
BDI Framework Team	Proposed	—

Context and Problem Statement

The BDI (Basic Data Infrastructure) network requires a clear separation between core infrastructure, reusable extensions (marketplace), and specific implementations (like CTN). This separation is necessary to ensure that core components remain generic, while allowing for a vibrant ecosystem of plugins and themes without cluttering the core repository or forcing specific requirements onto all participants.

Currently, development is focused on CTN-specific functionality, but there is a clear intent to generalize reusable parts later.

Considered Options

Option 1: Monolithic package structure

All code resides under a single package (e.g., org.bdinetwork.*). Reusable and specific code are mixed.

Option 2: Three-layered package and repository structure

Divide code into three distinct layers based on their purpose and reusability:

BDI Core: Fundamental protocol and API definitions.
Marketplace: Generic plugins and extensions.
Association Specific (CTN): Specific themes and plugins for a particular network instance.

Decision Outcome

Chosen option: Option 2: Three-layered package and repository structure.

Rationale

This approach provides a clear path for code evolution:

BDI Core (org.bdinetwork.*): Contains core components, protocol/API definitions, and Service Provider Interfaces (SPIs). This is the foundation that everyone uses.
Marketplace Layer (org.bdinetwork.marketplace.*): Contains general-purpose plugins that extend the core. These are optional but reusable across different network instances.
CTN Specific (nl.ctn.*): Contains themes and plugins specific to the CTN network. Starting with a separate namespace (nl.ctn) prevents accidental coupling with core BDI components.

The strategy is to “start out by building mostly CTN stuff” and later move code to Core (by defining SPIs) or Marketplace as its general utility becomes clear.

Key Driver: CTN as the Leading Implementation Currently, CTN is the only concrete implementation of the BDI concepts. As such, it provides the only source of testable requirements. By focusing on CTN first within its own layer, we can discover and validate the necessary abstractions for the BDI Core and Marketplace based on real-world needs rather than theoretical design.

Business alignment: Protects the BDI core as a generic standard while allowing CTN to move fast.
Technical considerations: Encourages the use of SPIs for extensibility, which is a standard Java pattern for plugin architectures.
Risk assessment: Reduces the risk of CTN-specific requirements “polluting” the BDI standard.

Consequences

Positive:
- Clear boundaries for developers.
- Explicit path for generalizing code (CTN -> Marketplace -> Core).
- Prevents vendor/tenant lock-in at the core level.
Negative:
- Requires discipline to maintain package boundaries.
- Potential overhead in managing multiple repositories or modules.
Neutral:
- Developers need to be aware of the nl.ctn package name even if a final URL is not yet established.

Implementation Plan

Phase 1: Establish the nl.ctn package for current CTN-specific development in the asr-service and related repositories.
Phase 2: Identify reusable patterns in CTN code and define SPIs in org.bdinetwork to allow for generalization.
Phase 3: Migrate generic plugins from nl.ctn to org.bdinetwork.marketplace as they mature.