Multi-workspace mode in Structurizr Lite

Structurizr is a tool to produce software architecture diagrams following the C4 model. 'Workspaces' are how Structurizr isolates models, views, and documentation for a single system.

Since it is rare that we are producing diagrams or documentation for a single system in isolation, Structurizr Lite's support for only a single workspace may at first seem of limited use. This post shows you how to use the free Structurizr Lite in multi-workspace mode.

The Structurizr website claims Lite is "A single workspace version of Structurizr" (https://structurizr.com/help/tour).

Yet release notes for v2024.06.18 say "[it] Adds support for multi-workspace mode (not yet documented)".

How can we use this feature in our copy of Structurizr Lite then?

Our aim is to go from the following directory structure:

project/
    ┣━ workspace.dsl
    ┗━ workspace.json (auto-generated)

to:

project/
    ┣━ structurizr.properties
    ┣━ 1/
    ┃  ┣━ workspace.dsl
    ┃  ┗━ workspace.json
    ┗━ 2/
       ┣━ workspace.dsl
       ┗━ workspace.json

And in so doing support more than one workspace in a single instance of Structurizr. To do so:

1. Create a structurizr.properties file with contents:

   structurizr.workspaces=2

   (Structurizr will only check the number is larger than 1 - it doesn't have to match how many workspaces you have.)

2. Create workspace directories following the regex \d*-[a-zA-Z0-9_-]* ^{1 2}

I figured out the above by looking at Configuration.java and following the breadcrumb trail starting at STRUCTURIZR_PROPERTIES_FILENAME. Configuration.java is a good starting point if you're curious about the internals of Structurizr Lite.

Image: Herzog August Bibliothek https://diglib.hab.de/wdb.php?dir=mss/74-1-aug-2f, licensed under CC BY-SA.