Points Clés
- Connaître l'importance de documenter l'architecture
- Comprendre les fondamentaux de doc as code
- Comprendre ce qu'est un modèle C4 et comment en créer un pour votre architecture
L'une des définitions utilisées pour aborder l'architecture logicielle est qu'elle est chargée de définir les parties d'un projet, en plus de la stratégie technologique. Et, comme toute stratégie, il est essentiel qu'il y ait un processus continu d'examen et de mise à jour. C'est pourquoi, ici dans l'équipe Open Source de Zup, nous utilisons le modèle C4.
Avoir une vue sur l'architecture de votre projet est crucial à plusieurs égards, car cela vous aide à répondre à des questions telles que : comment mon système peut-il s'intégrer en interne ou avec d'autres systèmes ? Ou comment garantir la sécurité entre mes applications ? Etc.
L'un des livres d'architecture classiques, Just Enough Software Architecture: A Risk-Driven Approach, mentionne que pour réussir à créer un logiciel, vous devez faire face à trois fronts :
-
Partition : l'art de diviser le problème en petits morceaux afin d'en comprendre le tout.
-
Connaissances : la capacité d'expliquer non seulement ce qui se cache derrière l'architecture, comment elle fonctionne, mais surtout pourquoi elle est utilisée et quelles ont été les décisions nécessaires pour parvenir à ce résultat final.
-
Abstraction : une définition d'architecture logicielle est difficile à définir avec précision, donc l'utilisation d'abstractions aide à comprendre et à résoudre des problèmes complexes.
Un autre ouvrage de référence dans le domaine, intitulé Fundamentals of Software Architecture: An Engineering Approach, indique que l'analyse constante de l'architecture est l'une des exigences attendues par ceux qui travaillent avec l'architecture au sein de la technologie.
Compte tenu des alternatives disponibles sur le marché pour documenter l'architecture logicielle, laquelle pourrait être un bon choix ?
Qu'est-ce que le modèle C4 ?
Documenter l'architecture d'un projet est souvent un processus laborieux qui nécessite du temps, la connaissance des outils et des techniques de création de diagrammes et de documentation.
En pratique, le plus grand défi dans une documentation d'architecture logicielle est d'éviter deux scénarios :
-
Une documentation architecturale très complexe et, par conséquent, tend à devenir confuse et obsolète, perdant sa raison d'être. Autrement dit : une documentation qui prend du temps et devient, en peu de temps, inutilisable.
-
Documentation "mauvaise" avec peu d'informations ou des informations erronées.
Dans les deux cas, le résultat final est qu'ils sont plus un obstacle qu'une aide.
Le modèle C4 est un format de documentation créé par l'ingénieur Simon Brown entre 2006 et 2011 et basé sur les modèles de documents 4+1 et UML.
Il est né pour aider à résoudre le problème de la documentation des architectures défectueuses qui sont difficiles à comprendre et à maintenir. Le modèle C4 apporte une vision plus claire de l'architecture documentée et s'étend sur plusieurs niveaux pertinents pour les différentes personnes impliquées.
Les niveaux du modèle C4
Le modèle C4 est divisé en quatre types de diagrammes, chacun ayant un niveau de détail et un public cible différents. L'idée est que chaque niveau approfondisse les détails et les informations du niveau précédent.
Une meilleure allusion serait avec un Google Maps, que vous pouvez zoomer pour réduire ou agrandir la conception architecturale.
Si sur une carte, par exemple, nous avons continent, pays, état et ville, sur le modèle C4 nous avons :
-
Contexte
-
Récipient
-
Composant
-
Code
Ci-dessous, nous comprendrons mieux chacun de ces niveaux
Niveau 1 : Contexte
C'est la première étape de notre conception. L'idée est de montrer les interactions de manière macro, sans trop de détails, en se concentrant sur les communications et les dépendances entre les systèmes et les utilisateurs qui composent et interagissent avec le logiciel.
C'est un diagramme qui peut (et doit) être consommé par tous les « personnes » du projet, à la fois techniques et commerciaux, et qui interagissent directement ou indirectement avec le système.
Niveau 2 : Container
Le deuxième niveau montre le système plus en détail, décrivant ses conteneurs (à ne pas confondre avec Docker) et comment ils communiquent/interagissent. A ce niveau, l'accent est mis sur l'architecture et les technologies utilisées.
L'idée est de montrer comment le système est (ou sera) construit de manière macro. Un conteneur peut être une application Web, une base de données, un système de fichiers, entre autres. C'est un schéma à consommer par l'équipe technique, qui interagit directement ou indirectement avec le système (développement, professionnels du support, etc.).
Niveau 3 : Composant
En atteignant le troisième niveau, nous franchissons une nouvelle étape dans les détails par rapport au Conteneur, cette fois avec la description des éléments qui composent ces conteneurs. A ce niveau, les informations sur les interactions, les responsabilités et les technologies utilisées apparaissent plus en détail qu'aux niveaux précédents.
Un système aura probablement plus d'un diagramme de composants. C'est un schéma à consommer par l'équipe de développement technique, qui n'est recommandé que dans les cas qui ont généré de la valeur pour l'équipe et il y a un engagement à le maintenir.
Niveau 4 : Code
Au dernier niveau, le modèle C4 montre - au niveau du code - comment chaque composant est implémenté et pour cela il utilise le diagramme de classes UML.
De manière générale, ce niveau de détail n'est pas recommandé et est donc une vue facultative. De plus, il existe actuellement plusieurs outils qui génèrent automatiquement ce type de schéma.
Pourquoi adoptons-nous le modèle C4 pour l'architecture de nos projets ?
Au sein de l'équipe Open Source de Zup, la technologie et l'architecture de chaque projet sont vues de manière stratégique, car nous comprenons qu'avoir une vision claire de ce que nous construisons - à la fois au niveau technique et commercial - contribue à l'évolution du produit et à la création de feuille de route affirmée.
Un bon produit technologique repose sur une bonne architecture et sa documentation respective. Par conséquent, avec le modèle C4, nous avons pu avoir cette vision de manière agile et ajouter de la valeur au projet.
De plus, l'utilisation de ce modèle nous permet de partager les connaissances architecturales du projet avec la communauté de manière simplifiée, mais avec un objectif et une valeur évitant ainsi les problèmes déjà évoqués.
Comment nous utilisons le modèle C4
Au sein de l'équipe, nous préconisons que la documentation architecturale soit proche du code et relève de la responsabilité de tous les membres de l'équipe. Comme le code lui-même, notre modèle C4 se trouve dans un référentiel Git.
Cela garantit tous les avantages d'un versionning. Soit dit en passant, cette pratique de conversion en code est présente, même dans nos autres documentations (également appelées docs as code).
Pour faciliter la visualisation et la maintenance du modèle C4, nous avons adopté le modèle d'un référentiel unique par projet, disponible via S3 et déployé à l'aide de GitHub Actions.
Quel outil utilisons-nous ?
Nous adoptons la conception architecturale en tant que code avec C4-Builder. Un point important est qu'il a différentes manières de configurer et d'exporter. Cependant, parmi les paramètres existants, nous avons choisi de l'utiliser via markdown pour plusieurs raisons :
-
nous l'utilisons déjà pour notre documentation
-
notre équipe de rédacteurs techniques recommande
-
il s'agit de doc as code, conforme à nos objectifs et à nos directives
-
il existe des actions pour GitHub Actions, un outil utilisé dans notre pipeline, qui facilite l'intégration et l'utilisation de l'outil
Comment aligner le modèle C4 avec la documentation ?
En plus de notre documentation technique, nos modèles de modèle C4 sont mis en ligne via un site internet référencé dans un menu de la documentation officielle.
Il est de la responsabilité de l'équipe d'ingénierie, en collaboration avec l'équipe de rédaction technique, de maintenir le modèle C4 à jour à chaque mise à jour dans laquelle il est également nécessaire de mettre à jour la documentation de l'architecture.
Vous pouvez vérifier le modèle C4 de chaque projet :
Modèle C4 : clé de l'évolution d'un projet
Une bonne documentation est au cœur de tout projet Open Source et est généralement la passerelle vers les projets Open Source. Avec l'architecture cela ne fait pas exception, après tout, avoir une stratégie et une carte de celle-ci facilitent l'évolution du projet et de ses possibilités, qui, compte tenu du monde du cloud computing, va vers l'infini et au-delà.
Alors, qu'avez-vous pensé du modèle C4 ? Déjà implémenté ou envisagez-vous d'adopter ? Dites-le nous dans les commentaires!
Les références
-
The C4 model for visualising software architecture - C4 Model
-
arc42 - arc42
-
O modelo C4 de documentação para Arquitetura de Software - InfoQ
-
Visualize a arquitetura do seu sistema com C4 Model - Dev.to
A propos de l'auteur
Otávio Santana est un ingénieur logiciel avec une vaste expérience dans le développement open source, avec plusieurs contributions à JBoss Weld, Hibernate, Apache Commons et à d'autres projets. Axé sur le développement multilingue et les applications haute performance, Otávio a travaillé sur de grands projets dans les domaines de la finance, du gouvernement, des médias sociaux et du commerce électronique. Membre du comité exécutif du JCP et de plusieurs groupes d'experts JSR, il est également un champion Java et a reçu le JCP Outstanding Award et le Duke's Choice Award.