buildzr

Define your C4 software architecture in Python, then build it and explore it in an interactive browser viewer.

• 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

With uv installed (it finds or fetches a compatible Python), 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.

Until 1.0.0 final is out, add a pre-release flag: uvx --prerelease allow buildzr serve --example, uv add --prerelease allow buildzr, or pip install --pre buildzr.

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.10 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 (use the pre-release flag from the note above until 1.0.0 final is out):

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

• Documentation: the user guides, the command reference and the API reference.
• Roadmap: what is planned and what is done.
• Contributing: how to report an issue or send a change.

buildzr is approaching 1.0. Read the issue tracker for known problems, and open an issue if something does not work.

buildzr is released under the MIT License.