9. Architecture Decisions (ADRs)

This chapter holds the Architecture Decision Records that capture the choices made during the design and evolution of the Connected Trade Network.

Two decision tiers

Decisions are split into two tiers by audience:

• ADR — Architecture Decision Record (this directory): board-level, large-scale choices an architecture board would own (stack, structure, identity, federation). Five-digit sequential ids (00001, …).
• TDR — Technical Decision Record (docs/ai/adrs/): low-level, purely technical choices of concern only to builders (schema tooling, intake field mapping). Separate four-digit sequence (TDR-0001, …).

A decision belongs in the ADR tier when it is large-scale and board-relevant; otherwise it is a TDR. Each tier has its own numbering sequence and index; cross-references between tiers are by id.

Existing ADRs

Ref	Title
00001	Record architecture decisions
00002	Define a preferred technology stack
00003	Separate users and participants
00004	Naming follows the glossary
00005	Use AGENTS.md for AI guidelines
00006	Token claim composition
00007	Identity mutation proxy
00008	External IdP federation strategy
00009	Layered source code structure
00010	Evolving from Package-based Plugins to Quarkus Extensions
00011	URI-Based Legal Entity Identifier Scheme
00012	OnboardingRequest Lifecycle Transition Seam
00013	Applicant Keycloak account provisioned at intake
00014	Claim Verification Provider seam and eHerkenning control-proof
00015	End-to-End Browser Test Tooling — Playwright + Chromium
00016	Language Support and Documentation Policy
00017	Test Automation Using Playwright with TypeScript (strategic portal UI framework)
00018	Build-enforced Java formatting via Spotless + an Eclipse JDT profile
00019	Bulk import is a distinct onboarding Source with orthogonal Validity and admin-owned repair
00020	Test Data Handling Strategy
00021	Documents as a decoupled service behind an ObjectStorageProvider seam, Postgres-first
00022	Module seam pattern — in-process seam vs internal, with a REST-boundary zone (audit pilot)
00023	CTN Test Strategy — layers, ownership, and CI gating (umbrella over 00015 / 00017 / 00020)

(Two early decisions were reclassified as technical decisions and moved to the TDR tier — see docs/ai/adrs/. Numbering caveats: 00015 was used twice (Test Data Handling Strategy and the Playwright e2e tooling ADR); ADR-00017 is present in-repo but its file is named with an extra leading zero (000017-…); 00019 is currently unused. A separate ADR-renumbering branch (not yet merged) fixes these collisions/gaps — reconcile 00021’s number against that branch on merge.)

Templates

• ADR-TEMPLATE.md — MADR-style template for new architecture decisions.
• REQ-TEMPLATE.md — Template for capturing requirements that drive an ADR.

Conventions

• Numbering is sequential (00001, 00002, …). Pick the next free number.
• Status moves through Proposed → Accepted → Reviewed → Approved (or Rejected); a superseded ADR keeps its file but its status changes to Superseded by 0000N.
• Every ADR has Context, Decision and Consequences sections (see the template).