https://github.com/sidorov-as/c4-diagrams
C4 model as Code
https://github.com/sidorov-as/c4-diagrams
diagram diagram-as-code plantuml
Last synced: 5 months ago
JSON representation
C4 model as Code
- Host: GitHub
- URL: https://github.com/sidorov-as/c4-diagrams
- Owner: sidorov-as
- License: mit
- Created: 2025-06-20T07:59:21.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-01-22T17:11:42.000Z (5 months ago)
- Last Synced: 2026-01-23T09:57:34.189Z (5 months ago)
- Topics: diagram, diagram-as-code, plantuml
- Language: Python
- Homepage: https://sidorov-as.github.io/c4-diagrams/
- Size: 2.72 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
A Python DSL for C4 model diagrams.
# c4-diagrams
[](https://pypi.org/project/c4-diagrams/)
[](https://pypi.org/project/c4-diagrams/)
[](https://github.com/sidorov-as/c4-diagrams/actions/workflows/main.yml?query=branch%3Amain)
[](https://qlty.sh/gh/sidorov-as/projects/c4-diagrams)
[](https://qlty.sh/gh/sidorov-as/projects/c4-diagrams)
[](https://img.shields.io/github/license/sidorov-as/c4-diagrams)
**c4-diagrams** is a Python DSL for defining **[C4 model](https://c4model.com/) 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**](https://github.com/plantuml-stdlib/C4-PlantUML)
- local rendering via `plantuml` CLI or `plantuml.jar`
- remote rendering via PlantUML server
- [**Mermaid**](https://mermaid.js.org/syntax/c4.html) — WIP
- [**Structurizr**](https://structurizr.com/) — WIP
## Getting started
**c4-diagrams** requires **Python 3.10** or higher.
```shell
# using pip (pip3)
$ pip install c4-diagrams
# using pipenv
$ pipenv install c4-diagrams
# using poetry
$ poetry add c4-diagrams
# using uv
$ uv add c4-diagrams
```
## Minimal example
A minimal system context diagram defined in Python:
```python
from c4 import Person, Rel, System, SystemContextDiagram
with SystemContextDiagram("Example system context") as diagram:
user = Person(label="User", description="System user")
backend = System(label="Backend API", description="Main application backend")
user >> Rel("Uses HTTP API") >> backend
print(diagram.as_plantuml())
```
Generated PlantUML source
```puml
@startuml
' convert it with additional command line argument -DRELATIVE_INCLUDE="relative/absolute" to use locally
!if %variable_exists("RELATIVE_INCLUDE")
!include %get_variable_value("RELATIVE_INCLUDE")/C4_Context.puml
!else
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
!endif
title Example system context
Person(user_91e7, "User", "System user")
System(backend_api_610a, "Backend API", "Main application backend")
Rel(user_91e7, backend_api_610a, "Uses HTTP API")
@enduml
```
## Examples
| System context diagram | Container Diagram | Component Diagram |
|-----------------------------------------------------------|---------------------------------------------------------|---------------------------------------------------------|
|  |  |  |
## Project Links
- [**PyPI**](https://pypi.org/project/c4-diagrams/)
- [**GitHub**](https://github.com/sidorov-as/c4-diagrams/)
- [**Documentation**](https://sidorov-as.github.io/c4-diagrams/)
- [**Changelog**](https://github.com/sidorov-as/c4-diagrams/tree/main/CHANGELOG.md)
## License
* [MIT LICENSE](https://github.com/sidorov-as/c4-diagrams/blob/main/LICENSE)
## Contribution
[Contribution guidelines for this project](https://github.com/sidorov-as/c4-diagrams/blob/main/CONTRIBUTING.md)
---
Repository initiated with [fpgmaas/cookiecutter-uv](https://github.com/fpgmaas/cookiecutter-uv).