L06 Structurizr

title: "Structurizr — C4 Architecture with Diagram-as-Code" weight: 6 description: "Learn Structurizr for C4 model architecture diagrams: DSL syntax, workspace configuration, system context and container views, deployment views, and automated architecture documentation." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, diagram-as-code] }

Structurizr is a diagram-as-code tool specifically designed for the C4 model, providing a DSL for defining software architecture and generating consistent, hierarchical diagrams automatically.

In this lesson, you will learn Structurizr DSL syntax, defining software architecture models, creating views at each C4 level, adding documentation, and integrating with CI pipelines.

What You'll Learn

You will learn Structurizr DSL basics, define a software architecture model, create System Context, Container, and Component views, add deployment views, and generate documentation.

Why It Matters

Structurizr ensures consistency across all architecture diagrams because views are generated from a single model. Change the model, and all diagrams update automatically.

Real-World Use

DodaZIP uses Structurizr for its complete architecture documentation. The single DSL file defines the entire system. Adding a new container automatically updates all related diagrams.

def create_structurizr_dsl(workspace_name, model_elements):
    """Generate Structurizr DSL structure."""
    lines = [
        f'workspace "{workspace_name}" {{',
        '    model {',
    ]
    for element in model_elements:
        if element["type"] == "person":
            lines.append(f'        {element["name"]} = person "{element["name"]}"')
        elif element["type"] == "system":
            lines.append(f'        {element["name"]} = softwareSystem "{element["name"]}"')
    lines.append('    }')
    lines.append('    views {')
    lines.append('        systemContext "System" "Context" {')
    lines.append('            include *')
    lines.append('            autolayout')
    lines.append('        }')
    lines.append('    }')
    lines.append('}')
    return "\n".join(lines)

dsl = create_structurizr_dsl("DodaZIP", [
    {"name": "User", "type": "person"},
    {"name": "DodaZIP", "type": "system"},
])
print(dsl)

def add_container_view(dsl_text, containers):
    """Add container view to an existing Structurizr DSL."""
    view = '\n    views {\n        container "System" "Containers" {\n'
    for c in containers:
        view += f'            include {c}\n'
    view += '            autolayout\n        }\n    }'
    return dsl_text + view

dsl = create_structurizr_dsl("DodaZIP", [])
dsl = add_container_view(dsl, ["WebApp", "API", "Database"])
print(dsl)

def add_deployment_view(dsl_text, deployment_nodes):
    """Add deployment view to Structurizr DSL."""
    view = '\n    views {\n        deployment "System" "Deployment" {\n'
    for node in deployment_nodes:
        view += f'            deploymentNode "{node}"\n'
    view += '        }\n    }'
    return dsl_text + view

dsl = create_structurizr_dsl("DodaZIP", [])
dsl = add_deployment_view(dsl, ["AWS", "EC2", "RDS"])
print(dsl)

Teacher Mindset

Think of Structurizr as a model-driven architecture tool. You define the model once (people, systems, containers, components) and generate as many views as you need. This is fundamentally different from drawing each diagram individually. It requires up-front thinking about the architecture model but pays off in consistency and maintainability.

Common Mistakes in Structurizr

1. Not Defining the Model First

Jumping to views without defining the full model leads to inconsistent diagrams. Define all elements first, then create views.

2. Overly Complex Models

A model with 50 people and 100 systems defeats Structurizr's purpose. Keep the model focused on the system boundary. Use separate workspace files for different subsystems.

3. Ignoring Relationships

Elements without relationships produce empty diagrams with no arrows. Define how elements interact. Relationships make architecture diagrams valuable.

4. Not Using Tags for Styling

Tags control colors, shapes, and styles. Without tags, all elements look the same. Apply tags consistently: Person, System, Container, Component.

5. Skipping Deployment Views

Architecture is not just about software structure. Deployment views show how software maps to infrastructure. Include them for operational context.

Practice Questions

1. What is the difference between Structurizr and Mermaid C4? Structurizr uses a model-driven approach: define the model once, generate views. Mermaid C4 requires writing each view as a separate diagram. Structurizr ensures consistency across views.

2. How does Structurizr ensure diagram consistency? All views are generated from a single model definition. When the model changes, all views update automatically. This prevents the common problem of inconsistent architecture documentation.

3. What is the Structurizr DSL? A domain-specific language for defining software architecture models. It supports people, software systems, containers, components, relationships, and deployment nodes.

4. How do you render Structurizr diagrams? Use the Structurizr CLI, the Structurizr library for Java or .NET, or the Structurizr cloud service. The DSL is compiled to diagrams in various formats.

5. Challenge: Create a Structurizr DSL file for a simple web application. Include a user, a web application, an API server, and a database. Define relationships. Create System Context and Container views.

FAQ

Mini Project

Create a Structurizr workspace for a project you work on. Define the architecture model with at least 3 elements and relationships. Generate System Context and Container views. Export as images and embed in a documentation page.

What's Next

D2 Lang in the next lesson.