Cet article est le résultat de la collaboration entre nos experts humains et nos intelligences artificielles (en savoir +).
Par : Rodolphe LECOCQ, Brieuc HORARD
La documentation d'architecture est essentielle pour assurer la cohérence entre la conception et la réalisation d'un système. Lorsqu'on développe des applications complexes, il est crucial de disposer d'une documentation claire, cohérente et accessible à tous les membres de l'équipe.
Cet article explore comment utiliser les modèles C4 et les Architecture Decision Records (ADR) pour documenter efficacement l'architecture d'un système, en prenant comme exemple la conception d'une application mobile appelée "Chauffator 3000".
Contexte et Problématiques
L'une des problématiques courantes dans la documentation d'architecture est la disparité entre la conception initiale et la réalisation finale. Souvent, ce que l'on observe dans la réalité ne correspond pas exactement aux plans prévus. Cette discordance peut provenir d'une documentation inadéquate ou mal structurée.
Le modèle C4 (Context, Containers, Components, Code) a donc été conçu pour répondre à une problématique courante dans la modélisation des systèmes logiciels : l'absence de représentations standardisées et multi-échelles des architectures. En effet, les diagrammes traditionnels manquent souvent de cohérence, de granularité, ou ne s'adaptent pas aux différents niveaux de détail nécessaires pour bien comprendre un système. Un développeur ou un architecte logiciel peut se retrouver face à des diagrammes trop abstraits pour saisir les détails techniques, ou à l'inverse, trop détaillés pour visualiser l'ensemble du système de manière claire. De plus, chaque équipe ou projet peut utiliser des notations différentes, rendant la communication difficile.
Pour illustrer ces concepts, nous allons utiliser un énoncé simple :
Créer une application mobile appelée chauffator 3000
Cette application permettrait aux utilisateurs de piloter leur chauffage à distance et de surveiller leur consommation électrique grâce à un compteur de nouvelle génération, le Linky++.
Exemples de Schémas de Conception
Avant de présenter le modèle C4, examinons plusieurs exemples de schémas de conception réalisés par différentes personnes de l'équipe :
| Premier exemple : Un schéma intégrant le chauffage, le compteur Linky, une base de données, un backend, et une application mobile pour la visualisation des données. |  |
| Deuxième exemple : Utilisation d'une carte de prototypage (Raspberry Pi), avec des protocoles comme HTTP et Bluetooth, en plus des éléments clés comme le chauffage, le compteur, et l'application mobile. |  |
| Troisième exemple : Une approche plus centrée sur les systèmes externes, incluant des centrales électriques et des protocoles de communication. |  |
| Quatrième exemple : Un niveau de détail plus élevé, décrivant comment l'application est structurée, souvent proche des diagrammes de classes traditionnels. |  |
Analyse des Points Communs
Ces exemples montrent qu'il n'existe pas de représentation standardisée des niveaux de zoom et des éléments inclus. Chaque schéma présente différents niveaux de détail, allant de la vue d'ensemble à des aspects très spécifiques comme les protocoles de communication.
Dans ce contexte, l’objectif principal du modèle C4 est de structurer la documentation des architectures logicielles de manière claire, progressive et standardisée. Chaque niveau de représentation répond à un besoin différent selon les interlocuteurs : les décideurs, les développeurs ou les architectes. C4 assure ainsi une bonne communication et une compréhension partagée du système, quels que soient les niveaux d'abstraction nécessaires.
Présentation du Modèle C4
Le modèle C4 (Context, Container, Component, and Code) propose une approche structurée en quatre niveaux de zoom, permettant de passer de la vue d'ensemble d'un système à ses détails les plus fins, tout en maintenant une cohérence visuelle et sémantique. Cette approche améliore la compréhension et la communication au sein des équipes, tout en offrant une flexibilité pour représenter les systèmes complexes selon le niveau de détail pertinent pour le public cible.
Niveau 1 : Contexte (Context)
Ce premier niveau offre une vue d'ensemble du système, montrant comment il interagit avec son environnement externe, y compris les utilisateurs et les autres systèmes. Il répond à la question "Quel est ce système et comment s’intègre-t-il dans son écosystème ?".
Cette vue est utile pour comprendre la place du système dans un environnement plus large et comment les acteurs externes interagissent avec lui.
Pour reprendre notre exemple sur le Chauffator 3000, cela inclut :
- L'utilisateur
- Le compteur Linky++
- Le chauffage
Niveau 2 : Conteneurs (Containers)
Ce niveau décompose le système en conteneurs logiques et physiques, tels que les applications web, les bases de données, les services et les applications mobiles. Il décrit où et comment le code est déployé et exécuté, ainsi que les responsabilités générales des conteneurs.
Cette vue est utile pour comprendre l’ensemble des briques logicielles nécessaires à la solutions complète. Elle permet également de visualiser la répartition des responsabilités au sein du système.
Pour notre application, cela comprend :
- Un backend qui gère la logique métier, la lecture et la sauvegarde des données.
- Une application mobile permettant aux utilisateurs de piloter le chauffage et de visualiser leur consommation.
- Une base de données pour stocker les informations.
Niveau 3 : Composants (Components)
À ce niveau, chaque conteneur est décomposé en composants logiciels plus fins. Un composant représente un groupe de classes ou de modules qui collaborent pour fournir une fonctionnalité spécifique dans un conteneur.
Cette vue permet de comprendre comment les différentes parties du code interagissent au sein d’un même conteneur.
En zoomant davantage, nous détaillons les composants internes du backend :
- Un contrôleur HTTP pour gérer les requêtes.
- La logique métier centrale qui traite les données et interagit avec le compteur et le chauffage.
- Des interfaces spécifiques pour communiquer avec le compteur Linky et le chauffage, permettant des changements futurs sans impacter le reste du système.
Niveau 4 : Code
Ce dernier niveau, optionnel dans de nombreux cas, zoom sur un composant individuel, montrant les détails du code source réel, comme les classes UML, les méthodes ou les fonctions. Il permet de plonger directement dans la structure du code pour les aspects les plus techniques.
Modèle C4 : niveau 4 - code
Le Modèle C4 : Une solution simple et efficace pour la documentation logicielle
Le modèle C4 est conçu pour être simple à lire et à écrire, ce qui en fait un excellent outil pour la documentation logicielle. Il permet de maintenir facilement la documentation au fil du temps, un défi que beaucoup rencontrent rarement avec succès. Ce modèle est complémentaire à d'autres types de documentation et ne s'oppose pas aux méthodes traditionnelles. En effet, il n’a pas pour vocation de remplacer UML, mais de proposer une alternative plus accessible et adaptée à certains contextes. Là où UML offre une approche riche et très formalisée pour modéliser les systèmes logiciels, C4 privilégie une simplicité et une clarté permettant une compréhension rapide et efficace de l’architecture à différents niveaux d'abstraction. Le choix entre C4 et UML dépend du contexte, des processus internes de l’équipe, et des besoins spécifiques des personnes qui consulteront les diagrammes. Si UML est particulièrement utile pour une documentation exhaustive et détaillée, C4 est idéal lorsque la priorité est une communication claire et rapide, adaptée à différents interlocuteurs, notamment dans des environnements agiles ou orientés vers la collaboration. Il ne s’agit donc pas d’un remplacement mais d’une alternative à évaluer en fonction des objectifs et des contraintes du projet.
De plus, C4 propose une forme standardisée aux dessins fait sur tableaux blanc ou tout autre schéma ad-hoc.
De nombreux logiciels existent, comme Structurizr, PlantUML. Le site officiel de C4 (https://c4model.com/) propose une variété d'outils actualisés pour répondre à tous les besoins.
Introduction aux Architecture Decision Records (ADR)
Les ADR sont des documents qui capturent les décisions importantes prises concernant l'architecture du système et en particulier des systèmes complexes. Chaque décision significative est documentée dans un ADR séparé, ce qui permet de comprendre le contexte et les justifications de chaque choix architectural.
Les 3 pièges à éviter dans le processus de prise de décision
Dans le processus de prise de décisions, il existe trois grands pièges à éviter :
- Le premier piège est de ne prendre aucune décision du tout, laissant les équipes travailler sans directives claires pour construire les systèmes. Bien que l'absence de décision puisse sembler une manière d'éviter les erreurs, elle ne fait pas avancer les choses. Cette approche peut avoir des applications limitées, comme dans le chaos engineering, mais elle est inadaptée lorsqu'il s'agit de concevoir des systèmes structurés .
- Le deuxième piège consiste à prendre des décisions sans fournir de justifications, rendant ces décisions incompréhensibles pour les équipes, même si elles reposent sur de bonnes raisons.
- Enfin, le troisième piège est de documenter les décisions sans rendre cette documentation accessible. Si les équipes ne savent pas où trouver les justifications des décisions prises, cela entraîne des problèmes de compréhension et d'intégration pour les nouveaux arrivants, qui resteront ignorants de l'existence même de cette documentation.
Importance des ADR
- Documentation des décisions : Les ADR permettent de documenter les décisions significatives d’architecture, comme les choix de structure, de sécurité, de résilience, et de dépendances externes, stacks techniques, build, CI/CD, …
- Immutabilité : Une fois une décision prise, elle est documentée et devient immuable. Seul son état peut changer (acceptée, rejetée, dépréciée).
- Lien avec les implémentations : Les ADR doivent être liés aux tickets de développement pour assurer que les décisions prises sont réellement implémentées.
Exemple de Cycle de Vie des ADR
1. En cours de travail : La décision est en cours d'élaboration.
2. Proposable : La décision est prête à être revue.
3. En revue : La décision est en cours de discussion pour être acceptée ou rejetée.
4. Acceptée/Rejetée : La décision est officiellement acceptée ou rejetée.
5. Dépréciée : Une décision acceptée peut être ultérieurement dépréciée si elle n'est plus valable.
Contenu Typique d'un ADR
Les rubriques « essentielles » d’un ADR :
- Titre et identifiant : Chaque ADR doit avoir un titre unique et un identifiant.
- Statut : Indique le statut actuel de la décision.
- Contexte : Explique le problème ou le contexte ayant conduit à la décision.
- Décision : La décision prise
- Conséquences : Les implications de cette décision sur le système.
- Critères : Les critères de choix qui ont guidé la décision (prix, formation, etc.)
- Options : Les différentes options considérées.
- Participants : Les personnes ayant participé à la décision.
- Liens : Liens vers les tickets de développement et autres ADR connexes.
L’utilisation du modèle C4 et des ADR
Le modèle C4 et les ADR sont deux pratiques légères de documentation et complémentaires.
Le C4 fournit une représentation très visuelle et hiérarchisée de l'architecture, tandis que les ADR documentent les décisions, leurs justifications et permettent de donner plus de contextes que des simples diagrammes.
Avantages du C4 et des ADR
- Clarté visuelle et compréhension partagée (Modèle C4)
- Le modèle C4 est simple à lire et à écrire, ce qui facilite la communication au sein de l'équipe en se concentrant sur des hauts niveaux d’abstractions qui permettent d’avoir une vue d’ensemble claire du système ainsi qu’une vue détaillée de ses composants internes. .
- En combinant C4 avec des ADR, l’équipe peut plus facilement comprendre non seulement ce qui a été conçu, mais aussi pourquoi certaines décisions architecturales ont été prises.
- Documentation explicite des décisions (ADR)
- Les ADR permettent de documenter les décisions architecturales importantes au fur et à mesure du projet. Cela comprend les options envisagées, les compromis, les risques, et les raisons des choix finaux.
- Cela complète le modèle C4, car les diagrammes de C4 expliquent comment le système est structuré, tandis que les ADR expliquent pourquoi il a été structuré ainsi.
- Facilitation de la maintenance et de l'évolution
- Coupler le modèle C4 et les ADR permet de mieux gérer les évolutions du projet. Lorsque le système évolue, les équipes peuvent rapidement comprendre les implications des modifications en consultant les ADR et en actualisant les diagrammes C4 pour refléter les changements.
- Cela est particulièrement utile pour les nouvelles équipes ou membres qui rejoignent le projet, car ils peuvent facilement naviguer dans la documentation visuelle (C4) et historique (ADR).
- Complémentarité : Les ADR ajoutent un contexte supplémentaire et détaillé aux diagrammes C4, aidant à comprendre non seulement ce qui a été conçu, mais aussi pourquoi certaines décisions architecturales ont été prises.
Conclusion
L'utilisation combinée du modèle C4 et des ADR offre une approche efficace et standardisée pour documenter l'architecture des systèmes complexes. En structurant la documentation à différents niveaux de zoom et en capturant les décisions clés, ces méthodes améliorent la clarté, la collaboration, la maintenabilité et la compréhension de l'architecture par toutes les parties prenantes.
Pour les équipes de développement, ces pratiques légères mais rigoureuses peuvent transformer la manière dont elles documentent et partagent leur architecture, assurant ainsi un alignement durable entre la conception et la réalisation du système.
Références
AWS - Prescriptive Guide / ADRs :
https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records
ADRs—Explicit Decisions For Better And Faster Software :
https://qeunit.com/blog/adrs-explicit-decisions-for-better-and-faster-software/Joel Parker Henderson - architecture-decision-record :
https://github.com/joelparkerhenderson/architecture-decision-record
outils
Conférence Tech week 2023
Vous souhaitez en savoir plus sur la conférence de Brieuc Horard et Rodolphe Lecocq, présentée durant notre Tech Week 2023 et qui a inspiré cet article ?
Le replay, c'est par ici !
Nos équipes, toujours en quête de savoir, organisent régulièrement des conférences, des ateliers et même des lunchs (parce qu'apprendre en mangeant, c'est quand même plus sympa). Ces moments d'échanges sont enregistrés, retranscrits et confiés à nos IA (merci à ChatZen, notre ChatGPT interne) qui se chargent de les transformer en super articles. Grâce à ce travail d'équipe, nous rendons nos connaissances accessibles et enrichissantes pour tous. Si nos collaborateurs en profitent, autant en faire profiter toute la communauté !
Retour aux articles