Documenter une architecture — C4 et décisions (ADR)

Les quatre niveaux C4

1. Contexte : le système, ses utilisateurs et les systèmes externes. Lisible par un non-technicien.
2. Conteneurs : applications, bases, files de messages, avec les technologies et protocoles.
3. Composants : découpage interne d'un conteneur.
4. Code : rarement utile à maintenir à la main.

Règle d'or : chaque diagramme a un titre, une légende et des flèches libellées (« lit les commandes via HTTPS/JSON »).

Diagrammes comme code

@startuml
!include <C4/C4_Container>
Person(client, "Client")
System_Boundary(s, "Boutique") {
  Container(web, "Front web", "React")
  Container(api, "API", "Node.js")
  ContainerDb(db, "Base", "PostgreSQL")
}
Rel(client, web, "Utilise", "HTTPS")
Rel(web, api, "Appelle", "JSON/HTTPS")
Rel(api, db, "Lit/écrit", "SQL")
@enduml

Versionnés avec le code, relus en merge request, toujours à jour.

Architecture Decision Records

Un ADR = une décision significative, immuable, numérotée :

# ADR-007 : PostgreSQL pour les données transactionnelles

Statut : accepté — 2026-03-12
## Contexte
Besoin de transactions ACID, d'un volume modéré, compétences internes SQL.
## Décision
PostgreSQL 16 managé, réplication multi-AZ.
## Conséquences
+ écosystème mature, coûts maîtrisés
− scalabilité horizontale en écriture limitée : à réévaluer au-delà de 5 000 tps
## Alternatives étudiées
MongoDB (schéma flexible mais transactions multi-documents plus contraintes), Aurora (coût).

Une décision remplacée n'est pas modifiée : un nouvel ADR la supplante.

Ce qu'il faut documenter en priorité

Contexte, conteneurs, flux (lien avec la matrice de flux), exigences non fonctionnelles (RTO/RPO, volumétrie), décisions structurantes et leurs raisons.