Anybody who works with me knows that I’m a big fan of visualizing software with diagrams. In my experience, having a diagram of an application’s structure or processes performed by the application makes it a lot easier to talk about. High-level diagrams can be especially helpful when communicating with non-technical people. A model I really like to use for architecture diagrams is the C4 model by Simon Brown. This model takes a hierarchical approach and introduces four core diagram types: system context, container, component, and code. These diagrams visualize a software system from the highest to the lowest level.

Until recently I always used the well-known diagrams.net (formerly draw.io) with this C4 plugin to draw such diagrams. As I already wrote in this article about Mermaid I prefer to create diagrams using plain text tools. Mermaid provides an experimental C4 diagram type which looks promising, but is not ready for professional use. While exploring the C4 model website for the hundredth time, something caught my eye. There on the bottom was a logo and the text “The example diagrams were created with Structurizr”. Looking at the Structurizr site, I got excited because this was the tool I was looking for.

Structurizr introduces a sane syntax for C4 diagrams that feels right for me. There are customization options, but the generated diagrams look good enough out of the box.

To demonstrate the syntax, I created a small set of diagrams that describe this blog. Because of this blog’s simplicity, I only added a system context and a container diagram. In the following code snippet, the source code for the diagrams is shown. You can actually copy the code and paste it to the Structurizr DSL page to play around with it.

workspace {

    model {
        reader = person "Reader" "Surves the web in the search for interesting content."
        author = person "Author" "Writes articles."
        blog = softwareSystem "Blog" "A website that serves articles and pages." {
            webserver = container "Web Server" "Serves websites over the internet." "Caddy" {
                reader -> this "visits"
            }
            folder = container "Folder" "Contains HTML files and other assets." {
                webserver -> this "serves"
            }
            ssg = container "Static Site Generator" "Takes input files and generates a static website." "Eleventy" {
                this -> folder "generates website"
                author -> this "writes source files"
            }
        }
    }

    views {
        systemContext blog {
            include *
            autolayout lr
        }

        container blog {
            include *
            autolayout lr
        }

        theme default
    }
}

Structurizr diagrams are composed of a model and a views section that are contained in a workspace. In the first section all systems, persons, containers, and components of the diagrams and their relationships, are defined. The second section defines which views should be generated from the model and how they should look. The above code generates the following two diagrams.

In the above diagram, you can see the blog displayed as a software system and two persons that interact with the blog. The persons represent the readers and the author of the blog.

Going down one layer in the diagram, the containers that make up the blog are described. It is composed of a web server, a folder in the file system, and a static site generator that generates HTML files from source files.

If you have to draw some architecture diagrams, I can only recommend that you give Structurizr a try. I’m really impressed by the clear and expressive language, the tooling, and the generated diagrams.