DEV Community

loading...

Getting started with Structurizr Lite

Simon Brown
Author "Software Architecture for Developers" | Creator of the "C4 model for visualising software architecture" | Founder at Structurizr | Software architecture training at architectis.je
・3 min read

Structurizr Lite is a free version of Structurizr, packaged as a Docker container, and designed for developers who want to quickly author and/or view software architecture diagrams, documentation, and architecture decision records (ADRs). A software architecture model, views, and documentation (together called a "workspace") can be defined using the Structurizr DSL - what I referred to as Diagrams as code 2.0 in a previous post; a textual language specifically designed to support software architecture and the C4 model. Let's get started.

1. Create a new directory

First we need to create a directory somewhere to store our workspace.

2. Create a workspace.dsl file

Next we need to create a file called workspace.dsl inside that directory, with the following content.

workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System"

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem "Diagram1" {
            include *
            autoLayout
        }

        theme default
    }

}
Enter fullscreen mode Exit fullscreen mode

You can find more about the Structurizr DSL at https://github.com/structurizr/dsl, but essentially this DSL file says:

  • Create a model with a user and a software system, where the user uses the software system.
  • Create a system context view for the software system, adding the default set of elements, using auto-layout.
  • Use the default theme for styling elements and relationships.

3. Start Structurizr Lite

Assuming that you have Docker installed, you can now start Structurizr Lite with the following commands:

docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/lite
Enter fullscreen mode Exit fullscreen mode

Be sure to replace PATH with the full path to the directory created in step 1. For example, if the directory is located at /Users/alice/structurizr, the commands would be:

docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v /Users/alice/structurizr:/usr/local/structurizr structurizr/lite
Enter fullscreen mode Exit fullscreen mode

4. View the diagram

Open the workspace in a web browser by heading to http://localhost:8080 and you should see your diagram.

Structurizr Lite - diagram

If you make a change to the DSL file and save it, you should see that change immediately reflected when you refresh your web browser.

5. Add some documentation

Let's add some documentation to describe our software system. To do this, create a subdirectory named docs and create a file named 01-context.md inside that subdirectory, with the following content:

## Context

Here is a description of my software system...

![](embed:Diagram1)
Enter fullscreen mode Exit fullscreen mode

Now change the content of the workspace.dsl file to be as follows (notice the addition of the !docs line):

workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System" {
            !docs docs
        }

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem "Diagram1" {
            include *
            autoLayout
        }

        theme default
    }

}
Enter fullscreen mode Exit fullscreen mode

Save all files, refresh your web browser, and click on the top-left button with the icon that looks like a book. You should now see the Markdown documentation page that we just created, which itself is embedding our existing system context diagram.

Structurizr Lite - documentation

Summary

Structurizr Lite provides a quick and free way to get started with the Structurizr tooling. It supports the full set of C4 model diagrams, along with the ability to publish Markdown/AsciiDoc documentation, and architecture decision records (ADRs). Enjoy!

Discussion (3)

Collapse
a30006441 profile image
Dinesh Dharmawardena

I love the tool so far. Are there any plans to make Structurizr Lite open source?

The only feedback I have at this stage is that the Automatic Layout doesn't really do a great job of laying out the elements. There are a few more issues I'd like to raise, just wish it was opensource so that we could see accelerated improvement of this tool

Collapse
simonbrown profile image
Simon Brown Author

Thanks! No plans to make it open source, and I agree with your comment about automatic layout - I don't use it myself. Feel free to raise issues at github.com/structurizr/structurizr....

Collapse
catcodeme profile image
catcodeme

👍👍👍