c4-diagrams¶

c4-diagrams is a Python DSL for defining C4 model architecture diagrams as code.

The package provides first-class abstractions for C4 entities — people, systems, containers, components, boundaries, and relationships — allowing you to describe software architecture in Python and render it into multiple diagram formats.

Features¶

• Declarative Python DSL for C4 modeling
• First-class C4 entities and relationships
• Multiple rendering backends
• Suitable for documentation, ADRs, and architecture reviews
• Portable core DSL for the common C4 subset, with backend-specific features available through contrib extensions

Rendering backends¶

Currently supported backends:

• PlantUML

  • local rendering via plantuml CLI or plantuml.jar
  • remote rendering via PlantUML server

• Mermaid

  • local rendering via Mermaid CLI
  • Mermaid’s C4 diagram support is currently experimental

• Structurizr - WIP

• D2 - WIP

Example¶

Here’s an example of a system context diagram defined in Python:

# diagram.py
from c4 import (
    EnterpriseBoundary,
    Person,
    System,
    SystemContextDiagram,
    SystemExt,
)
from c4.contrib.plantuml import RelDown, RelRight


with SystemContextDiagram("Acme Shop Platform") as diagram:
    user = Person(
        "Customer",
        "A registered customer who browses products and places orders.",
    )

    with EnterpriseBoundary("Acme Corp"):
        web_app = System(
            "Web Application",
            "Customer-facing website for browsing products and placing orders.",
        )

        api_backend = System(
            "Backend API",
            "Handles authentication, order processing, and business logic.",
        )

    email_provider = SystemExt(
        "Email Provider",
        "Delivers transactional emails.",
    )

    user >> RelRight("Uses") >> web_app
    web_app >> RelRight("Calls API") >> api_backend
    api_backend >> RelDown("Sends emails via") >> email_provider

To export the diagram to a rendered artifact, run:

c4 export diagram.py > diagram.png

This generates the diagram below: