Skip to content

Working with workspace.dsl

How to render, preview, and extend the Structurizr DSL model at documentation/architecture/workspace.dsl.

  1. Install "Structurizr DSL" (marketplace: systemticks.c4-dsl-extension — or the one from community, both work).
  2. Open documentation/architecture/workspace.dsl.
  3. The extension previews the diagrams live in a side panel.

Option B — Structurizr Lite (full local renderer)

Runs the free Structurizr app in a container; serves the full preview at http://localhost:8080 including styles + interactive zoom.

docker run --rm -p 8080:8080 \
  -v "$(pwd)/documentation/architecture:/usr/local/structurizr" \
  structurizr/lite

Then open http://localhost:8080. Edits to workspace.dsl are picked up on page refresh.

Option C — structurizr-cli (headless, for CI or offline exports)

brew install structurizr-cli     # macOS
# or download from https://github.com/structurizr/cli/releases

structurizr-cli export \
  -workspace documentation/architecture/workspace.dsl \
  -format plantuml/structurizr \
  -output /tmp/structurizr-export

Exports each view to a .puml file that can be rendered to PNG/SVG.

Embedding diagrams in MkDocs

For the docs site, we currently link back to the workspace.dsl source and offer the three rendering options above. A server-side render step in the docs.yml CI workflow may be added later if static export proves valuable.

Conventions

  • One workspace (workspace.dsl) — no per-ADR forked copies.
  • Views per scope: start with System Context + Containers. Add a Component view only when an ADR references it.
  • Styles live in the styles {} block inside workspace.dsl, not per-view.
  • Labels on relationships describe the intent, not the protocol (e.g. "Triggers launchers", not "POST /api/trigger").
  • External systems get the external tag so the shared style (grey fill) applies.

Validating the file

Structurizr DSL has a strict parser. To lint without rendering:

structurizr-cli validate -workspace documentation/architecture/workspace.dsl

If this command ships in CI later, it gates the PR.