Architectural Decision Records (ADRs)

Author(s):

Gordo Lowrey - Architect

Date:

February 2024

Summary

This document proposes the adoption of a process to document the architectural decisions made during the software development process. ADRs aim to provide clarity, rationale, and context for important architectural decisions.

What is an ADR?

An Architectural Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. It serves as a historical record that helps future team members understand why decisions were made.

Purpose of ADRs

• Documentation of Architecture: Create a clear and permanent record of architectural decisions and their rationale.
• Facilitate Knowledge Sharing: Help new team members understand the context of past decisions.
• Improve Decision Making: Encourage careful consideration and documentation of architectural choices.

Principles of ADRs

• Clarity and Conciseness: ADRs should be clear, concise, and focused on a single decision.
• Rationale and Context: Each ADR should explain the reason behind the decision and the context in which it was made.
• Accessibility: ADRs should be easily accessible to all team members.

ADR Process

1. Proposal: When a significant architectural decision is made, the responsible architect or developer drafts an ADR.
2. Discussion: The ADR is shared with the team for feedback and discussion.
3. Revision: The ADR is revised based on team feedback.
4. Finalization: The ADR is finalized and added to the project documentation.
5. Review: ADRs are periodically reviewed and updated as necessary.

ADR Document Structure

• Title: Descriptive title reflecting the decision.
• Author: Name of the person(s) responsible for the decision.
• Date: Date when the ADR was created or revised.
• Status: Current status of the decision (e.g., proposed, accepted, deprecated).
• Context: The circumstances that led to the decision.
• Decision: A clear statement of the architectural decision.
• Consequences: The impact of the decision, including benefits and potential drawbacks.
• Alternatives Considered: Other options that were considered and why they were not chosen.

Version Control and Tracking

• Repository: ADRs are best stored in the same version-controlled repository as the project.
• File Naming: ADRs should be named sequentially and descriptively for easy reference.
• Documentation Integration: ADRs must be linked or integrated into the broader project documentation for accessibility.

Appendices

Appendix A: Process Diagram

@startuml
start
:Identify Need for Decision;
:Draft ADR Document;
:Share for Team Feedback;
if (Feedback Received?) then (yes)
    :Revise ADR;
else (no)
    :Proceed to Finalize;
endif
:Finalize and Record ADR;
:Regularly Review and Update;
stop
@enduml

Appendix B: References

• Wikipedia - Architectural decision
• AWS - Architectural Decision Records Process
• ADR GitHub Page

Appendix C: Differences Between ADRs and RFCs

Purpose:

• RFCs: Focus on broader proposals or changes affecting systems, processes, or standards. They are used for discussing, deciding, and documenting significant changes.
• ADRs: Specifically document architectural decisions. They provide context, rationale, and implications of architectural choices made during a project.

Scope:

• RFCs: Can encompass a wide range of topics, including new features, technical strategies, process improvements, or organizational changes.
• ADRs: Limited to architectural decisions, detailing the considerations and choices in the project's architecture.

Usage:

• RFCs: Used for collaborative decision-making involving various stakeholders. They are more discussion-oriented.
• ADRs: Serve as a historical record for architectural decisions, primarily used for documentation and reference purposes.