Le modèle C4 expliqué avec un exemple concret

Le modèle C4 se décrit facilement et s'applique tout aussi facilement de travers. Beaucoup d'équipes finissent avec un diagramme géant qui mélange utilisateurs, microservices, classes Java et boîtes cloud, exactement ce que C4 cherche à éviter. Ce guide parcourt un exemple complet de diagramme modèle C4 : un système inventé, dessiné aux niveaux 1, 2 et 3, pour que vous voyiez ce qui va sur chaque diagramme, qui le lit et où se glissent les erreurs habituelles.

Le modèle C4 en une minute

Le modèle C4, créé par Simon Brown, décrit une architecture logicielle sous forme de diagrammes que l'on peut zoomer. Chaque niveau répond à une question différente, pour un public différent.

Dans C4, un « container » est tout ce qui s'exécute ou stocke des données de façon autonome : une application web, une API, un worker, une base de données, une file de messages ou un topic. Il ne s'agit pas spécifiquement d'un conteneur Docker. C4 définit des abstractions, pas des formes ni des couleurs : la notation vous revient. La référence officielle est c4model.com.

Le système d'exemple : Folio, une librairie en ligne

Pour rester concret, nous utilisons un système inventé. Folio est une librairie en ligne fictive, pas une vraie entreprise, qui vend des livres papier et des e-books.

• Les clients parcourent le catalogue, achètent des livres et téléchargent des e-books.
• L'équipe back-office gère le catalogue, le stock et les prix.
• Folio dépend de trois systèmes externes : un prestataire de paiement, un service d'envoi d'e-mails et le système de fulfilment d'un partenaire logistique.

Niveau 1 : diagramme de contexte (System Context)

Le diagramme de contexte montre Folio comme une seule boîte, avec tout ce qui l'entoure. Aucun détail interne.

• Customer (Person) : parcourt et achète des livres.
• Back-office Staff (Person) : gère catalogue, stock et prix.
• Folio (Software System, dans le périmètre) : permet d'acheter des livres papier et des e-books.
• Payment Provider (Software System, externe) : autorise et capture les paiements par carte.
• Email Service (Software System, externe) : envoie les e-mails de commande et d'expédition.
• Fulfilment System (Software System, externe, appartenant au partenaire logistique) : prépare, emballe et expédie les commandes papier.

Chaque relation porte un libellé qui exprime l'intention :

• Customer → Folio : « Parcourt et achète des livres via »
• Back-office Staff → Folio : « Gère le catalogue et le stock via »
• Folio → Payment Provider : « Encaisse les paiements par carte via »
• Folio → Email Service : « Envoie les e-mails de commande via »
• Folio → Fulfilment System : « Transmet les commandes papier à »

Pour qui : product managers, nouveaux arrivants, relecteurs sécurité, autres équipes. Si un lecteur a besoin de plus qu'un coup d'œil pour comprendre, le diagramme est trop chargé. Protocoles et technologies restent généralement hors de ce niveau.

Niveau 2 : diagramme de conteneurs

Zoomez dans Folio. Les personnes et les systèmes externes restent en place ; Folio devient une boundary autour de ses conteneurs.

Les relations portent désormais l'intention et le protocole :

• Web Storefront → API Application : « Lit le catalogue, passe des commandes [JSON/HTTPS] »
• API Application → Main Database : « Lit et écrit [SQL/TCP] »
• API Application → Payment Provider : « Crée et capture les paiements [HTTPS] »
• API Application → Order Events Queue : « Publie les événements OrderPaid [AMQP] »
• Order Worker → Order Events Queue : « Consomme les événements OrderPaid [AMQP] »
• API Application → E-book Store : « Signe les liens de téléchargement des fichiers e-books [HTTPS] »
• Order Worker → Fulfilment System : « Soumet les commandes papier [JSON/HTTPS] »
• Order Worker → Email Service : « Envoie les e-mails de confirmation [HTTPS] »

Pour qui : ingénieurs, architectes et SRE. Au quotidien, c'est souvent le diagramme C4 le plus utile : celui que vous projetez en design review ou que vous donnez à un nouveau membre de l'équipe. Remarquez ce qui manque : Pods, VPC, load balancers. Leur place est sur un diagramme de déploiement.

Niveau 3 : diagramme de composants

Zoomez dans un seul conteneur, l'API Application. Tous les conteneurs n'ont pas besoin d'un diagramme de composants ; dessinez-le là où l'intérieur mérite une explication.

• Catalogue Controller (contrôleur REST Spring MVC) : endpoints de recherche et de fiche livre.
• Checkout Controller (contrôleur REST Spring MVC) : endpoints panier et paiement.
• Order Service (service Spring) : valide les paniers, crée les commandes, publie les événements.
• Payment Gateway Client (composant Spring) : encapsule l'API du prestataire de paiement.
• Order Repository (Spring Data JPA) : persiste les commandes.
• Catalogue Repository (Spring Data JPA) : lit livres, prix et stock.

Les relations suivent la même règle qu'au niveau 2, par exemple Order Service → Payment Gateway Client « Demande la capture du paiement » et Order Repository → Main Database « [SQL/TCP] ».

Pour qui : les développeurs responsables de ce conteneur. Les diagrammes de composants sont ceux qui vieillissent le plus vite.

Niveau 4, Code : ne le dessinez pas à la main. Générez les diagrammes de classes depuis votre IDE si besoin.

Conseils de notation pour des diagrammes C4 lisibles

• Chaque boîte contient quatre éléments : nom, type d'élément, technologie et responsabilité en une ligne.

API Application
[Container: Java, Spring Boot]
Provides catalogue, ordering and account functionality via a JSON/HTTPS API.

• Libellez chaque relation avec l'intention et, à partir du niveau 2, le protocole. Une flèche qui dit seulement « Utilise » n'apprend rien au lecteur.
• Une direction par flèche, décrite du point de vue de la source.
• Ajoutez une légende qui explique formes, couleurs, styles de trait et acronymes. Un trait pointillé ne veut rien dire tant que vous ne l'avez pas expliqué.
• Titrez chaque diagramme avec son type et son périmètre, par exemple « Diagramme de conteneurs : Folio ».
• Dessinez la boundary du système concerné, pour montrer ce que vous possédez et ce que vous appelez.

Erreurs fréquentes

1. Commencer directement par les composants. Sans vue de contexte ni de conteneurs, le lecteur ne sait pas où vit un composant ni pourquoi il existe.
2. Mélanger les niveaux. Une Person, un Pod et une classe Java sur le même diagramme : aucun n'est bien expliqué.
3. Des flèches sans libellé. Sans intention ni protocole, le lecteur devine, et chacun devine différemment.
4. Dessiner le niveau Code à la main. Il est obsolète le lendemain.
5. De l'infrastructure sur le diagramme de conteneurs. Namespaces, sous-réseaux et types d'instances vont sur un diagramme de déploiement.

Diagrammes complémentaires : déploiement et dynamique

C4 définit aussi des vues complémentaires. Deux sont particulièrement utiles :

• Diagramme de déploiement : projette les conteneurs sur l'infrastructure. Pour Folio, cela pourrait être l'API Application et l'Order Worker en tant que Deployments dans un cluster Kubernetes, PostgreSQL en base managée et l'E-book Store en stockage objet. C'est là que vont les détails Kubernetes et cloud.
• Diagramme dynamique : montre un flux précis en étapes numérotées, par exemple « Un client achète un e-book » : 1) le Storefront envoie le paiement, 2) l'API capture le paiement, 3) l'API publie OrderPaid, 4) le worker envoie l'e-mail avec le lien de téléchargement.

Construire cet exemple de diagramme modèle C4 dans Archboard

Archboard propose un pack C4 Model avec des nodes Person, Software System, Container, Component et Database, ainsi que des boundaries. Ce sont des nodes à part entière avec des ports, pas des formes génériques : les relations se connectent de port à port.

1. Connectez-vous avec Google ou GitHub et créez un diagramme.
2. Niveau 1 : placez deux nodes Person (Customer, Back-office Staff), un node Software System pour Folio et trois nodes External System pour les systèmes de paiement, d'e-mail et de fulfilment. Reliez les ports et libellez chaque lien avec son intention.
3. Niveau 2 : ajoutez une boundary pour Folio, placez des nodes Container pour Web Storefront, Admin Portal, API Application, Order Worker, Order Events Queue et E-book Store, et un node Database pour Main Database. Renseignez nom, technologie et responsabilité, puis libellez les liens avec intention et protocole.
4. Niveau 3 : ajoutez une boundary pour l'API Application et placez-y les nodes Component.
5. Légende et notes : utilisez un bloc Markdown ou une Table des éléments Core pour la légende, et un Frame pour garder chaque niveau dans sa propre zone du canvas infini.
6. La vue de déploiement juste à côté : les vues C4 peuvent cohabiter sur le même canvas que les packs Kubernetes et Cloud. Dessinez un frame Namespace avec des nodes Deployment, Service et Ingress pour l'API Application et l'Order Worker, juste à côté de la vue de conteneurs qu'ils implémentent.

Comme Archboard est un canvas, vous dessinez chaque vue de façon délibérée : vous décidez de ce qui a sa place à chaque niveau, et les nœuds C4 côtoient les nœuds des packs Kubernetes et Cloud sur le même board. La vue de déploiement vit ainsi juste à côté de la vue des conteneurs.

Avec le plan Free, un diagramme contient 15 nœuds de diagramme plus 150 notes, textes, autocollants et sujets de carte mentale, ce qui suffit pour un niveau C4 par diagramme sur un système comme Folio. Pro lève les limites de nodes et de diagrammes si vous voulez tous les niveaux sur un seul canvas. Pour aller plus loin : cas d'usage C4.

Modèle gratuit

L'exemple de vue de conteneurs C4 est un diagramme public que vous pouvez copier dans votre espace de travail avec Utiliser cet exemple. Servez-vous-en pour la disposition des boundaries, puis libellez chaque lien avec son intention et son protocole, comme décrit plus haut.

FAQ

Ai-je besoin des quatre niveaux ? Non. La plupart des équipes tirent l'essentiel de la valeur des diagrammes de contexte et de conteneurs. Ajoutez des diagrammes de composants au cas par cas et ne générez les vues Code que si nécessaire.

Un container C4 est-il un conteneur Docker ? Non. C'est toute unité exécutable ou déployable séparément, y compris les bases de données et les applications monopages. Elle peut tourner dans Docker, ou pas.

Où mettre les détails Kubernetes ? Sur un diagramme de déploiement. Le diagramme de conteneurs reste centré sur les responsabilités et la communication.

Commencez gratuitement — un siège, sans carte bancaire