ADR Format — Architecture Decision Records

ADR Format — Architecture Decision Records

Template and conventions for documenting architectural decisions.

File Location

docs/adr/
  ADR-001-<slug>.md
  ADR-002-<slug>.md
  ...

Numbering is sequential and never reused. Deprecated ADRs are marked as such, not deleted.

Template

# ADR-NNN: Title

**Date:** YYYY-MM-DD  
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN  
**Deciders:** [who was involved in this decision]

---

## Context

What is the problem or situation that forced this decision?
What constraints exist (technical, time, team, cost)?
What happens if we do nothing?

## Decision

State the decision clearly in one or two sentences.
Use active voice: "We will..." not "It was decided that..."

## Options Considered

### Option A — [Name]
**Description:** brief explanation  
**Pros:** what this gets right  
**Cons:** what this gets wrong or costs  

### Option B — [Name]
**Description:** brief explanation  
**Pros:**  
**Cons:**  

### Option C — [Name] *(if applicable)*

## Rationale

Why was Option X chosen over the others?
What was the deciding factor?

## Consequences

**Positive:**
- What becomes easier or better

**Negative:**
- What becomes harder or more costly
- What technical debt this introduces

**Actions Required:**
- [ ] Concrete next steps that must happen as a result of this decision

---

*Supersedes: ADR-NNN (if applicable)*  
*Related: ADR-NNN (if applicable)*

Rules for Writing ADRs

• Write them at decision time, not after implementation.
• One decision per ADR. If you have two decisions, write two ADRs.
• Be honest about the downsides. An ADR that only lists pros is not useful.
• Keep them short — if the context section exceeds half a page, you're writing a design doc, not an ADR.
• Never delete an ADR. Mark it Deprecated or Superseded with a reference to the replacement.
• Link to ADRs from code comments where the decision directly affects the code.

Example

# ADR-001: Use Promtail instead of Filebeat for log shipping

**Date:** 2024-11-15  
**Status:** Accepted  
**Deciders:** [you]

---

## Context

We need to ship logs from Nginx, PHP-FPM, and Node.js apps to Loki.
Both Filebeat and Promtail are viable. We already run Grafana and Loki.

## Decision

We will use Promtail for log collection and shipping to Loki.

## Options Considered

### Option A — Promtail
**Pros:** Native Loki integration, label-based pipeline, same ecosystem as Grafana/Loki, lighter resource footprint  
**Cons:** Only works with Loki (no Elasticsearch option later without replacing it)

### Option B — Filebeat
**Pros:** More mature, supports multiple outputs  
**Cons:** Heavier, requires extra transformation config to work well with Loki, different ecosystem

## Rationale

We are committed to the Grafana/Loki stack. Promtail's native integration reduces config complexity.
The Loki lock-in is acceptable — switching log backends is a deliberate migration, not an accident.

## Consequences

**Positive:** Simpler pipeline config, consistent label model across metrics and logs  
**Negative:** Locked to Loki as the log backend  
**Actions Required:**
- [ ] Write Promtail scrape configs for all log paths
- [ ] Validate log pipeline end-to-end before decommissioning any existing log collection