Structurizr DSL


The Structurizr DSL (as mentioned on the ThoughtWorks Tech Radar - Techniques - Diagrams as code) allows you to create multiple diagrams based upon the C4 model, in multiple output formats, from a single DSL source file. There are two options for authoring workspaces with the Structurizr DSL.

Structurizr CLI (recommended)

The Structurizr CLI is a command line utility, designed to be used in conjunction with the Structurizr DSL. It provides the ability to push/pull workspaces to/from the Structurizr cloud service or an on-premises installation, in additional to exporting the views defined in a DSL file to other formats (PlantUML, Mermaid, WebSequenceDiagrams, and Ilograph).

The CLI provides access to the full feature set offered by the Structurizr cloud service/on-premises installation and Structurizr DSL. See Getting started with the Structurizr CLI and DSL for more information.

DSL editor

If you'd rather not use the CLI, the Structurizr cloud service/on-premises installation provides an online DSL editor. The editor provides some basic syntax highlighting and the ability to use the DSL without installing the Structurizr CLI, but it does not provide access to the full feature set offered by the Structurizr cloud service/on-premises installation and Structurizr DSL.

To use the DSL editor, click the button on your workspace summary page.

Comparison

Structurizr CLI DSL editor
Diagrams
Documentation !docs
Architecture decision records !adrs
Branding logo logo
Element style icons icon
DSL includes !include
Export to PlantUML, Mermaid, WebSequenceDiagrams, and Ilograph

Important notes

  1. If you have previously defined a workspace using one of the code-based client libraries, or the browser-based workspace editor, it is not possible to convert these to the DSL format - there is no tooling that will "decompile" a workspace back to the Structurizr DSL.
  2. Any changes you make to a workspace using the browser-based workspace editor will not be reflected in the DSL source.

Real-time collaboration

The DSL editor also supports real-time collaboration. To use it, click the button on your workspace summary page.

Not available with a free or basic subscription

Anybody who has owner, admin, or read-write role-based access to your workspace can click the same button to join your collaboration session. The collaborative editor currently functions as follows:

  • DSL source is synchronized in real-time.
  • Each user can click the "Render" button to render the DSL as one or more diagrams.
  • Clicking the "Save workspace" button will save the DSL definition, and automatically reload the diagrams for each collaborator.

At the moment, diagram layout changes (moving elements, adding vertices to relationships, etc) are not synchronized until the workspace is saved. This feature may be added at a later date.


Collaborative DSL editor