Architecture Décision Records¶

Capturer les décisions techniques importantes pour que l'équipe de demain comprenne les choix d'aujourd'hui.

Qu'est-ce qu'un ADR ?¶

Un Architecture Décision Record (ADR) est un court document qui capture une décision architecturale importante, le contexte dans lequel elle a été prise, et ses conséquences.

La valeur d'un ADR n'est pas dans la décision elle-même, mais dans le contexte et les alternatives envisagees. Dans six mois, quand quelqu'un se demandera "pourquoi on a fait ca ?", l'ADR donne la réponse.

Michael Nygard, inventeur du format ADR

"An ADR captures a single décision and its context at a point in time."

Quand écrire un ADR ?¶

Ecrivez un ADR quand :

Vous choisissez une base de données, un framework, un protocole
Vous decidez d'une architecture (microservices vs monolithe, sync vs async)
Vous adoptez une convention qui aura un impact long terme
Vous choisissez de ne pas faire quelque chose d'évident

N'ecrivez pas d'ADR pour :

Des choix de style ou de formatage (c'est pour le linter)
Des décisions réversibles facilement
Des choix triviaux sans alternatives serieuses

Le template standard¶

# ADR-0042 : Utiliser PostgreSQL comme base de donnees principale

**Date** : 2024-03-15
**Statut** : Accepte
**Decideurs** : Alice (lead tech), Bob (ops), Carol (product)

## Contexte

Notre service de commandes doit stocker des donnees transactionnelles
avec des relations complexes entre commandes, produits et utilisateurs.
Le volume attendu est de 50 000 commandes/jour en regime nominal.

## Decision

Nous utilisons PostgreSQL 16 comme base de donnees relationnelle
principale, hebergee sur RDS dans notre infrastructure AWS.

## Alternatives envisagees

| Option       | Avantage                  | Inconvenient                        |
| ------------ | ------------------------- | ----------------------------------- |
| PostgreSQL   | ACID, JSON, maturite      | Scaling horizontal complexe         |
| MySQL        | Familiarite equipe        | Moins de fonctionnalites avancees   |
| MongoDB      | Schema flexible           | Pas de transactions multi-documents |
| DynamoDB     | Scaling AWS natif         | Modele de donnees contraint         |

## Consequences

- **Positives** : Transactions ACID, support JSON natif (JSONB), extensions riches (PostGIS, pg_vector).
- **Negatives** : Scaling horizontal necessite PgBouncer ou Citus.
- **Neutres** : L'equipe devra se former aux specificites PostgreSQL si elle vient de MySQL.

## Liens

- [Benchmark interne](../benchmarks/db-2024-03.md)
- [ADR-0015 : Choisir AWS comme cloud provider](0015-cloud-provider.md)

Les statuts d'un ADR¶

stateDiagram-v2
    [*] --> Propose
    Propose --> Accepte : Validation equipe
    Propose --> Rejete : Refus
    Accepte --> Obsolete : Remplace par nouveau choix
    Accepte --> Supersede : ADR plus recent
    Rejete --> [*]
    Obsolete --> [*]
    Supersede --> [*]

Statut	Signification
`Propose`	En discussion, pas encore valide
`Accepte`	Décision prise et appliquee
`Rejete`	Envisage mais refuse, avec explication
`Obsolete`	La situation a change, la décision ne s'applique plus
`Supersede`	Remplacé par un ADR plus récent (lien vers le successeur)

Organisation dans le dépôt¶

projet/
├── docs/
│   └── decisions/
│       ├── 0001-utiliser-python-fastapi.md
│       ├── 0002-redis-pour-le-cache.md
│       ├── 0003-rejete-graphql.md
│       └── README.md       # Index des ADR
├── src/
└── README.md

Numerotation séquentielle

Prefixez toujours par un numéro a quatre chiffres (0001, 0002...). Ca maintient l'ordre chronologique dans le système de fichiers et facilite les références croisees (voir ADR-0002).

README index des ADR¶

# Decisions d'architecture

| N°   | Titre                              | Statut    | Date       |
| ---- | ---------------------------------- | --------- | ---------- |
| 0001 | Utiliser Python + FastAPI          | Accepte   | 2023-01-10 |
| 0002 | Redis pour le cache de session     | Accepte   | 2023-02-05 |
| 0003 | Rejeter GraphQL (REST suffisant)   | Rejete    | 2023-03-12 |
| 0004 | Migrer vers PostgreSQL 16          | Accepte   | 2024-03-15 |

Exemple concret : changer de stratégie d'authentification¶

# ADR-0007 : Remplacer JWT par des sessions serveur

**Date** : 2024-06-01
**Statut** : Accepte
**Supersede** : ADR-0003 (JWT pour l'authentification)

## Contexte

Depuis l'adoption de JWT (ADR-0003), nous avons rencontre deux problemes :
1. Impossibilite de revoquer un token avant son expiration (securite).
2. Taille des tokens (2 ko) surcharge les headers de chaque requete.

Notre architecture est maintenant exclusivement server-side (pas de SPA),
ce qui rend les sessions serveur plus adaptees.

## Decision

Remplacer JWT par des sessions Redis avec cookie HttpOnly/Secure.
Duree de session : 8h, renouvelee automatiquement si activite.

## Consequences

- **Positives** : Revocation immediate possible, tokens legers (16 octets).
- **Negatives** : Redis devient un point de defaillance ; necessite un cluster Redis.
- **Migration** : Les tokens JWT existants expireront naturellement sur 24h.

Workflow : de la décision à l'ADR¶

sequenceDiagram
    participant Dev as Developpeur
    participant PR as Pull Request
    participant Team as Equipe
    participant Repo as Depot

    Dev->>Dev: Identifie une decision importante
    Dev->>Dev: Redige l'ADR (statut: Propose)
    Dev->>PR: Ouvre une PR avec l'ADR
    PR->>Team: Notification de review
    Team->>PR: Discussion, suggestions
    Team->>PR: Approuve
    PR->>Repo: Merge avec statut: Accepte
    Repo-->>Dev: ADR visible et searchable

Bonnes pratiques de workflow¶

Un ADR par PR : facilite la discussion focalisee
Lien depuis le code : ajoutez // voir ADR-0007 dans le code concerne
Review obligatoire : au moins deux reviewers pour les décisions importantes
Court : un ADR doit tenir en une page. Si c'est plus long, c'est un design doc.

ADR léger (LADR)

Pour les petites équipes ou les décisions mineures, une version allégee :

# Utiliser Zod pour la validation des schemas TypeScript

**Statut** : Accepte | **Date** : 2024-07-01

**Contexte** : Besoin de validation runtime des entrees API avec inference TypeScript.
**Decision** : Zod plutot que Joi (meilleure integration TypeScript) ou Yup (API plus simple).
**Consequences** : +14 ko bundle, validation et types synchronises automatiquement.

Outils pour les ADR¶

Outil	Description	Usage
`adr-tools`	CLI bash pour créer/lister des ADR	`adr new "Titre"`
`log4brains`	Site web généré depuis les ADR markdown	Visualisation graphique
MkDocs	Intégration native des fichiers markdown	Documentation intégrée

# Installation de adr-tools
brew install adr-tools

# Initialiser les ADR dans le projet
adr init docs/decisions

# Creer un nouvel ADR
adr new "Utiliser Kafka pour le bus d'evenements"
# Cree : docs/decisions/0005-utiliser-kafka-pour-le-bus-d-evenements.md

Prochaine étape¶

Les ADR capturent les décisions textuellement. Les diagrammes les rendent visuels et permettent de communiquer l'architecture en un coup d'oeil.

Diagrammes as code →