What Will You Learn?

  • What is Structurizr?
  • What are the use cases for Structurizr?
  • How do I create diagrams with Structurizr?
  • How do I use the Structurizr CLI?
  • Where do I learn more about Structurizr?

The Basics

Structurizr is a diagram generation tool created by Simon Brown, the creator of the C4 Model. The tool’s primary focus is the rapid generation of several diagrams with the same components. Maybe Simon was tired of diagramming tools that make you repeat yourself? If so, I share the sentiment.

It’s free for most use cases.

Primary Use Cases

  • Creation of architectural diagrams
  • Capture architecture decisions
  • Diagram review
  • Saving time!


Building diagrams can be very tedious, and Structurizr addresses this tedium. A typical workflow in Structurizr looks like this.

  1. Add diagram elements
  2. Create relationships
  3. Layout your diagram
  4. Download your diagrams


Edit diagrams using the Structurizr command-line interface. You can follow these steps to edit your workspace if you’re on macOS.

# Install docker or some other docker-like app

cd /tmp
wget -P /tmp https://raw.githubusercontent.com/structurizr/examples/main/dsl/getting-started/workspace.dsl
docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v /tmp:/usr/local/structurizr structurizr/lite
open http://localhost:8080/ # Start editing!

# Update /tmp with your preferred directory

Structurize Your Workspace

I use Structurizr Lite to create diagrams with code. I’ve found a way to reuse models using this method. Reusing models keeps the management of links to component details simple.

workspace "Reuse Models" "Demonstrate Model Reuse" {

    model {
        customer = person "Customer" "Customer" "Customer"
        website = softwareSystem "Website" "Website" "Website"

        system1 = softwareSystem "system1" "" "" {
            rel1 = customer -> website "Relationship scoped to system1"

        system2 = softwareSystem "system2" "" ""  {
            rel2 = website -> customer "Relationship scoped to system2"

    views {
        systemContext system1 {
            include customer
            include website
            exclude rel2

        systemContext system2 {
            include customer
            include website
            exclude rel1


Getting Help

Learning how to use Structurizr will take time. I’ve barely scratched the surface of what it can do, but luckily you can get help.

I like to learn with examples. I found the Spring PetClinic example to be the best way to learn how to use it. Try exporting the workspace from the workspace menu.

Structurizr export workspace

Then import the workspace so you can explore how Structurizr created those diagrams.

Structurizr import workspace

Learn Structurizr - Beyond the Basics


Other Learning