Decisions d'architecture (ADR)
Tracez vos choix techniques directement dans vos projets avec les Architecture Decision Records integres.
Chaque projet d'architecture est fait de choix : pourquoi PostgreSQL plutot que MongoDB ? Pourquoi un event bus plutot qu'un appel synchrone ? Ces decisions sont souvent perdues dans des threads Slack, des pages Confluence oubliees, ou simplement dans la memoire des developpeurs.
Les Architecture Decision Records (ADR) de Siovos Archi vous permettent de documenter, tracer et retrouver chaque decision directement dans le projet concerne.
Timeline des décisions d'architecture
Concept#
Un ADR capture un choix technique avec tout son contexte :
| Champ | Description |
|---|---|
| Code | Identifiant unique (ex: ADR-014) |
| Titre | Resume du choix en une phrase |
| Contexte | Pourquoi cette decision est necessaire |
| Probleme | Le probleme technique a resoudre |
| Alternatives | Les options evaluees (avec pour/contre) |
| Decision | L'option retenue |
| Justification | Pourquoi cette option plutot qu'une autre |
| Consequences | Impacts positifs, negatifs et risques |
| Composants lies | Les nodes du canvas concernes par cette decision |
Statuts#
Chaque decision suit un cycle de vie :
- Proposed : La decision est en discussion, pas encore validee
- Accepted : La decision a ete validee par l'equipe
- Deprecated : La decision n'est plus pertinente (contexte change)
- Superseded : La decision a ete remplacee par une autre (avec lien vers la nouvelle)
Creer une decision#
Ouvrir le panel Decisions#
- Cliquez sur le bouton Decisions dans la barre d'outils du canvas
- Le panel lateral s'ouvre (il remplace le panel de proprietes)
Wizard de creation#
Wizard de création — étape Décision
Le wizard vous guide en 4 etapes :
Etape 1 — Contexte Decrivez le contexte technique et le probleme a resoudre. Soyez precis : un bon contexte permet a quelqu'un de comprendre la decision 6 mois plus tard.
Etape 2 — Alternatives Listez les options evaluees. Pour chaque alternative, ajoutez :
- Un titre et une description
- Les avantages (pros)
- Les inconvenients (cons)
Ajoutez autant d'alternatives que necessaire. La qualite des pros/cons est ce qui rend un ADR utile dans le temps.
Etape 3 — Decision Selectionnez l'alternative retenue et redigez la justification. Pourquoi cette option ? Quels criteres ont pese dans la balance ?
Etape 4 — Consequences Documentez les impacts de cette decision :
- Consequences positives : ce que cette decision ameliore
- Consequences negatives : les compromis acceptes
- Risques : ce qui pourrait mal tourner
Lier a des composants#
Lors de la creation (ou apres), vous pouvez associer la decision a un ou plusieurs nodes du canvas. Cette association permet :
- De voir les decisions liees a un composant dans ses proprietes
- De naviguer depuis une decision vers les composants concernes
- De comprendre pourquoi un composant a ete concu de cette maniere
Consulter les decisions#
Panel lateral#
Le panel Decisions affiche toutes les decisions du projet, groupees par statut :
- Les decisions Proposed en haut (en attente de validation)
- Les decisions Accepted (les choix actifs)
- Les decisions Deprecated et Superseded en bas (historique)
Cliquez sur une decision pour voir son detail complet.
Page Timeline#
Accedez a la vue chronologique via Projet > Decisions (ou depuis l'URL /projects/[id]/decisions). Cette page affiche toutes les decisions dans l'ordre chronologique, avec :
- Le code et le titre
- Le statut avec un badge colore
- La date de creation et de validation
- L'auteur
Tags sur les nodes#
Les composants lies a une decision affichent un tag cliquable. Cliquez sur le tag pour :
- Naviguer vers le canvas
- Selectionner le node
- Ouvrir le panel de decisions filtre sur ce composant
Modifier une decision#
Ouvrez le detail d'une decision et modifiez n'importe quel champ. Les modifications courantes :
- Changer le statut : passer de "Proposed" a "Accepted" une fois la decision validee
- Deprecier : marquer comme "Deprecated" quand le contexte a change
- Superseder : remplacer par une nouvelle decision (l'ancienne pointe vers la nouvelle)
- Ajouter des alternatives apres coup : une option non evaluee initialement
- Mettre a jour les consequences : si de nouveaux risques ou impacts sont identifies
Supprimer une decision#
La suppression est definitive. Preferez le statut Deprecated pour garder la tracabilite. La suppression est reservee aux brouillons ou erreurs.
Cas d'usage#
Revue d'architecture#
Avant un comite d'architecture, listez les decisions en statut "Proposed". Chaque decision est accompagnee de son contexte, ses alternatives et ses consequences — tout est pret pour la discussion.
Onboarding technique#
Un nouveau developpeur rejoint l'equipe. Au lieu de lui expliquer chaque choix technique de vive voix, dirigez-le vers les ADR du projet. Il comprend le "pourquoi" derriere chaque composant.
Audit de conformite#
Lors d'un audit, les ADR servent de preuve documentee de la gouvernance technique. Chaque decision est tracee avec son auteur, sa date et sa justification.
Migration technologique#
Vous migrez de RabbitMQ a Kafka. Creez un nouvel ADR qui supersede l'ancien choix de RabbitMQ. L'historique est preserve, et la nouvelle decision documente pourquoi le changement est necessaire.
Bonnes pratiques#
Ecrivez pour votre futur vous. Un ADR est utile quand il repond a la question "mais pourquoi on a fait ca ?" 6 mois plus tard. Soignez le contexte et la justification.
- Un ADR par decision : ne melangez pas plusieurs choix dans un seul ADR
- Soyez factuel : listez les criteres objectifs (performance, cout, complexite)
- Documentez les alternatives rejetees : elles sont aussi importantes que le choix final
- Liez aux composants : un ADR sans composant lie est difficile a retrouver
- Preferez Deprecated a Delete : la tracabilite est la valeur principale des ADR
Prochaines etapes#
- Analyse d'impact pour evaluer les consequences d'un changement
- Mode Presentation pour presenter vos decisions en comite
- Proprietes semantiques pour enrichir vos composants avec des metadonnees