Dossiers de Décision Architecturale

Patterns complets pour créer, maintenir et gérer les Dossiers de Décision Architecturale (ADR) qui captent le contexte et la justification derrière les décisions techniques significatives.

Quand Utiliser Cette Compétence

Prendre des décisions architecturales significatives
Documenter les choix technologiques
Enregistrer les compromis de conception
Intégrer les nouveaux membres de l'équipe
Examiner les décisions historiques
Établir des processus de prise de décision

Concepts Fondamentaux

1. Qu'est-ce qu'un ADR ?

Un Dossier de Décision Architecturale capture :

Contexte : Pourquoi nous devions prendre une décision
Décision : Ce que nous avons décidé
Conséquences : Ce qui s'ensuit

2. Quand Rédiger un ADR

Rédiger un ADR	Ne pas faire d'ADR
Adoption d'un nouveau framework	Mises à jour mineures
Choix de technologie de base de données	Corrections de bugs
Patterns de conception d'API	Détails d'implémentation
Architecture de sécurité	Maintenance de routine
Patterns d'intégration	Changements de configuration

3. Cycle de Vie des ADR

Proposé → Accepté → Déprécié → Remplacé
            ↓
         Rejeté

Templates

Template 1 : ADR Standard (Format MADR)

# ADR-0001 : Utiliser PostgreSQL comme Base de Données Primaire

## Statut

Accepté

## Contexte

Nous devons sélectionner une base de données primaire pour notre nouvelle
plateforme e-commerce. Le système doit gérer :

- ~10 000 utilisateurs simultanés
- Catalogue de produits complexe avec catégories hiérarchiques
- Traitement des transactions pour commandes et paiements
- Recherche full-text pour les produits
- Requêtes géospatiales pour le localisateur de magasins

L'équipe a une expérience avec MySQL, PostgreSQL et MongoDB. Nous avons besoin
de conformité ACID pour les transactions financières.

## Facteurs de Décision

- **Obligation : Conformité ACID** pour le traitement des paiements
- **Obligation : Support des requêtes complexes** pour les rapports
- **Souhaitable : Support full-text search** pour réduire la complexité infrastruture
- **Souhaitable : Bon support JSON** pour attributs produits flexibles
- **Familiarité de l'équipe** réduit le temps d'intégration

## Options Considérées

### Option 1 : PostgreSQL

- **Avantages** : Conforme ACID, excellent support JSON (JSONB), recherche
  full-text intégrée, PostGIS pour géospatial, équipe expérimentée
- **Inconvénients** : Configuration de réplication légèrement plus complexe que MySQL

### Option 2 : MySQL

- **Avantages** : Très familier à l'équipe, réplication simple, grande communauté
- **Inconvénients** : Support JSON faible, pas de full-text search intégré (besoin
  Elasticsearch), pas de géospatial sans extensions

### Option 3 : MongoDB

- **Avantages** : Schéma flexible, JSON natif, scaling horizontal
- **Inconvénients** : Pas d'ACID pour transactions multi-documents (à la date de
  décision), expérience limitée de l'équipe, demande discipline de conception

## Décision

Nous utiliserons **PostgreSQL 15** comme base de données primaire.

## Justification

PostgreSQL offre le meilleur équilibre de :

1. **Conformité ACID** essentielle pour les transactions e-commerce
2. **Capacités intégrées** (recherche full-text, JSONB, PostGIS) réduisent la
   complexité infrastruture
3. **Familiarité de l'équipe** avec les bases de données SQL réduit la courbe
   d'apprentissage
4. **Écosystème mature** avec excellent outillage et support communautaire

La légère complexité en réplication est compensée par la réduction des services
additionnels (pas de Elasticsearch séparé nécessaire).

## Conséquences

### Positives

- Base de données unique gère transactions, recherche et requêtes géospatiales
- Complexité opérationnelle réduite (moins de services à gérer)
- Garanties de cohérence forte pour données financières
- L'équipe peut exploiter expertise SQL existante

### Négatives

- Besoin d'apprendre les fonctionnalités spécifiques PostgreSQL (JSONB, syntaxe
  full-text search)
- Limites du scaling vertical peuvent nécessiter replicas de lecture plus tôt
- Certains membres de l'équipe ont besoin de formation PostgreSQL

### Risques

- Recherche full-text peut ne pas scaler aussi bien que moteurs de recherche
  dédiés
- Mitigation : Concevoir pour ajout potentiel Elasticsearch si nécessaire

## Notes d'Implémentation

- Utiliser JSONB pour attributs produits flexibles
- Implémenter connection pooling avec PgBouncer
- Configurer streaming replication pour read replicas
- Utiliser extension pg_trgm pour fuzzy search

## Décisions Associées

- ADR-0002 : Stratégie de Cache (Redis) - complète ce choix
- ADR-0005 : Architecture de Recherche - peut remplacer si Elasticsearch nécessaire

## Références

- [Documentation PostgreSQL JSON](https://www.postgresql.org/docs/current/datatype-json.html)
- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
- Interne : Benchmarks de performance dans `/docs/benchmarks/database-comparison.md`

Template 2 : ADR Léger

# ADR-0012 : Adopter TypeScript pour le Développement Frontend

**Statut** : Accepté
**Date** : 2024-01-15
**Décideurs** : @alice, @bob, @charlie

## Contexte

Notre codebase React a grandi à 50+ composants avec des rapports de bugs
croissants liés à incompatibilités de props et erreurs undefined. PropTypes
fournissent vérification runtime seulement.

## Décision

Adopter TypeScript pour tout nouveau code frontend. Migrer le code existant
progressivement.

## Conséquences

**Bons points** : Détection d'erreurs de type à la compilation, meilleur support
IDE, code auto-documenté.

**Mauvais points** : Courbe d'apprentissage pour l'équipe, ralentissement initial,
augmentation de la complexité build.

**Mitigations** : Sessions de formation TypeScript, permettre adoption graduelle
avec `allowJs: true`.

Template 3 : Format Y-Statement

# ADR-0015 : Sélection d'API Gateway

Dans le contexte de **construire une architecture microservices**,
face au **besoin de gestion API centralisée, authentification et rate limiting**,
nous avons décidé pour **Kong Gateway**
et contre **AWS API Gateway et solution Nginx personnalisée**,
pour atteindre **indépendance fournisseur, extensibilité des plugins et familiarité
de l'équipe avec Lua**,
en acceptant que **nous devions gérer l'infrastructure Kong nous-mêmes**.

Template 4 : ADR pour Dépréciation

# ADR-0020 : Déprécier MongoDB en Faveur de PostgreSQL

## Statut

Accepté (Remplace ADR-0003)

## Contexte

ADR-0003 (2021) choisissait MongoDB pour stockage profils utilisateur du fait des
besoins schéma flexible. Depuis :

- Les transactions multi-documents MongoDB restent problématiques pour notre cas
- Notre schéma s'est stabilisé et change rarement
- Nous avons maintenant expertise PostgreSQL à partir d'autres services
- Maintenir deux bases de données augmente le fardeau opérationnel

## Décision

Déprécier MongoDB et migrer profils utilisateur vers PostgreSQL.

## Plan de Migration

1. **Phase 1** (Semaine 1-2) : Créer schéma PostgreSQL, dual-write activé
2. **Phase 2** (Semaine 3-4) : Remplir données historiques, valider cohérence
3. **Phase 3** (Semaine 5) : Basculer lectures vers PostgreSQL, surveiller
4. **Phase 4** (Semaine 6) : Supprimer écritures MongoDB, décommissionner

## Conséquences

### Positives

- Technologie base de données unique réduit complexité opérationnelle
- Transactions ACID pour données utilisateur
- L'équipe peut concentrer expertise PostgreSQL

### Négatives

- Effort de migration (~4 semaines)
- Risque de problèmes données durant migration
- Perte de flexibilité schéma

## Leçons Apprises

Retours d'expérience ADR-0003 :

- Bénéfices flexibilité schéma surappréciés
- Coût opérationnel de plusieurs bases de données sous-estimé
- Considérer maintenance long-terme dans décisions technologiques

Template 5 : Style Request for Comments (RFC)

# RFC-0025 : Adopter Event Sourcing pour Gestion des Commandes

## Résumé

Proposer adoption pattern event sourcing pour domaine gestion commandes pour
améliorer auditabilité, activer requêtes temporelles et supporter analytics
métier.

## Motivation

Défis actuels :

1. Exigences audit besoin historique complète commande
2. Requêtes « Quel était l'état commande au temps X ? » impossibles
3. Équipe analytics a besoin flux événements pour tableaux de bord temps réel
4. Reconstruction état commande pour support client manuelle

## Conception Détaillée

### Event Store

OrderCreated { orderId, customerId, items[], timestamp } OrderItemAdded { orderId, item, timestamp } OrderItemRemoved { orderId, itemId, timestamp } PaymentReceived { orderId, amount, paymentId, timestamp } OrderShipped { orderId, trackingNumber, timestamp }


### Projections

- **CurrentOrderState** : Vue matérialisée pour requêtes
- **OrderHistory** : Timeline complète pour audit
- **DailyOrderMetrics** : Agrégation analytics

### Technologie

- Event Store : EventStoreDB (dédié, gère projections)
- Alternative considérée : Kafka + service projection personnalisé

## Inconvénients

- Courbe d'apprentissage pour l'équipe
- Complexité augmentée vs CRUD
- Besoin de concevoir événements avec soin (immuables une fois stockés)
- Croissance stockage (événements jamais supprimés)

## Alternatives

1. **Tables audit** : Plus simple mais n'active pas requêtes temporelles
2. **CDC depuis BD existante** : Complexe, change pas le modèle données
3. **Hybride** : Event source seulement pour changements état commande

## Questions Non Résolues

- [ ] Stratégie versioning schéma événement
- [ ] Politique de rétention pour événements
- [ ] Fréquence snapshots pour performance

## Plan d'Implémentation

1. Prototype avec type commande unique (2 semaines)
2. Formation équipe sur event sourcing (1 semaine)
3. Implémentation complète et migration (4 semaines)
4. Surveillance et optimisation (continu)

## Références

- [Event Sourcing par Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
- [Documentation EventStoreDB](https://www.eventstore.com/docs)

Gestion des ADR

Structure des Répertoires

docs/
├── adr/
│   ├── README.md           # Index et directives
│   ├── template.md         # Template ADR de l'équipe
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # Remplace 0003

Index ADR (README.md)

# Dossiers de Décision Architecturale

Ce répertoire contient les Dossiers de Décision Architecturale (ADRs) pour
[Nom Projet].

## Index

| ADR                                   | Titre                                    | Statut     | Date       |
| ------------------------------------- | ---------------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md)        | Utiliser PostgreSQL comme BD Primaire    | Accepté    | 2024-01-10 |
| [0002](0002-caching-strategy.md)      | Stratégie Cache avec Redis               | Accepté    | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB pour Profils Utilisateur          | Déprécié   | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md)     | Déprécier MongoDB                        | Accepté    | 2024-01-15 |

## Créer un Nouvel ADR

1. Copier `template.md` en `NNNN-titre-avec-tirets.md`
2. Remplir le template
3. Soumettre PR pour review
4. Mettre à jour cet index après approbation

## Statut ADR

- **Proposé** : Sous discussion
- **Accepté** : Décision prise, implémentation en cours
- **Déprécié** : N'est plus pertinent
- **Remplacé** : Remplacé par un autre ADR
- **Rejeté** : Considéré mais non adopté

Automatisation (adr-tools)

# Installer adr-tools
brew install adr-tools

# Initialiser répertoire ADR
adr init docs/adr

# Créer nouvel ADR
adr new "Utiliser PostgreSQL comme Base de Données Primaire"

# Remplacer un ADR
adr new -s 3 "Déprécier MongoDB en Faveur de PostgreSQL"

# Générer table des matières
adr generate toc > docs/adr/README.md

# Lier ADRs associés
adr link 2 "Complète" 1 "Est complété par"

Processus de Review

## Checklist Review ADR

### Avant Soumission

- [ ] Contexte explique clairement le problème
- [ ] Toutes options viables considérées
- [ ] Avantages/inconvénients équilibrés et honnêtes
- [ ] Conséquences (positives et négatives) documentées
- [ ] ADRs associés liés

### Lors de la Review

- [ ] Minimum 2 ingénieurs senior ont review
- [ ] Équipes affectées consultées
- [ ] Implications sécurité considérées
- [ ] Implications coûts documentées
- [ ] Réversibilité évaluée

### Après Acceptation

- [ ] Index ADR mis à jour
- [ ] Équipe notifiée
- [ ] Tickets implémentation créés
- [ ] Documentation associée mise à jour

Bonnes Pratiques

À Faire

Rédiger ADRs tôt - Avant début implémentation
Les garder courts - 1-2 pages maximum
Être honnête sur compromis - Inclure vrais inconvénients
Lier décisions associées - Construire graphe décisions
Mettre à jour statut - Déprécier quand remplacé

À Ne Pas Faire

Ne pas modifier ADRs acceptés - Écrire nouveaux pour remplacer
Ne pas sauter contexte - Futurs lecteurs ont besoin background
Ne pas cacher échecs - Décisions rejetées sont précieuses
Ne pas être vague - Décisions spécifiques, conséquences spécifiques
Ne pas oublier implémentation - ADR sans action est perte

architecture-decision-records