A Python DSL for C4 model diagrams.

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
• Renderer-agnostic DSL (same code → different outputs)

Rendering backends

Currently supported and planned backends:

• PlantUML

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

• Mermaid — WIP

• Structurizr — WIP
• D2 — WIP

Example

Here’s an example of System Context diagram defined in Python:

# diagram.py
from c4 import *


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:

diagram.png