Décisions d'architecture (ADR)

Chaque projet d'architecture est fait de choix : pourquoi PostgreSQL plutôt que MongoDB ? Pourquoi un event bus plutôt qu'un appel synchrone ? Ces décisions sont souvent perdues dans des threads Slack, des pages Confluence oubliées, ou simplement dans la mémoire des développeurs.

Les Architecture Decision Records (ADR) de Siovos Archi vous permettent de documenter, tracer et retrouver chaque décision directement dans le projet concerné.

Timeline des décisions d'architecture

Concept#

Un ADR capture un choix technique avec tout son contexte :

Statuts#

Chaque décision suit un cycle de vie :

• Proposé : la décision est en discussion, pas encore validée
• Accepté : la décision a été validée par l'équipe
• Obsolète : la décision n'est plus pertinente (le contexte a changé)
• Remplacé : la décision a été remplacée par une autre (avec lien vers la nouvelle)

Créer une décision#

Ouvrir le panneau Décisions#

1. Cliquez sur le bouton Décisions dans la barre d'outils du canvas
2. Le panneau latéral s'ouvre

Panneau Décisions vide et lancement d'une nouvelle décision

Depuis un panneau vide, le bouton Créer une décision ouvre l'assistant.

L'assistant de création#

Assistant de création — étape Décision

L'assistant vous guide en 4 étapes :

Étape 1 — Contexte Décrivez le contexte technique et le problème à résoudre. Soyez précis : un bon contexte permet à quelqu'un de comprendre la décision 6 mois plus tard.

Étape 2 — Alternatives Listez les options évaluées. Pour chaque alternative, ajoutez :

• Un titre et une description
• Les avantages
• Les inconvénients

Ajoutez autant d'alternatives que nécessaire. La qualité des avantages/inconvénients est ce qui rend un ADR utile dans le temps.

Étape 3 — Décision Sélectionnez l'alternative retenue et rédigez la justification. Pourquoi cette option ? Quels critères ont pesé dans la balance ?

Étape 4 — Conséquences Documentez les impacts de cette décision :

• Conséquences positives : ce que cette décision améliore
• Conséquences négatives : les compromis acceptés
• Risques : ce qui pourrait mal tourner

Lier à des composants#

Lors de la création (ou après), vous pouvez associer la décision à un ou plusieurs composants du canvas. Cette association permet :

• De voir les décisions liées à un composant dans ses propriétés
• De naviguer depuis une décision vers les composants concernés
• De comprendre pourquoi un composant a été conçu de cette manière

Consulter les décisions#

Panneau latéral#

Le panneau Décisions affiche toutes les décisions du projet, groupées par statut :

• Les décisions En attente en haut (statut Proposé, à valider)
• Les décisions Acceptées (les choix actifs)
• Les décisions Obsolète et Remplacé en bas (historique)

Cliquez sur une décision pour voir son détail complet.

Page Timeline#

Accédez à la vue chronologique via Projet > Décisions. Cette page affiche toutes les décisions dans l'ordre chronologique, avec :

• Le code et le titre
• Le statut avec un badge coloré
• La date de création et de validation
• L'auteur

Tags sur les composants#

Les composants liés à une décision affichent un tag cliquable. Cliquez sur le tag pour :

• Naviguer vers le canvas
• Sélectionner le composant
• Ouvrir le panneau de décisions filtré sur ce composant

Modifier une décision#

Ouvrez le détail d'une décision et modifiez n'importe quel champ. Les modifications courantes :

• Changer le statut : passer de « Proposé » à « Accepté » une fois la décision validée
• Rendre obsolète : marquer comme « Obsolète » quand le contexte a changé
• Remplacer : remplacer par une nouvelle décision (l'ancienne pointe vers la nouvelle)
• Ajouter des alternatives après coup : une option non évaluée initialement
• Mettre à jour les conséquences : si de nouveaux risques ou impacts sont identifiés

Supprimer une décision#

La suppression est définitive. Préférez le statut Obsolète pour garder la traçabilité. La suppression est réservée aux brouillons ou aux erreurs.

Cas d'usage#

Revue d'architecture#

Avant un comité d'architecture, listez les décisions en attente (statut Proposé). Chaque décision est accompagnée de son contexte, ses alternatives et ses conséquences — tout est prêt pour la discussion.

Onboarding technique#

Un nouveau développeur rejoint l'équipe. Au lieu de lui expliquer chaque choix technique de vive voix, dirigez-le vers les ADR du projet. Il comprend le « pourquoi » derrière chaque composant.

Audit de conformité#

Lors d'un audit, les ADR servent de preuve documentée de la gouvernance technique. Chaque décision est tracée avec son auteur, sa date et sa justification.

Migration technologique#

Vous migrez de RabbitMQ à Kafka. Créez un nouvel ADR qui remplace l'ancien choix de RabbitMQ. L'historique est préservé, et la nouvelle décision documente pourquoi le changement est nécessaire.

Bonnes pratiques#

• Un ADR par décision : ne mélangez pas plusieurs choix dans un seul ADR
• Soyez factuel : listez les critères objectifs (performance, coût, complexité)
• Documentez les alternatives rejetées : elles sont aussi importantes que le choix final
• Liez aux composants : un ADR sans composant lié est difficile à retrouver
• Préférez « Obsolète » à la suppression : la traçabilité est la valeur principale des ADR

Prochaines étapes#

• Analyse d'impact pour évaluer les conséquences d'un changement
• Mode Présentation pour présenter vos décisions en comité
• Propriétés sémantiques pour enrichir vos composants avec des métadonnées