Architecture Decision Records (ADRs)
Les ADRs capturent les décisions structurantes prises sur la plateforme Nex : contexte, options envisagées, décision retenue, conséquences. Format inspiré de Michael Nygard.
Pourquoi des ADRs
- Onboarding — un nouveau dev comprend pourquoi les choix actuels en quelques lectures.
- Audit — un auditeur bancaire ou cybersec voit la gouvernance architecturale, pas seulement le code.
- Mémoire d’équipe — éviter de redébattre une décision déjà prise et oubliée.
- Évolution maîtrisée — un ADR
supersededdocumente explicitement le changement.
Table de référence
| # | Titre | Status | Date | Tickets |
|---|---|---|---|---|
| 0001 | NestJS en Clean Architecture pour tous les services | Accepted | 2026-02 | — |
| 0002 | Firebase comme provider de custom tokens | Accepted | 2026-02 | — |
| 0003 | Monorepo Turborepo + pnpm, mobile en npm hors workspace | Accepted | 2026-02 | — |
| 0004 | Modèle multi-utilisateurs marchand via merchant_members | Accepted | 2026-04 | NEX-500 |
| 0005 | Card number marchand 8 caractères avec préfixe env | Accepted | 2026-04 | NEX-500 |
| 0006 | Intent comme représentation canonique d’une transaction | Accepted | 2026-04 | NEX-438 |
| 0007 | Pas de prefetched policy — trust boundary risk-engine | Accepted | 2026-05-09 | NEX-438 |
| 0008 | Doppler + External Secrets Operator pour les secrets | Accepted | 2026-03 | — |
| 0009 | AWS EKS comme runtime staging et production | Accepted | 2026-03 | — |
| 0010 | Cloudflare edge, WAF, CDN et DNS | Accepted | 2026-03 | — |
| 0011 | VitePress pour la documentation technique | Accepted | 2026-04 | — |
| 0012 | Bus async BullMQ pour les notifications de transaction | Accepted | 2026-05-09 | NEX-438 |
| 0013 | QR code AES-256-GCM avec device key par appareil | Accepted | 2026-03 | — |
| 0014 | Schémas PostgreSQL séparés par microservice | Accepted | 2026-02 | — |
| 0015 | Architecture transaction-flow config-driven | Accepted | 2026-04 | NEX-438 |
| 0042 | Convention master_agent / simple_agent lowercase | Accepted | 2026-05-01 | NEX-435 |
Conventions de numérotation
- Numérotation séquentielle à partir de 0001.
- Les numéros déjà attribués (ex : 0042) restent stables — pas de renumérotation.
- Une décision rendue obsolète passe en
supersededmais n’est pas supprimée — elle référence l’ADR qui la remplace.
Format d’un ADR
markdown
---
title: "ADR-NNNN — Titre court de la décision"
audience: [dev, sec, audit-bank]
owner: "@architecture-team"
status: accepted | proposed | superseded
last_review: YYYY-MM-DD
related_tickets: [NEX-XXX] # optionnel
---
# ADR-NNNN — Titre court
**Status :** Accepted | Proposed | Superseded
**Date :** YYYY-MM-DD
**Deciders :** équipe / personne
**Tickets :** NEX-XXX
## Contexte
Quel problème, quelles contraintes, quels acteurs.
## Décision
Ce qui a été retenu.
## Conséquences
### Positives
### Négatives / risques
## Alternatives écartées
Les options non retenues et pourquoi.
## Suivi
Tickets, MR, autres ADRs liés.Quand écrire un ADR
Écrire un ADR quand :
- la décision touche plus d’un service ou plus d’une équipe ;
- la décision est difficile à inverser une fois prise ;
- la décision implique un trade-off non évident ;
- un nouvel arrivant aurait du mal à comprendre le « pourquoi » sans contexte.
Ne pas écrire d’ADR pour :
- un choix de nommage local ;
- une convention de code triviale ;
- une décision déjà capturée dans une autre page d’architecture.