Chapitre 12 : Architecture Decision Records (ADR)

Introduction

Les Architecture Decision Records (ADR) sont des documents courts qui capturent les décisions architecturales importantes, leur contexte et leurs conséquences. Introduits par Michael Nygard en 2011, ils répondent à un problème récurrent : "Pourquoi avons-nous fait ce choix ?"

---

12.1 Pourquoi les ADR ?

12.1.1 Le problème

Dans tout projet, des décisions architecturales sont prises quotidiennement. Sans documentation, ces décisions sont perdues :

Diagramme en cours de génération...

Sans ADR :

• Les décisions sont perdues (connaissances tacites)
• Les choix sont remis en question régulièrement
• Les nouveaux arrivants doivent tout redécouvrir
• Les erreurs passées sont répétées

Avec ADR :

• Traçabilité complète des décisions
• Contexte préservé pour le futur
• Communication facilitée au sein de l'équipe
• Historique des choix architecturaux

12.1.2 Qu'est-ce qu'une décision architecturale ?

Une décision architecturale est un choix qui impacte la structure, les propriétés ou l'évolution du système :

• Choix de framework ou de technologie
• Style architectural (microservices, monolithe)
• Pattern de conception (CQRS, Event Sourcing)
• Standard d'échange (REST, gRPC, GraphQL)
• Infrastructure (cloud, base de données)
• Décision d'architecture impactante

---

12.2 Format ADR (Michael Nygard)

12.2.1 Structure standard

# ADR NNN : Titre de la décision

## Statut
[Proposé | Accepté | Déprécié | Remplacé]

## Contexte
Description du problème, des contraintes, et des options considérées.

## Décision
La décision qui a été prise. "Nous avons décidé de..."

## Conséquences
Ce qui devient plus facile ou plus difficile à faire suite à cette décision.

12.2.2 Exemple complet

# ADR 001 : Utiliser PostgreSQL comme base de données principale

## Statut
Accepté

## Contexte
Notre application SaaS doit stocker des données structurées avec des relations complexes.
Nous considérons les options suivantes :
- PostgreSQL (relationnel, open-source)
- MongoDB (NoSQL, documents)
- MySQL (relationnel, open-source)
- SQL Server (relationnel, propriétaire)

Critères d'évaluation :
- Support des transactions ACID
- Coût (licence)
- Facilité de déploiement
- Performance en lecture/écriture
- Maturité de l'écosystème

## Décision
Nous avons choisi PostgreSQL car :
1. Support complet des transactions ACID
2. Open-source, pas de coût de licence
3. Excellente performance avec les requêtes complexes
4. Écosystème mature (ORM, outils, communauté)
5. Fonctionnalités avancées (JSONB, full-text search, PostGIS)

## Conséquences
**Positives :**
- Transaction ACID garantie pour l'intégrité des données
- Pas de coût de licence (open-source)
- Large communauté et outils matures
- Fonctionnalités avancées disponibles

**Négatives :**
- La réplication nécessite une configuration plus complexe qu'avec MongoDB
- L'indexation doit être soigneusement conçue pour les performances en écriture
- La scalabilité horizontale est plus complexe qu'avec Cassandra

---

12.3 Format Y-Statement

12.3.1 Structure

Le Y-Statement propose un format concis en une phrase :

In the context of [situation],
facing [problem],
we decided for [option]
to achieve [quality goal],
accepting [downside].

12.3.2 Exemple Y-Statement

Version longue :

In the context of our microservices architecture needing a message broker,
facing the need for persistent event storage with replay capability,
we decided for Apache Kafka over RabbitMQ
to achieve durable event sourcing and stream processing,
accepting the operational complexity of managing a Kafka cluster.

Version courte dans le titre :

# ADR 005 : Utiliser Kafka pour l'Event Sourcing

---

12.4 Cycle de vie d'un ADR

12.4.1 Les statuts

Diagramme en cours de génération...

12.4.2 Workflow d'un ADR

Diagramme en cours de génération...

---

12.5 ADR Management

12.5.1 Conventions de nommage

adr/
├── 001-choix-base-de-donnees.md
├── 002-architecture-microservices.md
├── 003-api-gateway-kong.md
├── 004-message-broker-kafka.md
├── 005-cqrs-event-sourcing.md
├── 006-utilisation-graphql.md
├── 007-deploiement-kubernetes.md
└── index.md

12.5.2 Template ADR

# ADR {NUMERO} : {TITRE}

## Statut
{Proposé | Accepté | Déprécié | Remplacé | Rejeté}

## Contexte
{Décrivez le problème, les contraintes, les options, les critères d'évaluation}

## Décision
{La décision retenue, avec les justifications}

## Conséquences
### Positives
- {Impact positif 1}
- {Impact positif 2}

### Négatives
- {Impact négatif 1}
- {Impact négatif 2}

---

12.6 Outils

12.6.1 adr-tools (Node.js)

# Installation
npm install -g adr

# Initialisation
adr init

# Créer un nouvel ADR
adr new "Utiliser PostgreSQL comme base de données"

# Superceder un ADR existant
adr new -s 1 "Utiliser MongoDB comme base de données"

# Liste des ADRs
adr list

# Générer un index
adr generate toc

12.6.2 Log4brains

Log4brains est un outil plus moderne avec UI :

# Installation
npm install -g log4brains

# Initialiser dans le projet
log4brains init

# Créer un ADR
log4brains adr new "Choix de la base de données"

# Démarrer le serveur de documentation
log4brains serve

12.6.3 ADR dans le code

Certains outils placent les ADR directement dans le repository :

project/
├── docs/
│   └── adr/
│       ├── index.md
│       ├── 001-*.md
│       ├── 002-*.md
│       └── ...
├── src/
└── README.md

---

12.7 Quand écrire un ADR ?

12.7.1 Déclencheurs typiques

Diagramme en cours de génération...

12.7.2 Règles empiriques

---

12.8 Exemples concrets d'ADR

ADR 001 : Architecture microservices

# ADR 001 : Migration vers une architecture microservices

## Statut
Accepté

## Contexte
L'application monolithique actuelle atteint ses limites : temps de build > 30min,
déploiement hebdomadaire, conflits fréquents entre équipes. L'équipe passe de 8 à 25 développeurs.

Options :
1. Rester monolithe, améliorer le CI/CD
2. Modular monolith
3. Microservices complets

## Décision
Migration vers les microservices pour permettre aux équipes d'être autonomes.

## Conséquences
Positives : Scalabilité, déploiement indépendant, ownership par équipe
Négatives : Complexité réseau, gestion des transactions distribuées

ADR 002 : Choix du message broker

# ADR 002 : Apache Kafka pour la messagerie événementielle

## Statut
Accepté

## Contexte
Besoins : Publier des événements métier, event sourcing, stream processing.
Options évaluées : Kafka, RabbitMQ, NATS, AWS SQS/SNS.

Critères : Persistance, rejeu d'événements, débit, maturité.

## Décision
Apache Kafka pour sa persistance, son rejeu d'événements et Kafka Streams.

## Conséquences
Positives : Event sourcing natif, débit élevé, écosystème riche
Négatives : Opérations complexes (ZooKeeper, partitionnement)

---

12.9 Anti-patterns des ADR

---

Synthèse

Diagramme en cours de génération...

---

Références

• Michael Nygard — Documenting Architecture Decisions (2011)
• Olaf Zimmermann — Decisions in Software Architecture
• ADR GitHub Organization
• Log4brains
• adr-tools