buildzr
Define your C4 software architecture in Python, then build it and explore it in an interactive browser viewer.
No install: edit a model and watch the viewer update.
- Write architecture as code. Describe people, systems, containers and components with Python
with blocks and >> relationships.
- See it in your browser. One command,
buildzr serve, builds your model and serves a viewer that you can zoom, search and link to.
- Stay compatible. buildzr produces standard Structurizr workspaces, so other Structurizr tools can read your model.
Try it now
The quickest way is the in-browser demo: edit a model and run it, with nothing to install.
To run buildzr on your machine, install uv (it finds or fetches a compatible Python) and run:
uvx buildzr serve --example
This serves a bundled example workspace and prints its address. Open it to explore the interactive viewer. You do not need a project, a model file or Node.js. If you prefer a browser tab, press Run Code on the complete Quick Start example: it runs without installing anything.
Use buildzr with your coding agent
Let your coding agent model your architecture for you. The buildzr skill teaches it to write model files, build them, fix build errors, serve the viewer and answer questions about your model.
Install the skill in your project:
npx skills add amirulmenjeni/buildzr
Then ask your agent:
Use buildzr to model the architecture of this repository. Read the code, create or update
the model in workspaces/, add a system context view and a container view, build it, and
tell me how to open it with buildzr serve.
The agent builds the model and tells you how to open the viewer. See Use buildzr with AI agents for the requirements and what the agent can do.
Quick Start
To write a model yourself, start a project. You need:
- Python 3.11 or newer.
- Node.js 18 or newer: when buildzr builds your model, its layout step runs on Node. Check it with
node --version.
- uv. With pip, install with
pip install buildzr instead of uv add buildzr.
Create a project and install buildzr:
uv init hello-buildzr
cd hello-buildzr
uv add buildzr
mkdir workspaces
Save this model as workspaces/hello.py:
from buildzr.dsl import (
Workspace,
SoftwareSystem,
Person,
StyleElements,
SystemContextView,
)
with Workspace('hello') as w:
user = Person('User', description='A user of the system')
system = SoftwareSystem(
'Web Application',
description='Our main web application'
)
user >> "Uses" >> system
StyleElements(
on=[user],
shape='Person'
)
SystemContextView(
software_system_selector=system,
key='system-context',
description='System Context View',
auto_layout='tb'
)
Build and serve it:
uv run buildzr serve
Open http://127.0.0.1:8000/. The viewer shows your model; click a box to see its details. The Quick Start tutorial explains each step.
What you can do
- Model in Python. Nest elements with
with, connect them with >>, group them, and extend an existing workspace. The DSL is type-hinted, so your editor can complete it.
- Draw the views you need. System landscape, system context, container, component, dynamic and deployment views, with styles and cloud-provider themes (AWS, Azure, Google Cloud, Kubernetes, Oracle Cloud).
- Build and serve.
buildzr build writes each workspace as static web pages. buildzr serve builds what changed and serves them on your machine. See Serve your workspaces.
- Explore in the viewer. Expand and collapse boxes, search, filter by type or tag, inspect relationships, switch between light and dark themes, and share a link to one view or element.
- Export. Save Structurizr JSON, and PlantUML, SVG or PNG files (these need Java; see Export).
- Query your model.
buildzr serve also exposes a read-only JSON Model API for scripts and CI jobs.
- Run the examples in your browser. Every example in the documentation has a Run Code button that runs it without installing anything.
Learn more
Found a problem? Check the issue tracker for known issues, and open one if something does not work.
buildzr is released under the MIT License.
