Structurizr DSL

This GitHub repository contains an implementation of the Structurizr DSL - a way to create Structurizr software architecture models based upon the C4 model using a textual domain specific language (DSL). The Structurizr DSL has appeared on the ThoughtWorks Tech Radar - Techniques - Diagrams as code.

Getting started

• Getting started with Structurizr Lite (using the DSL)
• Getting started with the Structurizr CLI and DSL
• Structurizr DSL demo
• Diagrams as code 2.0 (video from GOTO Copenhagen 2021)

Reference

• Language reference
• Changelog
• Structurizr DSL cookbook (this is a work in progress)

A quick example

As an example, the following text can be used to create a software architecture model and an associated view that describes a user using a software system.

workspace {

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

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem {
            include *
            autolayout
        }

        theme default
    }
    
}

(view this example)

Convention over configuration, useful defaults

The DSL is designed to be as compact as possible. In conjunction with the Structurizr CLI, the following DSL fragment will automatically create the implied relationship between the user and softwareSystem elements, create three views with auto-layout enabled (1 x System Landscape, 1 x System Context, 1 x Container), and add some default element styles.

workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System" {
            webapp = container "Web Application"
            database = container "Database"
         }

        user -> webapp "Uses"
        webapp -> database "Reads from and writes to"
    }
    
    views {
    	theme default
    }

}

Examples

• Getting started
• Big Bank plc
• Amazon Web Services

Rendering tools

The Structurizr DSL is rendering tool independent, and there are a number of tools that can be used to render diagrams.

• Structurizr Lite/on-premises/cloud service: A browser-based diagram and documentation rendering tool with interactive diagrams, "double-click to zoom", etc.
• c4viz: A browser-based diagram renderer, with diagram navigation and "click to zoom".
• Structurizr Site Generatr: Generates a HTML microsite with diagrams, documentation, and a UI to explore the model.
• Kroki: Kroki generates diagrams from a number of text-based formats, including the Structurizr DSL.
• Git for Confluence | Markdown, PlantUML, Graphviz, Mermaid: A Confluence plugin that will render a specific diagram from a Structurizr DSL file stored in your git repo.
• Structurizr Export: A collection of Java classes to generate diagrams as PlantUML, Mermaid, DOT, and WebSequenceDiagrams. An export to Ilograph is also available.
• Structurizr CLI: A command line tool that bundles the Structurizr Export utilities.

Other tooling support

• VS Code extension (syntax highlighting and diagram previews; please note that there are some known issues with the syntax highlighting - see Divergences for more details, and Examples for examples that work correctly with the extension)
• VS Code extension (syntax highlighting)