Architectural Decision Records

Architectural Decision Records (ADR)

BINDING RULES FOR ALL AI AGENTS: Every architecturally significant decision MUST be captured as an ADR before merging. Default template = MADR. Default location = docs/adr/. ADRs are append-only: an accepted ADR is never edited — supersede it instead. Source: https://adr.github.io/.

This guide is the source of truth for ADR practice in this project. Skills and commands reference it; do not duplicate content elsewhere.

1. Definitions

• Architectural Decision (AD): justified design choice addressing a functionally or non-functionally significant requirement.
• Architecturally Significant Requirement (ASR): requirement with measurable effect on system architecture or quality attributes.
• Architectural Decision Record (ADR): persistent document capturing one AD plus its context, alternatives, rationale, and consequences.
• Decision Log: the ordered set of all ADRs in the repo.

2. When to Write an ADR

Write an ADR when the decision affects any of:

• Layer boundaries or dependency direction (hexagonal violations).
• Port shape or contract (inbound/outbound interfaces).
• Adapter technology choice (JDBC vs JPA, Kafka vs RabbitMQ, REST vs gRPC).
• Aggregate boundary or bounded context split.
• Transaction strategy (Transaction port impl, outbox vs sync, saga vs 2PC).
• Persistence engine, message broker, cache provider.
• Security model (auth, authorization, multi-tenancy).
• Cross-cutting concerns implemented as decorators (CoR ordering).
• Public API contracts and versioning policy.
• Build / deployment topology (modules, packaging, runtime).

Do NOT ADR trivial choices: variable names, internal helper signatures, formatting, single-file refactors with no API change.

3. Template Selection

Default to MADR unless a project rule says otherwise.

4. MADR Template (default)

Filename: docs/adr/NNNN-title-with-dashes.md (e.g. 0007-use-kafka-outbox.md). NNNN is consecutive, zero-padded to 4 digits. Lowercase title with dashes.

1
---
2
status: proposed              # proposed | accepted | rejected | deprecated | superseded
3
date: 2026-05-05              # YYYY-MM-DD, last update
4
decision-makers: [andres, jane]
5
consulted: [security-team]    # two-way communication
6
informed: [product]           # one-way communication
7
---
8

9
# NNNN. Short Decision Title
10

11
## Context and Problem Statement
12

13
Two or three sentences (or a short narrative) describing the forces and the
14
problem. State the ASR being addressed and any quality attributes at stake.
15

16
## Decision Drivers
17

18
- Driver 1 (e.g., must support exactly-once delivery)
19
- Driver 2 (e.g., team has Kafka operational experience)
20
- Driver 3 (e.g., budget caps managed-broker spend)
21

22
## Considered Options
23

24
- Option A — Kafka with transactional outbox
25
- Option B — RabbitMQ with publisher confirms
26
- Option C — Direct JDBC + Debezium CDC
27

28
## Decision Outcome
29

30
Chosen option: **Option A — Kafka with transactional outbox**, because it
31
satisfies the exactly-once driver while reusing existing operational
32
expertise.
33

34
### Consequences
35

36
- **Good** — exactly-once via outbox pattern + idempotent consumers.
37
- **Good** — reuse of existing Kafka cluster, no new infra cost.
38
- **Bad** — additional complexity in outbox table maintenance and relay process.
39
- **Neutral** — schema registry adoption deferred to ADR-NNNN.
40

41
### Confirmation
42

43
Compliance verified by:
44
- ArchUnit rule forbidding direct `KafkaTemplate` use outside outbox-relay module.
45
- Integration test `OutboxRelayIT` asserting at-least-once delivery with dedup.
46
- Runtime metric `outbox.lag.seconds` < 5s SLO.
47

48
## Pros and Cons of the Options
49

50
### Option A — Kafka with transactional outbox
51
- Good — leverages existing infra.
52
- Good — fits hexagonal port `DomainEventPublisher`.
53
- Bad — operational burden of the relay process.
54

55
### Option B — RabbitMQ with publisher confirms
56
- Good — simpler at-least-once model out of the box.
57
- Bad — introduces a second broker, higher TCO.
58

59
### Option C — Direct JDBC + Debezium CDC
60
- Good — zero application-level publishing code.
61
- Bad — couples consumers to internal schema; brittle on migrations.
62

63
## More Information
64

65
- Spike: `docs/spikes/2026-04-kafka-vs-rabbit.md`
66
- Related: ADR-0003 (use hexagonal architecture), ADR-0005 (transaction port).

Required vs Optional Sections

Frontmatter

5. Status Lifecycle

1
proposed ──► accepted ──► deprecated
2
   │            │
3
   ▼            ▼
4
rejected    superseded ──► points to NNNN of replacement

Rules:

• proposed is the initial state when scaffolded.
• Move to accepted once decision-makers agree and the PR is approved.
• rejected is final; keep the file for the historical record.
• deprecated means the decision is no longer in force but no replacement exists.
• superseded requires a new ADR; old ADR’s frontmatter gains superseded-by: NNNN and the new ADR’s frontmatter gains supersedes: NNNN.

Immutability: an accepted ADR is append-only. Never edit its content. Fix typos before acceptance only. After acceptance, write a new ADR that supersedes it.

6. Nygard Template (quick capture)

1
# NNNN. Short Title
2

3
## Status
4
Accepted
5

6
## Context
7
What is the issue we're seeing that motivates this decision.
8

9
## Decision
10
What we are going to do.
11

12
## Consequences
13
What becomes easier or harder.

Use when the decision is obvious and tradeoffs are minimal. Promote to MADR if a reviewer asks “why not X?”.

7. Y-Statement (one-liner)

In the context of <use case>, facing <concern>, we decided for <option> and against <alternatives> to achieve <quality>, accepting <downside>.

Extended form adds because <rationale> and rejected: <list>.

Drop a Y-Statement into a PR description, code comment, or commit message when an ADR is overkill but the reasoning is non-obvious.

8. ISO/IEC/IEEE 42010 (formal)

Nine information items: identifier, summary, decision, status, rationale, alternatives, related decisions, related concerns, related artifacts. Use only in regulated / certification contexts. Out of scope for typical project work.

9. Repo Layout

1
docs/
2
└── adr/
3
    ├── README.md              # decision log index, auto- or hand-curated
4
    ├── 0001-record-architectural-decisions.md
5
    ├── 0002-use-hexagonal-architecture.md
6
    ├── 0003-transaction-port.md
7
    └── ...

docs/adr/README.md lists all ADRs with status and one-line summary. Regenerate or hand-edit on every accepted/superseded change.

10. Workflow

1. Detect significance — does the change match any trigger in §2?
2. Run /add-adr "short title" (or scaffold manually).
3. Fill MADR sections. Set status: proposed.
4. Open PR. Reviewers comment on the ADR alongside code.
5. On approval, flip status to accepted in the same PR or a follow-up.
6. Update docs/adr/README.md index.
7. Reference the ADR in code via // see ADR-NNNN only when context is non-obvious.

11. Hexagonal Architecture Tie-Ins

ADRs that this project expects, indicative list:

• 0001 — Use hexagonal architecture (ports & adapters).
• 0002 — Transaction port over @Transactional on use cases.
• 0003 — Outbox pattern for domain event publishing.
• 0004 — Chain of Responsibility for cross-cutting decorators.
• 0005 — ArchUnit as the layer boundary enforcement gate.
• 0006 — JsonMapper over ObjectMapper (Jackson 3.x).

When introducing a new bounded context, port, or adapter technology, write an ADR before merging.

12. Review Checklist

Before accepting an ADR:

• Title is problem-solution oriented, not solution-only.
• At least 2 options considered.
• Decision Drivers are measurable (no “better” without a metric).
• Consequences include at least one negative item.
• Confirmation lists how compliance is enforced (ArchUnit / IT / SLO / lint).
• No conflict with existing accepted ADRs (or this one supersedes them explicitly).
• Filename matches NNNN-title-with-dashes.md and is consecutive.
• Frontmatter status is proposed at PR open, accepted only after approval.

13. Anti-Patterns

• ADR for a code-style nit. Use clean-code.md or a lint rule instead.
• “We picked X because the team likes it” with no driver. Restate the driver.
• Editing an accepted ADR. Supersede.
• Single-option ADR. If only one option exists, capture it as a Nygard or skip.
• ADRs in a wiki separate from the repo. Decisions co-locate with code.
• Oversize ADRs (>2 pages). Split or link out to a spike.

14. Tooling (optional)

• adr-tools — bash CLI for scaffolding ADRs. Not required.
• /add-adr slash command in this repo (see commands/add-adr.md) — preferred for AI-driven flows.
• Render docs/adr/README.md as the decision log; many static-site generators support it natively.

15. References

• ADR organization: https://adr.github.io/
• MADR: https://adr.github.io/madr/
• Templates comparison: https://adr.github.io/adr-templates/
• Nygard’s original post: “Documenting Architecture Decisions” (2011).
• Y-Statement: “Sustainable Architectural Decisions” (Zimmermann et al.).