Qu'est-ce que le modèle C4 ? Guide complet pour les équipes logicielles

Les diagrammes d'architecture logicielle ont un problème de réputation. Ils sont soit trop abstraits pour être utiles, soit trop détaillés pour être maintenables. Vous avez probablement vu les deux : le diagramme à une seule boîte intitulé "Le Système" qui ne vous apprend rien, et le diagramme UML tentaculaire avec 200 classes qui vous dit tout sauf ce que vous avez réellement besoin de savoir.

Le modèle C4, créé par Simon Brown, résout ce problème en empruntant une idée à la cartographie. Les cartes fonctionnent à plusieurs niveaux de zoom. On commence avec une carte du monde pour se repérer, puis on zoome sur un pays, puis une ville, puis une rue. Chaque niveau montre la bonne quantité de détails pour les questions qu'on se pose. Le modèle C4 applique ce même principe à l'architecture logicielle.

Dans ce guide, nous allons parcourir tout ce que vous devez savoir sur le modèle C4 : ce que chaque niveau représente, quand l'utiliser, les pièges courants, et comment les équipes modernes implémentent le C4 en pratique.

Que signifie C4 ?

C4 représente les quatre niveaux d'abstraction que le modèle définit :

1. Context -- La vue d'ensemble. Comment votre système s'inscrit dans le monde.
2. Containers -- Les blocs de construction techniques de haut niveau de votre système.
3. Components -- La structure interne de chaque container.
4. Code -- Les détails d'implémentation réels.

Chaque niveau répond à des questions différentes pour des audiences différentes. Un product manager s'intéresse au Context. Un ingénieur plateforme s'intéresse aux Containers. Un développeur travaillant sur un service spécifique s'intéresse aux Components. Personne n'a vraiment besoin du niveau Code dessiné à la main -- on y reviendra plus tard.

La puissance du C4 ne réside pas dans un seul diagramme. Elle est dans la hiérarchie. Chaque élément à un niveau se décompose en un diagramme au niveau suivant. Une boîte intitulée "Backend API" dans le diagramme de Containers devient son propre diagramme de Components montrant les modules internes. Cela crée une vue navigable et zoomable de votre architecture.

Niveau 1 : Diagramme de Contexte Système

Le diagramme de Contexte Système est le point de départ de tout modèle C4. Il répond à une question : comment votre système s'inscrit-il dans l'environnement global ?

Ce qu'il montre

• Votre système logiciel comme une seule boîte au centre
• Les personnes (acteurs, rôles, personas) qui l'utilisent
• Les systèmes externes avec lesquels il s'intègre
• Les relations entre tous ces éléments

Ce qu'il ne montre pas

• La structure interne de votre système
• Les choix technologiques
• Les bases de données, files de messages ou l'infrastructure
• Les détails de déploiement

Un exemple concret

Imaginez que vous documentez une plateforme e-commerce. Votre diagramme de Contexte Système montrerait :

[Client] --> [Plateforme E-Commerce] : Parcourt les produits, passe des commandes
[Personnel d'entrepôt] --> [Plateforme E-Commerce] : Gère l'inventaire
[Plateforme E-Commerce] --> [Passerelle de paiement (Stripe)] : Traite les paiements
[Plateforme E-Commerce] --> [Transporteur (FedEx API)] : Crée les expéditions
[Plateforme E-Commerce] --> [Service email (SendGrid)] : Envoie les notifications

Cinq utilisateurs et systèmes externes. Une seule boîte pour toute votre plateforme. C'est tout.

Pourquoi ce niveau est important

Le diagramme de Contexte Système force la clarté sur les frontières. Que possédez-vous ? De quoi dépendez-vous ? Qui sont vos utilisateurs ? Ces questions semblent évidentes, mais les équipes ont régulièrement du mal à y répondre de manière cohérente.

C'est aussi le diagramme que vous montrez aux parties prenantes non techniques. Votre CEO peut le regarder et comprendre ce que fait le système, qui l'utilise et de quels services tiers il dépend. Essayez de faire ça avec un diagramme de classes UML.

Conseils pour un bon diagramme de Contexte Système

• Tenez sur une seule page. Si ça ne rentre pas, la frontière de votre système est peut-être mal définie.
• Étiquetez chaque relation avec un groupe verbal : "envoie des emails via", "traite les paiements via", "lit l'inventaire depuis."
• Incluez tous les systèmes externes, même ceux que vous tenez pour acquis (DNS, CDN, monitoring).
• N'incluez pas de détails internes. Résistez à la tentation.

Niveau 2 : Diagramme des Containers

Le diagramme des Containers zoome dans votre système et montre ses blocs de construction techniques de haut niveau. Dans la terminologie C4, un "container" est toute unité séparément déployable ou exécutable -- pas nécessairement un container Docker.

Ce qui compte comme Container

• Une application web (React SPA, app Next.js)
• Une application mobile (app iOS, app Android)
• Un service API backend (API Go, serveur Node.js)
• Une base de données (PostgreSQL, MongoDB, Redis)
• Un message broker (Kafka, RabbitMQ)
• Un système de stockage de fichiers (S3, MinIO)
• Une fonction serverless (AWS Lambda, Cloud Functions)

Chaque container s'exécute dans son propre processus ou possède son propre stockage de données. C'est le facteur distinctif. Deux packages Go déployés ensemble font partie du même container. Deux services Go déployés indépendamment sont des containers séparés.

Un exemple concret

En zoomant dans notre plateforme e-commerce :

[Application Single-Page (React)] --> [API Gateway (Kong)] : Appels API (HTTPS/JSON)
[API Gateway] --> [Service Commandes (Go)] : Route les requêtes
[API Gateway] --> [Service Produits (Go)] : Route les requêtes
[API Gateway] --> [Service Utilisateurs (Go)] : Route les requêtes
[Service Commandes] --> [Base Commandes (PostgreSQL)] : Lit/écrit les commandes
[Service Produits] --> [Base Produits (PostgreSQL)] : Lit/écrit les produits
[Service Utilisateurs] --> [Base Utilisateurs (PostgreSQL)] : Lit/écrit les utilisateurs
[Service Commandes] --> [File de messages (Kafka)] : Publie les événements de commande
[Service Notifications (Go)] --> [File de messages] : Consomme les événements de commande

Maintenant vous pouvez voir les choix technologiques, les patterns de communication et les bases de données. Un architecte peut discuter de la fusion des bases Commandes et Produits. Un ingénieur DevOps peut planifier la topologie de déploiement. Un nouveau développeur peut comprendre où le frontend React s'arrête et où le backend Go commence.

Conseils pour un bon diagramme de Containers

• Incluez la technologie entre parenthèses : "Service Commandes (Go)", "Base de données (PostgreSQL)".
• Montrez le protocole de communication sur les relations : "HTTPS/JSON", "gRPC", "AMQP".
• Si vous avez plus de 15-20 containers, créez plusieurs diagrammes de Containers pour différents sous-systèmes.
• Incluez les bases de données et les files de messages. Ce sont aussi des containers.
• Ne descendez pas en dessous du niveau container ici. Les modules internes appartiennent au diagramme de Components.

Niveau 3 : Diagramme des Components

Le diagramme des Components zoome dans un seul container et montre ses blocs de construction structurels internes. Les composants sont les abstractions majeures au sein d'un container -- pensez packages, modules, services ou couches.

Ce qui compte comme Composant

• Un handler HTTP ou contrôleur
• Un service de logique métier
• Un repository ou couche d'accès aux données
• Un client d'API externe
• Un processeur de tâches de fond
• Un middleware ou intercepteur

Les composants sont des regroupements logiques, pas nécessairement des fichiers individuels. Le composant OrderHandler pourrait être implémenté dans plusieurs fichiers, mais conceptuellement c'est une seule chose : la partie du système qui gère les requêtes HTTP liées aux commandes.

Un exemple concret

En zoomant dans le container Service Commandes :

[Order Handler] --> [Order Service] : Délègue la logique métier
[Order Service] --> [Order Repository] : Persiste les commandes
[Order Service] --> [Payment Client] : Valide le paiement
[Order Service] --> [Inventory Client] : Vérifie la disponibilité du stock
[Order Repository] --> [Base Commandes (PostgreSQL)] : Requêtes SQL
[Payment Client] --> [Passerelle de paiement (Stripe)] : HTTPS/REST
[Inventory Client] --> [Service Produits] : gRPC

Un développeur rejoignant cette équipe peut immédiatement voir comment le Service Commandes est structuré : les requêtes arrivent par le handler, la logique métier vit dans le service, l'accès aux données passe par le repository, et les appels externes passent par des clients dédiés.

Quand créer des diagrammes de Components

Tous les containers n'ont pas besoin d'un diagramme de Components. Créez-en un quand :

• Le container est assez complexe pour qu'un nouveau développeur ait du mal à s'y retrouver
• Il y a des patterns de conception importants (architecture hexagonale, CQRS) que le diagramme peut rendre explicites
• Plusieurs équipes contribuent au même container et ont besoin d'une compréhension partagée de sa structure

Évitez le diagramme de Components quand :

• Le container est simple (un service CRUD avec trois endpoints)
• La structure du code est évidente depuis l'arborescence des dossiers
• Le container est un outil tiers (Redis, Kafka) dont vous ne contrôlez pas les composants internes

Niveau 4 : Diagramme du Code

Le niveau Code montre les détails d'implémentation réels : classes, interfaces, fonctions et leurs relations. C'est essentiellement un diagramme de classes UML ou un diagramme entité-relation.

La vérité sur le niveau 4

Simon Brown lui-même déconseille de créer des diagrammes de Code manuellement. Voici pourquoi :

• Ils changent trop fréquemment. Chaque refactoring les invalide.
• Ils sont coûteux à maintenir. Dessiner des diagrammes de classes à la main est fastidieux.
• Ils dupliquent des informations qui existent déjà dans le code.
• Les IDE modernes peuvent les générer à la demande.

Si vous avez besoin de diagrammes au niveau Code, générez-les à partir de votre code source avec des outils qui supportent votre langage. Ne les dessinez pas à la main.

Quand les diagrammes de Code aident vraiment

Il y a des exceptions :

• Les algorithmes complexes qui bénéficient d'un parcours visuel
• Les design patterns (Strategy, Observer, State Machine) où la structure est la partie intéressante
• Les surfaces d'API publiques où vous voulez documenter les contrats
• Les supports d'entretien ou d'onboarding où vous enseignez des patterns

En pratique, la plupart des équipes utilisent trois niveaux de C4 (Context, Container, Component) et laissent le niveau Code aux vues générées par l'IDE.

Les diagrammes complémentaires

Au-delà des quatre niveaux fondamentaux, Simon Brown définit plusieurs diagrammes complémentaires qui complètent la hiérarchie C4 :

Diagramme de Paysage Système

Un diagramme de Contexte Système dézoomé encore plus loin. Il montre tous les systèmes logiciels d'une entreprise et comment ils se relient les uns aux autres. Utile pour les architectes d'entreprise qui gèrent un portefeuille de systèmes.

Diagramme de Déploiement

Fait correspondre les containers à l'infrastructure. Montre quels containers tournent sur quels serveurs, dans quelles régions cloud, derrière quels load balancers. Essentiel pour les équipes DevOps et plateforme.

Diagramme Dynamique

Montre comment les éléments collaborent à l'exécution pour remplir un cas d'utilisation spécifique. Similaire à un diagramme de séquence UML mais utilisant la notation C4. Utile pour documenter des flux complexes comme "que se passe-t-il quand un utilisateur passe une commande."

Modèle C4 vs. autres approches

C4 vs. UML

UML définit 14 types de diagrammes. La plupart des équipes en utilisent 2-3, et souvent de manière incohérente. Le C4 vous donne 4 niveaux avec des objectifs clairs. C'est plus simple à apprendre, plus simple à utiliser et plus simple à maintenir.

Cela dit, C4 et UML ne sont pas mutuellement exclusifs. Vous pouvez utiliser des diagrammes de classes UML au niveau 4, ou des diagrammes de séquence UML comme diagrammes dynamiques. Le C4 fournit la hiérarchie ; UML fournit des notations spécifiques quand vous en avez besoin.

C4 vs. Arc42

Arc42 est un template de documentation d'architecture. Il couvre bien plus que les diagrammes : exigences de qualité, contraintes, risques, vues de déploiement, et plus encore. Le C4 se concentre spécifiquement sur les diagrammes hiérarchiques. Beaucoup d'équipes utilisent les deux : Arc42 comme structure de documentation et C4 comme approche de diagramme à l'intérieur.

C4 vs. "Un tableau blanc suffit"

Les tableaux blancs sont excellents pour l'exploration et le brainstorming. Ils sont terribles pour la documentation. Les diagrammes au tableau blanc se font effacer, sont mal photographiés et ne sont jamais mis à jour. Le C4 fournit la structure pour transformer les explorations au tableau blanc en documentation durable.

Erreurs courantes lors de l'adoption du C4

Essayer de tout montrer en une fois

Tout l'intérêt du C4 est la divulgation progressive. Si votre diagramme de Containers montre des classes individuelles, vous avez effondré la hiérarchie. Chaque diagramme doit montrer des éléments à un seul niveau de zoom.

Ignorer les relations

Des boîtes sans flèches, c'est un inventaire, pas de l'architecture. Les relations -- qui appelle qui, quel protocole est utilisé, quelles données circulent entre eux -- sont souvent plus précieuses que les boîtes elles-mêmes. Étiquetez toujours vos relations.

En faire une activité solitaire

La documentation d'architecture est un sport d'équipe. Si une seule personne crée et maintient les diagrammes, ils refléteront la compréhension (ou l'incompréhension) de cette seule personne. Revoyez les diagrammes C4 en équipe, idéalement dans le cadre de votre processus de revue d'architecture.

Ne pas lier aux autres documentations

Un diagramme C4 gagne en puissance quand il est connecté à d'autres artefacts. Liez les containers à leurs runbooks de déploiement. Liez les composants à leurs Architecture Decision Records (ADRs). Liez les systèmes externes à leur documentation d'API. Les diagrammes isolés ont moins de valeur que les diagrammes connectés.

Laisser les diagrammes devenir obsolètes

Le plus grand tueur de toute approche de documentation est l'obsolescence. Un diagramme qui décrit l'architecture de l'année dernière est pire que pas de diagramme du tout parce qu'il induit activement en erreur. Intégrez les mises à jour de diagrammes dans votre workflow -- faites-en partie des checklists de PR, des sprint reviews ou des réunions d'architecture.

Comment Archyl implémente le modèle C4

Archyl a été construit autour du modèle C4 comme concept de premier plan. Voici comment chaque niveau correspond aux fonctionnalités de la plateforme :

Contexte Système dans Archyl

Quand vous créez un projet dans Archyl, vous définissez des systèmes et leurs relations avec des acteurs externes. La vue Contexte Système se génère automatiquement à partir de votre modèle -- pas besoin de dessin manuel. Ajoutez un système, ajoutez un acteur externe, dessinez une relation, et le diagramme se met à jour en temps réel.

Diagramme de Containers dans Archyl

Au sein de chaque système, vous définissez des containers avec leurs stacks technologiques. Archyl génère le diagramme de Containers et vous permet de naviguer dans n'importe quel container pour voir ses composants. Les relations entre containers montrent les protocoles de communication et les flux de données.

Diagramme de Components dans Archyl

À l'intérieur de chaque container, vous définissez des composants. Archyl les associe au code réel grâce à sa fonctionnalité Code Elements, qui lie les composants à des fichiers et répertoires spécifiques dans votre repository. Cette connexion entre diagramme et code est ce qui permet la détection de drift.

Découverte par IA

Ce qui distingue Archyl d'un outil de dessin, c'est que vous n'avez pas à construire le modèle à la main. Connectez votre repository, lancez la découverte par IA, et Archyl génère un brouillon de modèle C4 à partir de votre codebase. L'IA identifie les systèmes, containers, composants et relations en analysant la structure de votre code, les fichiers de configuration et les graphes de dépendances.

Vous passez en revue les suggestions, les acceptez ou les modifiez, et vous avez un modèle C4 en quelques minutes au lieu de semaines.

Détection de drift

Une fois votre modèle C4 créé, Archyl vérifie en continu s'il reflète toujours la réalité. Le score de drift vous indique quel pourcentage de votre architecture documentée existe réellement dans la codebase. Si quelqu'un renomme un service ou supprime un composant, le score de drift baisse, et vous savez que votre documentation nécessite une mise à jour.

C'est le point faible que la plupart des outils C4 manquent. Créer des diagrammes, c'est la partie facile. Les garder exacts, c'est la partie difficile. La détection de drift d'Archyl comble ce fossé.

Démarrer avec le C4 : une approche pas à pas

Si votre équipe découvre le modèle C4, voici un parcours d'adoption pratique :

Semaine 1 : Contexte Système

Rassemblez votre équipe pour un atelier d'une heure. Dessinez votre système comme une seule boîte. Identifiez chaque rôle utilisateur et système externe. Dessinez les relations. Vous serez surpris par la quantité de débats que cet exercice simple génère -- et par l'alignement qu'il crée.

Semaine 2 : Diagramme de Containers

Prenez la boîte système de votre diagramme de Contexte et décomposez-la en containers. Quelles sont les unités déployables ? Quelles bases de données existent ? Quels message brokers ou caches sont en jeu ? C'est là que vous rendez les choix technologiques visibles.

Semaines 3-4 : Diagrammes de Components pour les containers clés

Choisissez les deux ou trois containers les plus complexes. Décomposez chacun en composants. C'est là que les nouveaux développeurs passeront le plus de temps, donc priorisez les containers les plus difficiles à comprendre.

En continu : Maintenir et faire évoluer

La création initiale est la partie facile. La discipline de garder les diagrammes à jour est ce qui sépare les équipes qui tirent de la valeur du C4 de celles qui l'abandonnent après un mois. Automatisez ce que vous pouvez. Utilisez des outils qui détectent le drift. Faites des revues de diagrammes partie intégrante de votre workflow de développement.

Pourquoi le C4 fonctionne

Le modèle C4 n'est pas techniquement révolutionnaire. La décomposition hiérarchique et les niveaux d'abstraction existent en informatique depuis les années 1960. Ce que Simon Brown a fait, c'est packager ces idées dans un cadre simple et mémorable avec des règles claires et une notation minimale.

Ça fonctionne parce que :

• C'est facile à apprendre. Quatre niveaux. Des boîtes et des flèches. Pas besoin de certification UML.
• Ça passe à l'échelle. D'un projet de week-end à une plateforme d'entreprise, les mêmes quatre niveaux s'appliquent.
• Ça s'adresse à plusieurs audiences. Dirigeants, architectes et développeurs obtiennent chacun le diagramme qui parle leur langage.
• C'est agnostique en termes d'outils. Vous pouvez utiliser un tableau blanc, un outil de dessin, un format texte, ou une plateforme dédiée comme Archyl.
• Ça se concentre sur les bonnes choses. Structure et relations, pas détails d'implémentation.

Si la documentation d'architecture de votre équipe se résume à des fichiers Visio obsolètes, des photos de tableaux blancs sur Slack et des connaissances tribales, le modèle C4 est le chemin le plus pratique vers quelque chose de mieux.

Prêt à construire votre modèle C4 ? Essayez Archyl gratuitement et générez votre premier diagramme d'architecture à partir du code en quelques minutes. Ou explorez davantage : Découverte d'architecture par IA | Architecture as Code : Définir votre modèle C4 en YAML | Score de drift d'architecture.