ADR-00004: Single Consolidated Glossary for BDI and CTN
Approval Status
Section titled “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-11 |
| CTN Technical Advisory Board | Not Required | 2026-07-08 |
| CTN Steering Committee | Not Required | 2026-07-08 |
| BDI Conformance Team | Proposed | 2026-07-08 |
| BDI Framework Team | Pending | 2026-07-08 |
Context and Problem Statement
Section titled “Context and Problem Statement”In the development of the Association Registry (ASR) and the broader Connected Trade Network (CTN), we deal with concepts from multiple domains: the Basic Data Infrastructure (BDI) reference architecture, CTN-specific business logic, and general logistics.
Inconsistency in terminology leads to confusion in designs, documentation, and source code (e.g., mixing “Organization” vs “Member”, or “User” vs “Participant”). Some terms are a given (“Users” and “Organizations” are terms in use in Keycloak and may not mean the same. We need a stable, single source of truth for terminology that is accessible to both development teams and business stakeholders to ensure clear communication and maintainable code.
Considered Options
Section titled “Considered Options”Option 1: Fragmented Glossaries
Section titled “Option 1: Fragmented Glossaries”- Description: Maintain separate glossaries for BDI (external), CTN (local), and ASR (technical docs).
- Pros: Local control over specific sections.
- Cons: High risk of drift; conflicting definitions for the same terms; harder for stakeholders to find the authoritative definition.
Option 2: Single Consolidated Glossary (Chosen)
Section titled “Option 2: Single Consolidated Glossary (Chosen)”- Description: Maintain one single, comprehensive glossary at
docs/arc42/12-glossary/ctn-glossary.mdthat consolidates BDI and CTN terms. This glossary also includes a dedicated chapter for the ASR bounded context to define its specific entities. - Pros:
- Single source of truth for all stakeholders (Business and Tech).
- Ensures alignment between BDI reference architecture and CTN implementation.
- Explicitly defines the ASR bounded context entities, aiding developers.
- AI-Ready: A single file is easier to provide as context to LLMs for term-consistent code generation.
- Co-location: Stored in the repository, it evolves with the code.
- Cons: Requires discipline to maintain and keep updated during development.
Decision Outcome
Section titled “Decision Outcome”Chosen option: Option 2. We will maintain a single consolidated glossary. All naming in code, designs, and documentation MUST follow this glossary.
Rationale
Section titled “Rationale”Clear and consistent naming is fundamental to a shared understanding of the architecture. By consolidating BDI and CTN terms into one place, we eliminate ambiguity. Adding a dedicated ASR chapter ensures that the technical entities used in the codebase are also business-aligned and documented.
Consequences
Section titled “Consequences”- Positive:
- Reduced cognitive load and improved clarity for everyone involved.
- Seamless alignment between business requirements and technical implementation.
- Better AI assistance due to high-quality, consolidated context.
- Negative:
- Developers and architects must ensure the glossary is updated when new significant concepts are introduced.
- Neutral:
- Existing documentation and code might require refactoring to align with the consolidated terms.
Implementation Plan
Section titled “Implementation Plan”- Phase 1: Consolidate existing BDI and CTN terms into
docs/arc42/12-glossary/ctn-glossary.md(Completed). - Phase 2: Add the ASR Bounded Context chapter to the glossary (Completed).
- Phase 3: Review ASR codebase and data model for alignment with the new glossary sections.
- Phase 4: Enforce glossary usage in PR reviews and design sessions.
Compliance and Validation
Section titled “Compliance and Validation”- Security review completed
- Performance impact assessed
- Integration impact evaluated
- Documentation updated
- Stakeholder approval obtained
Related Documents
Section titled “Related Documents”Status History
Section titled “Status History”| Date | Status | Notes |
|---|---|---|
| 2026-05-28 | Proposed | Initial proposal (Naming follows glossary) |
| 2026-06-11 | Proposed | Rewritten to emphasize consolidation and ASR bounded context |
Status flow: Proposed → Accepted → Reviewed → Approved (or Rejected). A superseded ADR keeps its file; only its status changes to Superseded by NNNNN.
ADR format based on Michael Nygard’s template with CTN-specific enhancements
In samenwerking met
