Skip to content

Latest commit

 

History

History
76 lines (50 loc) · 3.47 KB

Architectural_Decision_Records_Wiki.md

File metadata and controls

76 lines (50 loc) · 3.47 KB

Architectural Decision Records (ADRs)

Definition

Architectural Decision Records (ADRs) are short, concise documents that capture a significant architectural decision made during the development of a software system. They describe the context of the decision, the problem it addresses, the options considered, the chosen solution, and the consequences of that choice.

Purpose and Importance

  • Documenting Rationale: They explain why a particular architectural decision was made.
  • Onboarding New Team Members: New developers can quickly understand the architectural landscape.
  • Preventing Rework: Avoid re-debating the same issues repeatedly.
  • Facilitating Communication: Provide a clear, centralized record of architectural decisions.

Structure of an ADR

  1. Title: A concise, descriptive title.
  2. Status: The current state of the decision (e.g., Proposed, Accepted, Superseded).
  3. Date: When the decision was made.
  4. Context: The problem or challenge that necessitated the decision.
  5. Decision: The chosen architectural solution.
  6. Options Considered: A brief description of alternative solutions.
  7. Consequences: The positive and negative consequences of the chosen solution.

Example ADR (Markdown Format)

# ADR 001: Use PostgreSQL for Primary Data Store

## Status

Accepted

## Date

2023-10-26

## Context

We need to choose a primary data store for our new e-commerce application. The application will have a relational data model and will require transactional consistency.

## Decision

We will use PostgreSQL as our primary data store.

## Options Considered

*   **MySQL:** A popular open-source relational database. It is a solid choice, but PostgreSQL has better support for advanced features like JSONB and full-text search, which we may need in the future.
*   **MongoDB:** A popular NoSQL database. It is a good choice for applications with a flexible schema, but our data model is relational, and we need transactional consistency, which is better supported by PostgreSQL.

## Consequences

*   **Positive:**
    *   PostgreSQL is a mature, reliable, and feature-rich relational database.
    *   It has excellent support for transactions and data consistency.
    *   It has a large and active community.
*   **Negative:**
    *   It may be more complex to manage than a simpler database.
    *   It may not be the best choice for applications with a very high write load.

The ADR Process

  1. Propose: A team member identifies the need for an architectural decision and creates a new ADR with the status "Proposed".
  2. Discuss: The team discusses the proposed ADR, considering the different options and their consequences.
  3. Decide: The team comes to a consensus on the decision and updates the ADR with the status "Accepted".
  4. Implement: The team implements the decision.

Tools for Managing ADRs

  • Markdown Files: Simple, human-readable, and version-controllable.
  • adr-tools: A command-line tool for creating and managing ADRs.
  • Wiki/Confluence: A centralized knowledge base for storing and sharing ADRs.

Conclusion

Architectural Decision Records are a lightweight yet powerful practice for documenting the rationale behind significant architectural choices. By providing context, options, and consequences, ADRs improve communication, facilitate onboarding, prevent rework, and serve as a valuable historical record for the evolution of a software system.