Architecture Decision Record

An architecture decision record, or ADR, explains a significant design choice and why it was made. It connects context and constraints to a decision and its consequences. A diagram shows structure; the ADR explains why this structure was chosen over plausible alternatives.

Record a concrete decision, such as retaining received CSV files separately from parsed tables. Explain the need for parsing evidence, alternatives, added storage and access work, the owner, and any unresolved assumptions. Do not present estimated cost as a measured result.

Use a visible status such as proposed, accepted, rejected, or superseded. Preserve an accepted decision’s rationale when circumstances change; link a replacement decision rather than silently rewriting the old reason. Revisit triggers can include measured restore time exceeding its target or a source contract changing.

An accepted ADR records agreement, not proof that the implementation works. Link workload measurements, tests, and follow-up owners. It specializes the general idea of a decision record for architectural choices; an AI-use authorization record answers a different question about permitted use.

Reference: AWS: ADR process. See Designing End-to-End Data Architecture for the worked example.