A Python DSL for C4 model 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.
- 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)
Currently supported and planned backends:
- PlantUML
- local rendering via
plantumlCLI orplantuml.jar - remote rendering via PlantUML server
- local rendering via
- Mermaid — WIP
- Structurizr — WIP
- D2 — WIP
c4-diagrams requires Python 3.10 or higher.
pip install c4-diagrams
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
For details (renderers, diagram types, API), see the documentation.
Contribution guidelines for this project
Repository initiated with fpgmaas/cookiecutter-uv.