CommunityImagegithub.com

c4-diagrams

Trigger when creating, reviewing, updating, or explaining software architecture diagrams using the C4 model (System Context L1, Container L2, Component L3, Code L4, System Landscape, Dynamic, or Deployment diagrams), especially in Markdown/Mermaid.

What is c4-diagrams?

c4-diagrams is a Claude Code agent skill that trigger when creating, reviewing, updating, or explaining software architecture diagrams using the C4 model (System Context L1, Container L2, Component L3, Code L4, System Landscape, Dynamic, or Deployment diagrams), especially in Markdown/Mermaid.

Works with~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 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

C4 diagrams

Source: the official C4 model at https://c4model.com/. Apply these rules whenever drawing, reviewing, or explaining a C4 diagram. Load the writing skill as well when the output includes prose (ADRs, docs, PR descriptions).

1. Purpose

C4 is a set of "maps of your code" at four zoom levels: Context, Containers, Components, Code. Simon Brown created it, inspired by UML and the 4+1 view model, to replace ad hoc boxes-and-lines diagrams. Typical failures it fixes: no legend, mixed abstractions, unlabelled arrows, missing technology, and vague labels such as "business logic".

C4 is notation-independent and tooling-independent. The abstractions and the rules below matter; the shapes do not.

2. Abstractions

Hierarchy: Person -> Software System -> Container -> Component -> Code. Each level zooms into one element of the level above.

AbstractionDefinitionExamples
PersonA human user, actor, role, or persona of the systemCustomer, Support Agent, Admin
Software SystemHighest level of abstraction; delivers value to users. Typically owned and built by a single team. It is not a product domain, bounded context, tribe, or squadTicketing Platform, Payments System
ContainerAn independently runnable/deployable application or data store inside a software systemServer-side web app, SPA, desktop app, mobile app, serverless function, batch/console app, microservice API, database schema, S3/blob store, CDN, file system, shell script
ComponentA grouping of related functionality behind a well-defined interface, inside a container. Not separately deployable: all components of a container share one process spaceOrderController, PaymentService, EmailSender
CodeClasses, interfaces, functions, or DB tables inside a componentclass OrderValidator, orders table

Container rules (C4 FAQ)

  • A C4 container is not Docker. It is a runnable/deployable application or data store, regardless of packaging.
  • A server-rendered HTML app is 1 container. A server plus an SPA or mobile client is 2 containers communicating over a remote API.
  • JARs, DLLs, assemblies, and modules are not containers. They organize code inside a container.
  • Managed data services (S3, RDS, CDN) are containers inside your system boundary when you own or control the buckets or schemas. They are not external systems.

Component rules

  • A component is not a folder, package, or JAR. It is a functional grouping with an interface.
  • Components are not independently deployable. If it deploys separately, it is a container.

Adapting terminology

Teams may substitute language-idiomatic names (for example Module or Function in functional code) when they define the term explicitly in the diagram or its docs. Do not invent extra abstraction levels unless each is strictly defined.

3. Special modeling patterns

Queues and topics

  • Wrong: one giant "Message Bus" container in the middle with every service attached (hub-and-spoke). It hides who produces and who consumes what.
  • Option 1 (preferred): model each queue or topic as its own container (a message data store). Producers write to it, consumers read or subscribe from it.
  • Option 2: for direct point-to-point coupling, omit the queue box and label the relationship "Publishes order events via Queue orders [AMQP]". Optionally style these lines differently from HTTP calls (explain in the legend).

For example: Order API --"Publishes OrderPlaced to [Kafka]"--> [(orders topic)] --"Reads OrderPlaced from [Kafka]"--> Fulfilment Worker.

Microservices (Conway's Law rule)

  • One team owns the whole software system: model each microservice as a group of containers inside that system's boundary (API container plus its own database schema container, or a single stateless Lambda container).
  • Separate teams own each service: promote each independently owned service to its own Software System, each with its own System Context and Container diagrams. State queue/topic ownership explicitly across system boundaries.

4. Diagram catalog

Core static levels

LevelDiagramRecommendedScopeAudienceShow / omit
1System ContextYes1 software systemTechnical & non-technicalPeople and external systems around the system. Omit low-level technology and protocols
2ContainerYes1 software systemTechnical, opsMajor technology choices and inter-process protocols. Omit clustering, load balancers, failover
3ComponentNo: only when it adds clear value, ideally automated1 containerArchitects, developersComponents inside one container and their interactions
4CodeNo: generate on demand in the IDE1 componentDevelopersUML class diagram or ERD

Supporting diagrams

DiagramRecommendedUse
System LandscapeYes, for organizations and portfoliosEnterprise or department map of all systems and people. A Context diagram without a single focus system
DynamicNo: use sparinglyComplex runtime collaborations. Numbered-collaboration style or UML sequence style
DeploymentYes1 environment (prod, staging, dev). Nested deployment nodes (physical, VM, Docker, Kubernetes, runtime) containing system/container instances, plus infrastructure nodes (DNS, load balancers, firewalls)

Compatibility

  • arc42: Context & Scope -> L1; Building Block level 1 -> L2; Building Block level 2 -> L3; Building Block level 3 -> L4.
  • UML: supplement C4 with UML state, sequence, and ERD diagrams for workflows, state machines, and data models.

Scaling rule

When a diagram gets cluttered, do not cram dozens of boxes into one canvas. Split at the same abstraction level by business area, bounded context, feature, or single-service focus (the focus service plus its inbound and outbound neighbors).

5. Notation rules

Diagram

  • Title states diagram type and scope: Container diagram for Checkout System.
  • Always include a key/legend explaining shapes, colors, borders, line types, arrowheads, and acronyms.
  • Keep strict abstraction purity: never mix abstraction levels (for example, no Component boxes inside an L2 Container diagram), and never put protocols or internal implementation steps ([HTTPS], masked packet, tool_runner) inside an L1 System Context diagram.
  • When comparing competing or historical architectures, label boundary titles explicitly (Option A (Superseded) vs. Option B (Current)) and update all diagrams in the document whenever requirements or assumptions change.

Element

  • Name, explicit element type (Person, Software System, Container, Component, Database, Deployment Node), and a concise responsibility description.
  • Explicit technology on every container, component, and deployment node.

Relationship

  • Unidirectional arrows only. Never <-->. If data flows both ways, show the initiator's direction and describe the response in the label.
  • Specific active verb labels. Never a bare "Uses". Write Submits orders to, Reads seat map from.
  • Protocol/technology on container-to-container relationships: [JSON/HTTPS], [SQL], [gRPC], [AMQP].

6. Mermaid in Markdown

Default to flowchart (flowchart TB or LR), not Mermaid's native C4Context/C4Container. The native C4 syntax is experimental and often fails to render in Markdown viewers. Emit it only if the user explicitly asks and confirms renderer support.

Flowchart conventions:

  • subgraph for the system boundary (Containers/Components) or deployment nodes.
  • [(...)] for databases, data stores, queues, and topics.
  • Quoted HTML labels: "<b>Name</b><br/>«Container: Tech»<br/>Short responsibility".
  • Arrows with quoted labels: A -->|"Action [Protocol]"| B.
  • One classDef per element type, applied consistently.
  • A compact Legend subgraph (unconnected nodes, anchored at the bottom with an invisible bottomNode ~~~ Legend link when Dagre places it at the top) is required whenever colors, cylinder shapes, or multiple line styles are used; place a title as the heading or Title: ... line directly above the code block.
  • Dynamic diagrams: sequenceDiagram, or a flowchart with numbered arrow labels (1. Submits order [JSON/HTTPS]).
  • Deployment diagrams: nested subgraphs in a flowchart.
  • Always quote labels containing parentheses, brackets, or colons.
  • Never put unescaped semicolons (;) inside sequenceDiagram or stateDiagram-v2 labels (Mermaid treats ; as a statement terminator and splits the remaining text into bogus states or parse errors); wrap long Note blocks in sequenceDiagram with <br/> so text never clips at the viewport edge.

Template: L1 System Context

Title: System Context diagram for Ticketing Platform

flowchart TB
    customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
    ticketing["<b>Ticketing Platform</b><br/>«Software System»<br/>Lets customers browse events and buy tickets"]
    payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]
    email["<b>Email Service</b><br/>«Software System, external»<br/>Delivers confirmation emails"]

    customer -->|"Browses events and buys tickets using"| ticketing
    ticketing -->|"Requests card charges from"| payments
    ticketing -->|"Sends confirmation emails using"| email
    email -->|"Delivers confirmation emails to"| customer

    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 customer person
    class ticketing system
    class payments,email external

    subgraph Legend
        direction LR
        l1["Person"]:::person
        l2["Software System (in scope)"]:::system
        l3["Software System (external)"]:::external
    end

Template: L2 Container (with queue container)

Title: Container diagram for Ticketing Platform

flowchart TB
    customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
    payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]

    subgraph boundary["Ticketing Platform [Software System]"]
        spa["<b>Web App</b><br/>«Container: React SPA»<br/>Event browsing and checkout UI"]
        api["<b>Order API</b><br/>«Container: Java, Spring Boot»<br/>Validates and places orders"]
        db[("<b>Orders DB</b><br/>«Container: PostgreSQL»<br/>Stores orders and tickets")]
        topic[("<b>orders topic</b><br/>«Container: Kafka topic»<br/>OrderPlaced events")]
        worker["<b>Fulfilment Worker</b><br/>«Container: Python»<br/>Issues tickets and sends emails"]
    end

    customer -->|"Browses and buys using [HTTPS]"| spa
    spa -->|"Submits orders to [JSON/HTTPS]"| api
    api -->|"Writes orders to [SQL/TCP]"| db
    api -->|"Publishes OrderPlaced to [Kafka]"| topic
    worker -->|"Reads OrderPlaced from [Kafka]"| topic
    worker -->|"Updates ticket status in [SQL/TCP]"| db
    api -->|"Requests card charges from [JSON/HTTPS]"| payments

    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 customer person
    class spa,api,worker container
    class db,topic store
    class payments external

    subgraph Legend
        direction LR
        l1["Person"]:::person
        l2["Container"]:::container
        l3[("Data store / queue / topic")]:::store
        l4["External system"]:::external
    end

Legend note: arrows point from the initiator to the target. The label states the action and [protocol].

Template: Deployment

Title: Deployment diagram for Ticketing Platform (Production)

flowchart TB
    users["<b>Customer browser</b><br/>«Deployment Node: Chrome»"]

    subgraph aws["AWS «Deployment Node: Cloud, us-east-1»"]
        dns["<b>Route 53</b><br/>«Infrastructure Node: DNS»"]
        lb["<b>Load Balancer</b><br/>«Infrastructure Node: ALB»"]
        subgraph eks["EKS «Deployment Node: Kubernetes cluster»"]
            subgraph pod["order-api pod «Deployment Node: Docker, x3»"]
                api["<b>Order API</b><br/>«Container instance: Java, Spring Boot»"]
            end
        end
        subgraph rds["RDS «Deployment Node: PostgreSQL 16»"]
            db[("<b>Orders DB</b><br/>«Container instance: PostgreSQL schema»")]
        end
    end

    users -->|"Resolves hostname using [DNS]"| dns
    users -->|"Sends requests to [HTTPS]"| lb
    lb -->|"Forwards requests to [HTTP]"| api
    api -->|"Reads and writes orders in [SQL/TCP]"| db

Add a Legend subgraph if you use colors or styles beyond defaults.

Template: Dynamic (Sequence)

Title: Dynamic diagram (sequence style) for Order Checkout in Ticketing Platform

sequenceDiagram
    autonumber
    actor customer as Customer
    participant spa as Web App (React SPA)
    participant api as Order API (Spring Boot)
    participant payments as Payment Provider
    participant db as Orders DB (PostgreSQL)
    participant topic as orders topic (Kafka)

    customer->>spa: Clicks "Place Order"
    spa->>api: POST /orders [JSON/HTTPS]
    api->>payments: Charges card [JSON/HTTPS]
    payments-->>api: Payment authorized
    api->>db: Inserts order row [SQL/TCP]
    api->>topic: Publishes OrderPlaced [Kafka]
    api-->>spa: 201 Created (order confirmation)
    spa-->>customer: Shows order receipt

Keep sequenceDiagram participant and message labels free of unquoted slashes, semicolons (;, which Mermaid parses as statement terminators), or raw newlines for maximum Markdown viewer compatibility.

7. Diagramming vs. modelling

Hand-drawn or hand-written diagrams drift across views. For large systems, keep one model (for example Structurizr DSL, or another directed-graph model) as the single source of truth and generate each view from it. For a handful of diagrams in a README, Mermaid by hand is fine.

8. Pre-output checklist

Check every diagram against this list (from https://c4model.com/diagrams/checklist) before presenting it:

  1. Every element has a name, an explicit type, a clear responsibility, and (for containers, components, and deployment nodes) a technology choice.
  2. Every acronym and abbreviation is explained.
  3. Every arrow is unidirectional (-->, never <-->), specifically labelled, and states the protocol for inter-container calls.
  4. Every color, shape, icon, border style, and box size is consistent and explained in a Legend subgraph.
  5. Every diagram has a title stating its type and scope, keeps strict level purity (no protocols/implementation trivia in L1; no mixed Component/Container boxes), and stays in sync with any updated requirements in the surrounding document.

When reviewing someone else's diagram, report each failed item with the element or arrow concerned and a concrete fix.

Individual skills in this repo

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

Related Skills