1. The Cost of Forgotten Decisions
Two years after a system is built, a new engineer asks: 'Why did we use DynamoDB here instead of PostgreSQL?' Nobody remembers, or the original architect has left the company. The team risks repeating old mistakes.
An Architecture Decision Record (ADR) is a short, immutable markdown file stored directly in the git repository alongside the source code.
2. Standard ADR Structure
Title: Numbered title (e.g. `ADR-004: Adopt Kafka for Asynchronous Order Events`).
Status: Proposed, Accepted, Deprecated, or Superseded.
Context: What business or technical forces are driving this choice?
Decision: What did we decide to do?
Consequences: What are the trade-offs, positive benefits, and operational costs?
Model this architecture on the HLDForge Canvas
Turn static box diagrams into living, collaborative systems. Drag and drop microservices, Kafka clusters, and cache tiers. Run automated SPOF detection and STRIDE threat modeling in real time.
Written by HLDForge Architecture Team
Staff Systems Architect
The HLDForge Architecture Team publishes practical engineering guides, real-world case studies, and high-concurrency blueprints to help engineers build scalable and fault-tolerant software.