What is an ADR (Architecture Decision Record)?

In many projects, certain technical decisions end up becoming… mysterious.

• Why was this framework chosen?
• Why does this calculation work this way?
• Why do we use Redis here, but not elsewhere?

The problem is that over time, developers change, Slack discussions disappear, and decisions made several months earlier become difficult to understand.

This is precisely the role of ADRs, standing for Architecture Decision Record.

Architecture Decision Record

An ADR is a very simple document used to keep a record of an important technical decision in a project.

The idea is not to write a massive piece of documentation, quite the opposite:

An ADR is generally short, simple and focused on a single decision.

The goal is mainly to answer an essential question: Why was this decision made?

An ADR often contains:

• context ⇒ explains the problem encountered.
• decision ⇒ describes the choice made.
• consequences ⇒ detail the associated benefits, limitations or trade-offs.

Here's a very simplified example:

# ADR-001 : Utilisation de PostgreSQL

## Context
Le projet nécessite des relations complexes entre les données.

## Decision
Utiliser PostgreSQL comme base principale.

## Consequences
- SQL puissant
- bonnes performances relationnelles
- infrastructure plus lourde qu’une base NoSQL

This type of document might seem trivial… but it becomes extremely valuable over time.

Why set up ADRs?

Without ADRs, many projects end up with "historical" decisions that no one really understands anymore.

And this often creates problems:

• duplication of solutions
• constant second-guessing
• fear of modifying certain parts of the project
• harder onboarding

And above all, it makes the famous "bus factor" even more critical

Setting up ADRs is particularly useful for:

• long-term projects
• growing teams
• complex architectures
• open source projects

The good news is that you can start today, without any tools

Many teams simply store their ADRs in a folder:

/docs/adr

Or directly:

/adr

What matters most is not the format, but starting to document as early as possible.

Because in software architecture, the problem isn't just making good decisions. It's also understanding, several years later, why they were made.