Record an architecture decision and its trade-offs

Diagrams show components; an Architecture Decision Record explains why a consequential choice was made and when it should be reconsidered.

Validate an ADR

The delivery lab records a fictional webhook decision.

from delivery_cases import adr_case

result = adr_case()
assert result["complete"] is True
assert result["alternatives_count"] == 2
assert result["tradeoffs_present"] is True
assert result["adr"]["decision"] == "database inbox with unique event_id"

Use a stable ID/title, status/date, context/forces, decision, alternatives, positive/negative consequences, supporting evidence and review trigger. Keep it concise and commit it near code. Supersede old ADRs rather than erasing history.

Record decisions that affect security, data, reliability, cost or irreversible structure. Do not write an ADR for every minor implementation detail. Link tests or measurements that justified the choice and update if assumptions fail.

The FDE for Freshers course requires learners to explain architecture, not only draw it.

Exercise

Write an ADR for queue versus synchronous processing, including two rejected choices and an event-volume trigger for review.

Continue learning

This article is part of the FDE career entry and client-delivery practice sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Write a clear weekly project update.
• Continue with Design a user acceptance test for a client simulation.

Reference: ADR guidance.