Skip to content

The Architecture Decision Framework

What is this?

You asked to understand the difference between RFCs, ADRs, and Proposals, and where this methodology comes from. This note explains the industry-standard framework we are adopting.

1. The Definitions

In software engineering, we distinguish between the process of deciding and the record of the decision.

RFC (Request for Comments)

  • Also known as: Architecture Proposal, Design Doc, One-Pager.
  • Tense: Future ("We should do X").
  • Purpose: To solicit feedback, invite "Senior Critique," and explore alternatives.
  • State: Mutable. It changes as people comment on it.
  • Origin: Originated from the IETF (Internet Engineering Task Force) in 1969 to define the protocols of the Internet (e.g., HTTP, TCP). Adopted by open-source communities (Rust, React, Vue) to democratize decision-making.

ADR (Architecture Decision Record)

  • Tense: Past/Present ("We will do X" or "We decided X").
  • Purpose: To capture Context and Consequences. It explains why a decision was made at a specific point in time, even if that decision turns out to be wrong later.
  • State: Immutable. Once accepted, you don't edit an ADR. If you change your mind later, you write a new ADR that "Supersedes" the old one.
  • Origin: Popularized by Michael Nygard in 2011.

2. The Workflow: From Proposal to Law

We are using a "Docs as Code" workflow that mirrors the lifecycle of a law bill.

graph LR
    A[Idea] -->|Draft| B("RFC / Proposal")
    B -->|"Debate & Critique"| B
    B -->|Consensus| C{Decision}
    C -->|Accepted| D("ADR (The Law)")
    C -->|Rejected| E[Archive]
  1. Draft (The Proposal): You write docs/architecture/proposals/002_guest_mode.md. This is the "Bill" in parliament. It discusses trade-offs (e.g., "Dexie vs. LocalStorage").
  2. Review (The Debate): The team (or your "Senior Critique" persona) tears it apart. You update the Proposal.
  3. Acceptance (The Vote): Once agreed, the Proposal is "ratified."
  4. Record (The Statute): You move/rename it to docs/architecture/decisions/002_guest_mode.md (or create a summary there). It is now the law of the land.

3. Why do we do this? (The "Bus Factor")

The hardest thing to understand in legacy code is not what the code does, but why it was written that way.

"Why did Ben use Dexie.js instead of just localStorage in 2026? It's so over-engineered!"

Without an ADR, the future developer (or AI) assumes you were just being fancy. With an ADR, they read:

"Context: We needed to store 6 months of meal logs. LocalStorage has a 5MB blocking limit that causes UI jank. Therefore, we accepted the complexity of Dexie to ensure 60fps performance."

The Framework Source: This specific combination (RFCs for discussion, ADRs for history, stored in Git) is widely known as the "Nygard Format" (for the ADR structure) combined with the "Docs as Code" philosophy.

4. A Deep Dive into the History

To truly understand this framework, we have to look at the three separate streams of history that converged to create this modern workflow: The RFC, The ADR, and The Design Doc.

1. The Ancient Ancestor: The RFC (1969)

Long before Git existed, the internet was built on Requests for Comments (RFCs).

  • Origin: In 1969, Steve Crocker invented the RFC format to record notes on the development of the ARPANET (the precursor to the Internet).
  • The Philosophy: The tone was humble. It wasn't a "commandment"; it was a "request for comments." It encouraged peer review and consensus.
  • Modern Usage: Open-source communities (like Rust, React, and Ember) adopted the RFC process to discuss proposed changes before they are implemented. This is the "Discussion" phase of our framework.

2. The Game Changer: Michael Nygard & The ADR (2011)

For a long time, software architecture was documented in massive, monolithic Word documents (often called "Software Architecture Documents" or SADs). Nobody read them, and they went out of date instantly.

  • The Spark: In November 2011, Michael Nygard wrote a seminal blog post titled "Documenting Architecture Decisions."
  • The Innovation: He proposed dumping the massive Word doc in favor of small, immutable text files stored in the version control system (Git) alongside the code.
  • The Nygard Format: He defined the structure that is now industry standard:
    1. Title
    2. Context (The problem)
    3. Decision (What we are doing)
    4. Status (Accepted/Rejected)
    5. Consequences (The trade-offs)

This birthed the ADR—a way to capture the "Why" of the history, not just the "What."

3. The "Design Doc" Culture (Google & Uber)

While Nygard focused on decisions, big tech companies focused on proposals.

  • Google: Famous for its "Design Doc" culture. Before writing code, engineers write a Google Doc outlining the trade-offs, security implications, and alternatives.
  • The Shift: As "Docs as Code" became popular, the industry realized that Google Docs often rot (links break, permissions get lost). Engineers started moving these Design Docs into Markdown inside Git—merging the Google culture with the Nygard format.

5. How They Fit Together Today

Your statement mentions using RFCs for discussion and ADRs for history. This is the "Gold Standard" workflow used by modern engineering teams (like Spotify, GitHub, and Amazon).

Here is how the distinct histories merge into one workflow:

Phase Tool Historical Origin Purpose
1. Proposal RFC IETF (1969) / Open Source "I have an idea. Let's discuss if we should do it." Active, fluid discussion.
2. Review Pull Request BitKeeper / Git The mechanism to review the text changes.
3. Decision ADR Michael Nygard (2011) "The discussion is over. We have decided X." Immutable, historical record.

6. How it fits ChatKcal

  • docs/architecture/proposals/: Our workspace for thinking (The RFC/Design Doc).
  • docs/architecture/decisions/: Our historical log of "Why" (The ADR).
  • docs/architecture/*.md: The current "How" (Living documentation).

7. The Standard ADR Template

Following the Nygard Format, a high-quality ADR should include these specific sections. This ensures that any future developer can understand the constraints you were working under.

# ADR [Number]: [Short Title]

!!! info "Metadata"
    - **Status:** [Proposed | Accepted | Superseded | Rejected]
    - **Date:** YYYY-MM-DD
    - **Deciders:** [List of stakeholders]
    - **Consulted:** [List of experts consulted]

## 1. Context
What is the issue that we're seeing? What are the requirements (business and technical)?
Include any relevant links to issues, Slack threads, or customer feedback.

## 2. Decision
What is the change that we're proposing and/or doing?
State the decision clearly and concisely. Use "We will..." or "We decided to..."

## 3. Alternatives Considered
What else did we think about doing? Why did we choose this over the alternatives?
- **Option A:** [Description]. Why not? [Reason].
- **Option B:** [Description]. Why not? [Reason].

## 4. Consequences
What becomes easier or harder as a result of this change?
### :white_check_mark: Positive (Benefits)
- [List positive outcomes]
### :x: Negative (Trade-offs)
- [List technical debt or limitations introduced]

## 5. Compliance
How will we ensure this decision is followed? (e.g., "Add to PR checklist", "Added ESLint rule").

8. Review: Guest Mode Proposal (ACP-001) vs. Standard

How does our current active proposal stack up against the Nygard standard?

Critique of ACP-001: Guest Mode Architecture:

  • Metadata: ✅ Has Status (Draft), Date, Type.
  • Context: ✅ Explains the goal (First Log Experience) and trigger.
  • Decision: ✅ Proposes Dexie.js + Repository Pattern + Batch Sync.
  • Alternatives: ❌ Missing. It presents the chosen path as the only path. Ideally, it should briefly explain why we aren't using localStorage (blocking I/O) or Amplify DataStore (schema pollution).
    • Note: We did this analysis in ACP-002 (Deep Research), but the Proposal itself should summarize these rejections.
  • Consequences: ✅ Has an "Impacts & Risks" section, which covers consequences well (Cache poisoning, UUID generation).

Verdict: The Proposal is strong on Technical Specification but weak on Decision Rationale.

Recommendation: When we convert this Proposal into ADR 007, we must merge the "Deep Research" (ACP-002) into the "Alternatives Considered" section. This will create a complete historical record of why we chose the difficult path (IndexedDB) over the easy path.