Skip to content

Architecture Decision Records (ADR)

Version: 1.0.0 | Last Updated: 2025-01-06 | Status: Active

Overview

Architecture Decision Records (ADRs) document significant architectural decisions made during the development of MBPanel. Each ADR captures the context, decision, and consequences of architectural choices.

What is an ADR?

An ADR is a short text file that describes a significant architectural decision. The template follows the Michael Nygard template:

  1. Title - Short, descriptive title
  2. Status - Proposed, Accepted, Deprecated, Superseded
  3. Context - What is the issue that we're seeing that is motivating this decision or change?
  4. Decision - What is the change that we're proposing and/or doing?
  5. Consequences - What becomes easier or more difficult to do because of this change?

ADR Index

Accepted Decisions

Template

To create a new ADR, copy this template:

# ADR-000: [Title]

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded
**Deciders:** @team-members
**Related:** ADR-000, ADR-000

## Context

[What is the issue that we're seeing that is motivating this decision or change?]

## Decision

[What is the change that we're proposing and/or doing?]

## Consequences

- [Positive consequence 1]
- [Positive consequence 2]
- [Negative consequence 1]
- [Negative consequence 2]

## References

- [Link to external documentation]
- [Link to discussion]

Guidelines

When to Write an ADR

Write an ADR when: - Making a significant architectural change - Choosing between competing technologies - Establishing new patterns or conventions - Changing existing architectural decisions

ADR Lifecycle

  1. Proposed - Initial draft for discussion
  2. Accepted - Decision made and implemented
  3. Deprecated - No longer recommended but still in use
  4. Superseded - Replaced by a newer ADR (link to replacement)

Naming Convention

  • Format: 000-short-title.md
  • Use sequential numbers (001, 002, 003...)
  • Use kebab-case for titles
  • Store in /docs/architecture/adr/