CommunityImagegithub.com

diagrammes-c4

Déclenché lors de la création, révision, mise à jour ou explication de diagrammes d'architecture logicielle utilisant le modèle C4 (Contexte Système L1, Conteneur L2, Composant L3, Code L4, Vue Système, Diagramme Dynamique ou de Déploiement), notamment en Markdown/Mermaid.

Qu'est-ce que diagrammes-c4 ?

Cette compétence permet de créer, réviser ou expliquer des diagrammes d'architecture avec le modèle C4, une approche structurée en quatre niveaux (Contexte, Conteneurs, Composants, Code). Elle est particulièrement utile pour les développeurs et architectes travaillant avec des agents d'IA comme Claude Code ou Cursor, car elle fournit des règles précises sur les abstractions (Personne, Système Logiciel, Conteneur, Composant, Code), les notations (flèches unidirectionnelles, étiquettes verbeuses, légende obligatoire) et les patrons de modélisation (files d'attente, microservices, déploiement). La compétence privilégie le format `flowchart` Mermaid pour une meilleure compatibilité avec les visionneuses Markdown, et inclut des gabarits prêts à l'emploi (L1, L2, Déploiement, Dynamique) avec conventions de code (sous-graphes, labels HTML entre guillemets, `classDef`). Elle s'applique à toutes les situations où un diagramme C4 est requis : documentation, ADR, revue de code, ou explication d'architecture.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fsodano/writing-skills/tree/HEAD/skills/c4-diagrams

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Diagrammes C4

Source : le modèle C4 officiel sur https://c4model.com/. Appliquez ces règles chaque fois que vous dessinez, révisez ou expliquez un diagramme C4. Chargez également la compétence writing lorsque la sortie inclut du texte (ADR, documentation, descriptions de PR).

1. Objectif

C4 est un ensemble de « cartes de votre code » à quatre niveaux de zoom : Contexte, Conteneurs, Composants, Code. Simon Brown l'a créé, inspiré par UML et le modèle de vue 4+1, pour remplacer les diagrammes ad hoc de boîtes et de lignes. Les échecs typiques qu'il corrige : absence de légende, abstractions mélangées, flèches non étiquetées, technologie manquante, et étiquettes vagues comme « logique métier ».

C4 est indépendant de la notation et des outils. Les abstractions et les règles ci-dessous comptent ; les formes non.

2. Abstractions

Hiérarchie : Personne -> Système Logiciel -> Conteneur -> Composant -> Code. Chaque niveau zoome sur un élément du niveau supérieur.

AbstractionDéfinitionExemples
PersonneUn utilisateur humain, acteur, rôle ou persona du systèmeClient, Agent de support, Administrateur
Système LogicielPlus haut niveau d'abstraction ; apporte de la valeur aux utilisateurs. Généralement possédé et construit par une seule équipe. Ce n'est pas un domaine produit, un contexte borné, une tribu ou une squadPlateforme de billetterie, Système de paiement
ConteneurUne application ou un magasin de données exécutable/déployable de manière indépendante au sein d'un système logicielApplication web côté serveur, SPA, application desktop, application mobile, fonction serverless, application batch/console, API de microservice, schéma de base de données, bucket S3/blob store, CDN, système de fichiers, script shell
ComposantUn regroupement de fonctionnalités connexes derrière une interface bien définie, à l'intérieur d'un conteneur. Non déployable séparément : tous les composants d'un conteneur partagent un espace de processusOrderController, PaymentService, EmailSender
CodeClasses, interfaces, fonctions ou tables de base de données à l'intérieur d'un composantclass OrderValidator, table orders

Règles pour les conteneurs (FAQ C4)

  • Un conteneur C4 n'est pas Docker. C'est une application ou un magasin de données exécutable/déployable, quel que soit l'emballage.
  • Une application HTML rendue côté serveur est 1 conteneur. Un serveur plus un SPA ou un client mobile correspond à 2 conteneurs communiquant via une API distante.
  • Les JAR, DLL, assemblies et modules ne sont pas des conteneurs. Ils organisent le code à l'intérieur d'un conteneur.
  • Les services de données gérés (S3, RDS, CDN) sont des conteneurs à l'intérieur de la limite de votre système lorsque vous possédez ou contrôlez les buckets ou les schémas. Ce ne sont pas des systèmes externes.

Règles pour les composants

  • Un composant n'est pas un dossier, un package ou un JAR. C'est un regroupement fonctionnel avec une interface.
  • Les composants ne sont pas déployables indépendamment. S'il se déploie séparément, c'est un conteneur.

Adaptation de la terminologie

Les équipes peuvent substituer des noms idiomatiques (par exemple Module ou Fonction dans du code fonctionnel) à condition de définir explicitement le terme dans le diagramme ou sa documentation. N'inventez pas de niveaux d'abstraction supplémentaires à moins que chacun soit strictement défini.

3. Patrons de modélisation spéciaux

Files d'attente et sujets

  • Erreur : un seul « Bus de messages » géant au milieu avec tous les services attachés (hub-and-spoke). Cela cache qui produit et qui consomme quoi.
  • Option 1 (préférée) : modéliser chaque file d'attente ou sujet comme son propre conteneur (un magasin de données de messages). Les producteurs y écrivent, les consommateurs y lisent ou s'y abonnent.
  • Option 2 : pour un couplage direct point à point, omettez la boîte de la file et étiquetez la relation "Publie les événements de commande via la file orders [AMQP]". Optionnellement, stylisez ces lignes différemment des appels HTTP (expliquez dans la légende).

Par exemple : API Commande --"Publie OrderPlaced via [Kafka]"--> [(sujet orders)] --"Lit OrderPlaced depuis [Kafka]"--> Worker Exécution.

Microservices (règle de la loi de Conway)

  • Une seule équipe possède l'ensemble du système logiciel : modélisez chaque microservice comme un groupe de conteneurs à l'intérieur de la limite de ce système (conteneur API plus son propre conteneur de schéma de base de données, ou un seul conteneur Lambda sans état).
  • Des équipes distinctes possèdent chaque service : promouvez chaque service possédé indépendamment en son propre Système Logiciel, chacun avec ses propres diagrammes de Contexte Système et Conteneurs. Indiquez explicitement la propriété des files/sujets à travers les limites du système.

4. Catalogue de diagrammes

Niveaux statiques principaux

NiveauDiagrammeRecommandéPérimètrePublicMontrer / omettre
1Contexte SystèmeOui1 système logicielTechnique & non techniquePersonnes et systèmes externes autour du système. Omettre la technologie et les protocoles de bas niveau
2ConteneurOui1 système logicielTechnique, opsChoix technologiques majeurs et protocoles inter-processus. Omettre le clustering, les équilibreurs de charge, le basculement
3ComposantNon : seulement quand il apporte une valeur claire, idéalement automatisé1 conteneurArchitectes, développeursComposants à l'intérieur d'un conteneur et leurs interactions
4CodeNon : générer à la demande dans l'IDE1 composantDéveloppeursDiagramme de classes UML ou ERD

Diagrammes de support

DiagrammeRecommandéUtilisation
Vue SystèmeOui, pour les organisations et portefeuillesCarte d'entreprise ou de département de tous les systèmes et personnes. Un diagramme de Contexte sans système focal unique
DynamiqueNon : à utiliser avec parcimonieCollaborations complexes à l'exécution. Style de collaboration numérotée ou style de séquence UML
DéploiementOui1 environnement (prod, staging, dev). Nœuds de déploiement imbriqués (physique, VM, Docker, Kubernetes, runtime) contenant des instances de système/conteneur, plus des nœuds d'infrastructure (DNS, équilibreurs de charge, pare-feux)

Compatibilité

  • arc42 : Contexte et Périmètre -> L1 ; Niveau de Bloc de Construction 1 -> L2 ; Niveau de Bloc de Construction 2 -> L3 ; Niveau de Bloc de Construction 3 -> L4.
  • UML : complétez C4 avec des diagrammes d'état UML, de séquence et ERD pour les workflows, machines d'état et modèles de données.

Règle de mise à l'échelle

Lorsqu'un diagramme devient encombré, ne forcez pas des dizaines de boîtes sur une seule toile. Divisez au même niveau d'abstraction par domaine métier, contexte borné, fonctionnalité ou focus sur un seul service (le service focal plus ses voisins entrants et sortants).

5. Règles de notation

Diagramme

  • Le titre indique le type de diagramme et le périmètre : Diagramme de conteneurs pour le système de paiement.
  • Incluez toujours une clé/légende expliquant les formes, couleurs, bordures, types de lignes, pointes de flèches et acronymes.
  • Maintenez une pureté d'abstraction stricte : ne mélangez jamais les niveaux d'abstraction (par exemple, pas de boîtes Composant dans un diagramme de Conteneurs L2), et ne mettez jamais de protocoles ou d'étapes d'implémentation interne ([HTTPS], paquet masqué, tool_runner) dans un diagramme de Contexte Système L1.
  • Lorsque vous comparez des architectures concurrentes ou historiques, étiquetez clairement les titres des limites (Option A (Remplacée) vs. Option B (Actuelle)) et mettez à jour tous les diagrammes du document dès que les exigences ou hypothèses changent.

Élément

  • Nom, type d'élément explicite (Personne, Système Logiciel, Conteneur, Composant, Base de données, Nœud de Déploiement), et une description concise des responsabilités.
  • Technologie explicite sur chaque conteneur, composant et nœud de déploiement.

Relation

  • Flèches unidirectionnelles uniquement. Jamais <-->. Si les données circulent dans les deux sens, montrez la direction de l'initiateur et décrivez la réponse dans l'étiquette.
  • Étiquettes de verbe actif spécifique. Jamais un simple « Utilise ». Écrivez Soumet les commandes à, Lit le plan de places depuis.
  • Protocole/technologie sur les relations entre conteneurs : [JSON/HTTPS], [SQL], [gRPC], [AMQP].

6. Mermaid en Markdown

Utilisez par défaut flowchart (flowchart TB ou LR), pas le C4Context/C4Container natif de Mermaid. La syntaxe C4 native est expérimentale et échoue souvent à s'afficher dans les visionneuses Markdown. Ne l'émettez que si l'utilisateur le demande explicitement et confirme le support du rendu.

Conventions pour flowchart :

  • subgraph pour la limite du système (Conteneurs/Composants) ou les nœuds de déploiement.
  • [(...)] pour les bases de données, magasins de données, files d'attente et sujets.
  • Étiquettes HTML entre guillemets : "<b>Nom</b><br/>«Conteneur : Tech»<br/>Responsabilité courte".
  • Flèches avec étiquettes entre guillemets : A -->|"Action [Protocole]"| B.
  • Un classDef par type d'élément, appliqué de manière cohérente.
  • Un sous-graphe Légende compact (nœuds non connectés, ancré en bas avec un lien invisible bottomNode ~~~ Légende lorsque Dagre le place en haut) est requis dès que des couleurs, formes cylindriques ou styles de ligne multiples sont utilisés ; placez un titre comme en-tête ou une ligne Titre : ... directement au-dessus du bloc de code.
  • Diagrammes dynamiques : sequenceDiagram, ou un flowchart avec des étiquettes de flèches numérotées (1. Soumet commande [JSON/HTTPS]).
  • Diagrammes de déploiement : subgraph imbriqués dans un flowchart.
  • Mettez toujours les étiquettes contenant des parenthèses, crochets ou deux-points entre guillemets.
  • Ne mettez jamais de points-virgules non échappés (;) dans les étiquettes sequenceDiagram ou stateDiagram-v2 (Mermaid traite ; comme un terminateur d'instruction et divise le texte restant en états factices ou erreurs d'analyse) ; enveloppez les blocs Note longs dans sequenceDiagram avec <br/> pour que le texte ne soit jamais tronqué au bord de la fenêtre.

Gabarit : L1 Contexte Système

Titre : Diagramme de contexte système pour Plateforme de Billetterie

flowchart TB
    client["<b>Client</b><br/>«Personne»<br/>Achète des billets pour des événements"]
    billetterie["<b>Plateforme de Billetterie</b><br/>«Système Logiciel»<br/>Permet aux clients de parcourir les événements et d'acheter des billets"]
    paiements["<b>Fournisseur de Paiement</b><br/>«Système Logiciel, externe»<br/>Facture les cartes"]
    email["<b>Service d'Email</b><br/>«Système Logiciel, externe»<br/>Distribue les emails de confirmation"]

    client -->|"Parcourt les événements et achète des billets via"| billetterie
    billetterie -->|"Demande des frais de carte à"| paiements
    billetterie -->|"Envoie des emails de confirmation via"| email
    email -->|"Distribue les emails de confirmation à"| client

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class client person
    class billetterie system
    class paiements,email external

    subgraph Légende
        direction LR
        l1["Personne"]:::person
        l2["Système Logiciel (dans le périmètre)"]:::system
        l3["Système Logiciel (externe)"]:::external
    end

Gabarit : L2 Conteneur (avec file d'attente)

Titre : Diagramme de conteneurs pour Plateforme de Billetterie

flowchart TB
    client["<b>Client</b><br/>«Personne»<br/>Achète des billets pour des événements"]
    paiements["<b>Fournisseur de Paiement</b><br/>«Système Logiciel, externe»<br/>Facture les cartes"]

    subgraph limite["Plateforme de Billetterie [Système Logiciel]"]
        spa["<b>Application Web</b><br/>«Conteneur : React SPA»<br/>Navigation et interface de paiement"]
        api["<b>API Commande</b><br/>«Conteneur : Java, Spring Boot»<br/>Valide et place les commandes"]
        bd[("<b>BD Commandes</b><br/>«Conteneur : PostgreSQL»<br/>Stocke les commandes et les billets")]
        sujet[("<b>sujet orders</b><br/>«Conteneur : sujet Kafka»<br/>Événements OrderPlaced")]
        worker["<b>Worker Exécution</b><br/>«Conteneur : Python»<br/>Émet les billets et envoie les emails"]
    end

    client -->|"Parcourt et achète via [HTTPS]"| spa
    spa -->|"Soumet les commandes à [JSON/HTTPS]"| api
    api -->|"Écrit les commandes dans [SQL/TCP]"| bd
    api -->|"Publie OrderPlaced dans [Kafka]"| sujet
    worker -->|"Lit OrderPlaced depuis [Kafka]"| sujet
    worker -->|"Met à jour le statut des billets dans [SQL/TCP]"| bd
    api -->|"Demande des frais de carte à [JSON/HTTPS]"| paiements

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef container fill:#438dd5,stroke:#2e6295,color:#fff
    classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class client person
    class spa,api,worker container
    class bd,sujet store
    class paiements external

    subgraph Légende
        direction LR
        l1["Personne"]:::person
        l2["Conteneur"]:::container
        l3[("Magasin de données / file / sujet")]:::store
        l4["Système externe"]:::external
    end

Note de légende : les flèches pointent de l'initiateur vers la cible. L'étiquette indique l'action et [protocole].

Gabarit : Déploiement

Titre : Diagramme de déploiement pour Plateforme de Billetterie (Production)

flowchart TB
    utilisateurs["<b>Navigateur Client</b><br/>«Nœud de Déploiement : Chrome»"]

    subgraph aws["AWS «Nœud de Déploiement : Cloud, us-east-1»"]
        dns["<b>Route 53</b><br/>«Nœud d'Infrastructure : DNS»"]
        lb["<b>Équilibreur de Charge</b><br/>«Nœud d'Infrastructure : ALB»"]
        subgraph eks["EKS «Nœud de Déploiement : Cluster Kubernetes»"]
            subgraph pod["Pod order-api «Nœud de Déploiement : Docker, x3»"]
                api["<b>API Commande</b><br/>«Instance de Conteneur : Java, Spring Boot»"]
            end
        end
        subgraph rds["RDS «Nœud de Déploiement : PostgreSQL 16»"]
            bd[("<b>BD Commandes</b><br/>«Instance de Conteneur : Schéma PostgreSQL»")]
        end
    end

    utilisateurs -->|"Résout le nom d'hôte via [DNS]"| dns
    utilisateurs -->|"Envoie des requêtes à [HTTPS]"| lb
    lb -->|"Transfère les requêtes à [HTTP]"| api
    api -->|"Lit et écrit les commandes dans [SQL/TCP]"| bd

Ajoutez un sous-graphe Légende si vous utilisez des couleurs ou styles au-delà des valeurs par défaut.

Gabarit : Dynamique (Séquence)

Titre : Diagramme dynamique (style séquence) pour le Paiement de Commande dans la Plateforme de Billetterie

sequenceDiagram
    autonumber
    actor client as Client
    participant spa as Application Web (React SPA)
    participant api as API Commande (Spring Boot)
    participant paiements as Fournisseur de Paiement
    participant bd as BD Commandes (PostgreSQL)
    participant sujet as sujet orders (Kafka)

    client->>spa: Clique « Passer la Commande »
    spa->>api: POST /orders [JSON/HTTPS]
    api->>paiements: Facture la carte [JSON/HTTPS]
    paiements-->>api: Paiement autorisé
    api->>bd: Insère la ligne de commande [SQL/TCP]
    api->>sujet: Publie OrderPlaced [Kafka]
    api-->>spa: 201 Créé (confirmation de commande)
    spa-->>client: Affiche le reçu de commande

Gardez les étiquettes des participants et des messages sequenceDiagram exemptes de barres obliques non échappées, points-virgules (;, que Mermaid analyse comme terminateurs d'instruction) ou sauts de ligne bruts pour une compatibilité maximale avec les visionneuses Markdown.

7. Limitations et cas spéciaux

Diagrammes de déploiement avec infrastructure

Ne modélisez les nœuds d'infrastructure (DNS, équilibreurs de charge, pare-feux) que s'ils sont nécessaires pour expliquer un goulot d'étranglement ou un changement de configuration critique. Par défaut, omettre l'infrastructure dans les diagrammes de Conteneurs.

Diagrammes dynamiques

Utilisez les diagrammes dynamiques avec parcimonie. Les collaborations complexes peuvent souvent être documentées dans du texte ou des ADR. Si vous utilisez un diagramme dynamique, préférez le style de séquence UML ou les flèches numérotées dans un flowchart.

Diagrammes de code

Ne créez pas de diagrammes de code manuellement. Utilisez la génération dans l'IDE (par exemple plugins UML) et faites-les pivoter dans la documentation si nécessaire.

8. Processus de révision

Lors de la révision d'un diagramme C4, vérifiez :

  1. Pureté de l'abstraction – les niveaux sont-ils mélangés ?
  2. Légende – existe-t-elle ? Explique-t-elle les couleurs, formes, lignes ?
  3. Direction des flèches – sont-elles toutes unidirectionnelles ?
  4. Étiquettes – sont-elles spécifiques et actives ? Ont-elles un protocole sur les relations entre conteneurs ?
  5. Technologie – chaque conteneur et chaque nœud de déploiement a-t-il une technologie explicite ?
  6. Limites – les systèmes externes sont-ils clairement séparés de ce qui est dans le périmètre ?
  7. Mise à l'échelle – le diagramme est-il encombré ? Doit-il être divisé ?

9. Pièges courants

  • « Service » comme type d'élément C4 : ne l'utilisez pas. Choisissez Système Logiciel, Conteneur, ou Composant.
  • Utiliser des formes UML (acteur en bâton, classe) dans les diagrammes Mermaid : tenez-vous-en aux conventions flowchart.
  • Oublier d'échapper les guillemets dans Mermaid : utilisez "utilisez des guillemets doubles".
  • Utiliser des points-virgules non échappés dans les diagrammes de séquence : remplacez-les par <br/> ou supprimez-les.
  • Oublier d'étiqueter les files d'attente et les sujets avec leur technologie.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills associés