Après des années à dessiner des diagrammes d'architecture confus, j'ai découvert le modèle C4. Voici pourquoi il a transformé la façon dont notre équipe communique sur les systèmes.

Introduction au modèle C4 pour l'architecture logicielle

Je me souviens encore de cette session au tableau blanc qui m'a fait tout repenser sur les diagrammes d'architecture. Nous étions en train d'intégrer une nouvelle développeuse, et j'ai passé 45 minutes à dessiner des boîtes et des flèches pour essayer d'expliquer notre plateforme e-commerce. À la fin, elle semblait plus confuse qu'au début. Le diagramme avait tout — microservices, bases de données, files de messages, APIs externes — tout entassé avec une notation incohérente et aucune hiérarchie claire.

Ce soir-là, je suis tombé sur le modèle C4 de Simon Brown, et ça a été un de ces moments "pourquoi n'y ai-je pas pensé ?". L'idée est d'une simplicité trompeuse : au lieu de tout entasser dans un seul diagramme, on crée plusieurs diagrammes à différents niveaux de zoom. Comme Google Maps, on commence avec une vue d'ensemble, puis on zoome progressivement pour voir plus de détails.

Les quatre niveaux du C4

Le "C4" représente quatre niveaux d'abstraction, chacun répondant à différentes questions :

Niveau 1 : Contexte du Système

C'est la vue à 10 000 mètres d'altitude. Tout votre système est une seule boîte, et vous montrez :

Qui utilise votre système (personnes ou rôles)
Quels systèmes externes vous intégrez

C'est tout. Pas de détails internes, pas de choix technologiques, pas de bases de données. Juste "voici notre système, voici qui l'utilise, et voici ce avec quoi il communique."

Quand j'ai dessiné mon premier diagramme de Contexte Système pour notre plateforme, il tenait sur une seule slide. Notre CEO pouvait le comprendre. Ça n'était jamais arrivé avant avec mes diagrammes d'architecture.

Voici ce qui rend ce niveau puissant : il vous force à réfléchir aux frontières. Qu'est-ce qui est à l'intérieur de votre système versus à l'extérieur ? Qu'est-ce que vous possédez versus ce dont vous dépendez ? Ces questions semblent évidentes, mais j'ai vu des équipes peiner à y répondre clairement.

Niveau 2 : Diagramme des Containers

Maintenant on zoome d'un niveau. Un "container" dans la terminologie C4 n'est pas un container Docker — c'est toute unité déployable qui exécute du code ou stocke des données :

Applications web
Applications mobiles
Services backend
Bases de données
Files de messages
Stockage de fichiers

Ce diagramme montre l'architecture technique de haut niveau. On peut voir les choix technologiques majeurs (frontend React, backend Go, base de données PostgreSQL) et comment les données circulent entre eux.

Je trouve ce niveau le plus utile pour :

Planifier l'infrastructure et les déploiements
Discuter des choix technologiques avec l'équipe
Expliquer le système aux nouveaux développeurs backend ou frontend

Une chose que j'ai apprise : faites attention à la granularité ici. Si vous avez 30 microservices, ne montrez pas les 30 comme des containers séparés. Regroupez les services liés ou créez plusieurs diagrammes de Containers pour différentes zones de votre système.

Niveau 3 : Diagramme des Composants

C'est là qu'on zoome dans un seul container. Les composants sont les blocs de construction structurels majeurs à l'intérieur de ce container — pensez services, repositories, contrôleurs ou modules.

Pour notre backend Go, un diagramme de Composants pourrait montrer :

Handlers HTTP
Services de logique métier
Interfaces de repository
Clients d'API externes

Je vais être honnête : je ne crée pas de diagrammes de Composants pour chaque container. Seulement pour les plus complexes que les nouveaux développeurs ont du mal à comprendre. Pour un simple service CRUD, le code lui-même est la documentation.

Niveau 4 : Diagramme du Code

Le niveau le plus profond montre les éléments de code réels — classes, interfaces, fonctions. Simon Brown lui-même dit que ce niveau est optionnel et souvent auto-généré à partir du code.

En pratique, je crée rarement des diagrammes de Code manuellement. Quand je le fais, c'est pour des algorithmes ou des patterns particulièrement complexes qui bénéficient d'une explication visuelle. La plupart du temps, si vous avez besoin de ce niveau de détail, vous devriez lire le code réel.

Pourquoi le C4 a fonctionné pour notre équipe

Avant le C4, notre documentation d'architecture était un désordre. Nous avions :

Des diagrammes Visio de 2019 que personne ne mettait à jour
Des photos de tableaux blancs dans des canaux Slack aléatoires
Des fichiers README avec de l'art ASCII qui expliquait plus ou moins les choses
Des connaissances tribales qui partaient quand les gens quittaient l'entreprise

Le modèle C4 nous a donné un cadre qui fonctionne vraiment. Voici pourquoi :

C'est assez simple pour s'en souvenir

Quatre niveaux. C'est tout. Pas besoin de mémoriser 14 types de diagrammes UML différents ou de se disputer pour savoir si quelque chose devrait être un "composant" ou un "module" au sens UML.

Différents publics, différents diagrammes

Notre CEO regarde le diagramme de Contexte Système. Nos architectes discutent du diagramme de Containers. Nos développeurs travaillent avec les diagrammes de Composants. Chacun obtient le bon niveau de détail pour ses besoins.

Ça reste à jour

Parce que les diagrammes C4 sont relativement simples, ils ne sont pas pénibles à mettre à jour. Quand on ajoute une nouvelle intégration externe, mettre à jour le diagramme de Contexte Système prend 5 minutes. Comparez ça à la mise à jour d'un diagramme UML détaillé avec chaque classe et méthode.

C'est agnostique en termes d'outils

On a commencé avec draw.io, on est passé à Miro pour la collaboration, et maintenant on utilise Archyl pour la création de diagrammes assistée par IA. Le modèle C4 fonctionne avec n'importe quel outil car il s'agit des concepts, pas de la notation.

Les erreurs courantes que j'ai commises (pour que vous ne les fassiez pas)

Erreur 1 : Montrer trop de détails trop tôt

Mon premier diagramme de Containers avait 47 boîtes. Il était précis mais inutile. Maintenant je suis une règle : si votre diagramme ne tient pas sur un écran, vous êtes au mauvais niveau de zoom.

Erreur 2 : Oublier les relations

Un diagramme avec des boîtes mais pas de flèches n'est qu'un inventaire. Les relations — qui appelle qui, quelles données circulent où — sont souvent plus importantes que les boîtes elles-mêmes. Étiquetez vos flèches. Décrivez les protocoles et les formats de données.

Erreur 3 : Ne pas mettre à jour après les changements

Le meilleur diagramme est inutile s'il décrit le système d'il y a deux ans. On a résolu ça en faisant des mises à jour de diagrammes une partie de notre checklist de PR pour les changements architecturaux. Ce n'est pas parfait, mais ça aide.

Erreur 4 : Sur-ingénierer la notation

J'ai passé une semaine à concevoir des icônes personnalisées et des schémas de couleurs pour nos diagrammes C4. Perte de temps totale. Des boîtes simples avec des étiquettes claires fonctionnent très bien. Concentrez-vous sur le contenu, pas sur l'esthétique.

Pour commencer

Si vous êtes nouveau avec le C4, voici ce que je suggérerais :

Commencez avec le Contexte Système. Prenez 30 minutes pour dessiner votre système comme une seule boîte, entourée des utilisateurs et des systèmes externes. Rien que ça a de la valeur.
Ajoutez un diagramme de Containers. Choisissez votre système le plus complexe et décomposez-le en unités déployables. Montrez comment elles communiquent.
Arrêtez-vous là pour l'instant. N'essayez pas de tout documenter d'un coup. Laissez les diagrammes prouver leur valeur avant d'investir plus de temps.
Rendez-le collaboratif. Partagez les diagrammes avec votre équipe. Obtenez des retours. La documentation d'architecture ne devrait pas être une activité solitaire.

Comment nous utilisons le C4 chez Archyl

En construisant Archyl, on mange évidemment notre propre nourriture pour chien. Notre documentation d'architecture utilise le C4 partout :

Le diagramme de Contexte Système montre Archyl se connectant à divers fournisseurs git, services d'IA et systèmes de paiement
Les diagrammes de Containers détaillent le backend Go et le frontend React
Les diagrammes de Composants détaillent le service de découverte et le moteur de rendu des diagrammes

Ce qui est puissant, c'est de lier ces diagrammes à d'autres documentations. Un Architecture Decision Record sur le choix de PostgreSQL plutôt que MongoDB est directement lié au container de base de données dans notre diagramme de Containers. Les flux utilisateurs référencent les composants spécifiques qu'ils traversent.

Cette documentation interconnectée est ce que nous construisons dans Archyl — la capacité de voir votre architecture non pas comme des diagrammes isolés mais comme un graphe de connaissances connecté.

Conclusion

Le modèle C4 n'est pas révolutionnaire dans ses concepts. Les niveaux d'abstraction et la décomposition hiérarchique existent depuis toujours. Ce que Simon Brown a fait brillamment, c'est de packager ces idées dans un cadre simple et mémorable qui est réellement utilisé.

Si votre documentation d'architecture est un fouillis de fichiers Visio obsolètes et de photos de tableaux blancs, essayez le C4. Commencez petit, avec juste un diagramme de Contexte Système. Vous pourriez être surpris de voir combien de clarté un seul diagramme bien pensé peut apporter.

Ceci fait partie de notre série sur la documentation d'architecture. À suivre : Comment l'IA peut automatiquement découvrir votre architecture et Pourquoi la documentation compte plus que vous ne le pensez.

Introduction au modèle C4 pour l'architecture logicielle - Archyl Blog