Why ADRs Matter: Capturing Architectural Decisions with Purpose

Have you ever looked at a piece of code and asked yourself, "Why did we do it this way?"

Welcome to the world of Architecture Decision Records (ADR) — a simple but powerful technique to preserve the "why" behind technical decisions in your projects.

What Problem Does ADR Solve?

In every software project, decisions are made. We decide which framework to use, why a service communicates over REST instead of gRPC, or why a particular domain model was split into two bounded contexts. But over time, people leave, contexts shift, and the reasoning behind those choices gets lost.

ADR is the answer to the question "Why did we do this?"

It gives a voice to decisions, capturing not just the what, but more importantly, the why. It’s not enough to read the code — ADRs give you the intent behind it.

What Is an ADR?

An Architecture Decision Record is a short text document describing a single architectural decision. That’s it. Each ADR should be:

• Immutably stored - Once created, the document should not change. And should never be removed!
• Dated and versioned - You need to know when the decision was made.
• Status-driven - A decision can be Proposed, Accepted, Deprecated, Superseded, or Obsolete.
• Tracked over time - The collection of ADRs forms a historical timeline of the architecture.

The Structure of an ADR

A typical ADR document includes the following sections:

• Title - Short and descriptive (e.g. “Use PostgreSQL as main data store”)
• Status - Current state of the decision (Accepted, Rejected, etc.)
• Context - The background and forces at play when the decision was made.
• Decision - What was decided, clearly stated.
• Consequences - What happens as a result of this decision.

If you're wondering where the "why" is captured — it's mainly in the Context section. This is where you describe the situation, constraints, trade-offs, or previous options that led to this particular choice. Without it, the decision is just a fact. With it, it becomes a rationale.

Why Not Just Use Jira Tickets or Docs?

Because those are too broad or ephemeral. ADRs are focused, atomic, and always close to the codebase. They’re typically stored in the repository itself, usually in a folder like /docs/adr/, making them accessible to everyone in the team — including reviewers, future contributors, and stakeholders.

They’re also just Markdown. This simplicity ensures they’re easy to read, version, and integrate into your tooling.

Sylius ADRs

Looking for real-world examples? Sylius, an open-source e-commerce platform, uses ADRs to capture and document its architectural decisions. These records are publicly available in their GitHub repository and provide a great reference for how ADRs can be structured and written in practice.

👉 Check out the full list here: https://github.com/Sylius/Sylius/tree/2.1/adr

GitHub ❤️ ADRs

Did you know that GitHub officially encourages the use of ADRs?

Check out GitHub’s own ADR guide which provides templates and best practices for writing and managing ADR documents. This standardization is helping teams across the world stay aligned on their architectural decisions.

Make ADRs Work For You: Pistacy.io

If you're looking for a more structured and collaborative approach to managing your ADRs, Pistacy.io has you covered.

Pistacy is a free Software Architecture Platform for developers and architects, focused on organizing and maintaining software architecture documentation in one place. The platform includes a dedicated ADR management module that supports:

• ✅ Creating and editing ADR documents
• 🔄 Managing document lifecycle using state machines (e.g. from Proposed → Accepted → Obsolete)
• 🔁 Replacing, archiving, or marking ADRs as obsolete
• 🔄 Converting accepted RFCs into ADRs
• 📥 Importing Markdown ADRs directly from your repository using the Pistacy API

This makes ADRs not just useful, but manageable at scale.

Don’t let important decisions fade into git history. Start writing ADRs — and if you want to level up your documentation game, give Pistacy.io a try.