Document Decision

Quick Reference

Scope

• ✅ Technology selection (PostgreSQL vs MongoDB, Kong vs HAProxy)
• ✅ Structural decisions (internal service vs SaaS, queue vs sync call, adapter boundaries)
• ✅ Infrastructure choices (replication, topology, managed vs self-hosted)
• ✅ Security/integration choices with lasting consequences
• ❌ Repository structure, CI/CD, editor tooling, or diagram-authoring mechanics

Core Pattern

1. Name the decision clearly — one line that states the architectural choice.
2. Capture the forces — constraints, risks, scale, ownership, compliance, latency, migration pressure.
3. State the decision — what is chosen, where it applies, and what is explicitly out of scope.
4. List impacted elements — affected LikeC4 elements and, if useful, impacted views or deployment areas.
5. Record consequences — at least positive and negative, optionally neutral/operational consequences.
6. Add follow-up — migrations, model updates, validation, runbooks, or open questions.

Example

# ADR-0007: Choose PostgreSQL for the primary transactional store

## Status
Accepted

## Context
`{YourSystem}` needs strong transactional guarantees, relational querying, and predictable backup tooling.
The team considered MongoDB and PostgreSQL for the primary business data store.

## Decision
Use PostgreSQL for `{YourSystem}.primaryDatabase`.

## Impacted Elements
- `{YourSystem}.api`
- `{YourSystem}.primaryDatabase`
- Any view or deployment slice that documents persistence, backup, or failover

## Consequences

### Positive
- Strong ACID guarantees for transactional workflows
- Mature replication, backup, and observability ecosystem
- Clear fit for relational reporting and joins

### Negative
- Requires schema migration discipline
- Less flexible for rapidly changing document-shaped payloads
- Operational tuning may be needed as write volume grows

### Neutral
- Some JSON-heavy payloads may still remain in application-layer adapters

## Follow-up
- Update the database container technology to `PostgreSQL`
- Review replication and backup assumptions
- Validate affected views and deployment documentation

Integration with LikeC4

• Reference impacted elements by real element ID or stable descriptive name
• Mention affected views only when they are known and relevant; do not invent view IDs
• If the decision changes the model itself, follow up with the appropriate modeling skill and then validate with test-model

Useful follow-ups:

• element or boundary changes → create-element, create-relationship
• deployment consequences → model-deployment-infrastructure
• validation after changes → test-model

Common Mistakes

❌ Documenting how the diagram was edited — ADRs capture design rationale, not modeling mechanics

❌ Missing costs or risks — a decision without trade-offs reads like advocacy, not architecture

❌ No impacted elements — if readers cannot tell what parts of the model are affected, the ADR is too abstract

❌ Confusing the ADR with an implementation checklist — the ADR states the choice and its consequences; detailed execution can be follow-up work

❌ Treating a local ADR starter as an oracle — reuse the structure, not the example wording or domain content