Structurizr Workspace - Created with Scaffoldizr

When to use this skill

• Whenever the user needs to create or update elements within a given Structurizr workspace.
• Whenever the user needs to create an architecture diagram (leveraging the C4 model).
• Whenever the user needs to validate an existing Structurizr workspace.

General instructions

• In the root folder, search for an

  ./architecture

  folder. If there is no such folder, offer to create one using Scaffoldizr, run:
  bash

  scfz --dest <root_folder> \
    --workspaceName "<name>" \
    --workspaceDescription "<description>" \
    --workspaceScope "softwaresystem" \
    --systemName "<system name>" \
    --systemDescription "<system description>" \
    --authorName "<author name>" \
    --authorEmail "<author email>" \
    --shouldIncludeTheme "false"

  Scaffoldizr will create the

  ./architecture

  folder with all the relevant files.

scfz

• macOS / Linux — run in terminal:
  bash

  curl -s https://formulamonks.github.io/scaffoldizr/assets/install.sh | sh

• Windows — run in PowerShell:
  powershell

  irm https://formulamonks.github.io/scaffoldizr/assets/install.ps1 | iex

Non-interactive CLI usage (AI Agent Mode)

Subcommand routing

workspace.dsl

scfz <generator> [--flag "value"]

external-system

software-system

Passing arguments

--parameter "value"

--parameter=value

Element generators reference

system

--systemName

--systemDescription

--archetype

container

--systemName

--elementName

--containerDescription

--containerType

--containerTechnology

component

--elementName

--componentDescription

--componentTechnology

person

--elementName

--personDescription

external-system

--elementName

--extSystemDescription

view

--viewType

--viewName

--viewDescription

--dynamicScope

--systemName

--containerName

--step-N

constant

--constantName

--constantValue

archetype

--archetypeName

--archetypeBaseType

--archetypeDescription

--archetypeTechnology

--archetypeTags

theme

--themeAction "Add themes" --additionalThemes "<url1>,<url2>"

--viewType

landscape

deployment

dynamic

systemContext

container

component

• All the relevant documentation files are contained within the

  ./architecture

  folder.
• The main entrypoint is the

  ./architecture/workspace.dsl

  file.

• ./architecture/workspace.json

  is a compiled output generated from

  workspace.dsl

  . Never read or modify it directly — it will be overwritten the next time Structurizr runs. To regenerate it, run

  ./architecture/scripts/export.sh

  (or

  export.ps1

  on Windows).

Folder contents

• ./architecture/archetypes

  : Elements that serve as baseline or foundations for other elements. Contains reusable relationship patterns (e.g.,

  1_https_relationship.dsl

  ).

• ./architecture/containers/<system name>

  : Container definitions for a software system. Each software system is contained within an independent folder.

• ./architecture/components/<system name>/<container name>

  : Component definitions for a software system. Each software system is contained within an independent folder, as well as each container.

• ./architecture/decisions

  : Architecture Decision Records (ADRs) documenting key architectural decisions.

• ./architecture/docs

  : Documentation files referenced in the workspace.

• ./architecture/environments

  : This folder contains elements for Deployment view. They are used to create and display deployment diagrams.

• ./architecture/relationships

  : Relationship definitions for the different elements within the system.

• ./architecture/systems

  : System definitions. This folder also contains

  _people.dsl

  to reference person elements and

  _external.dsl

  to reference external systems (systems that are not in scope of the actual diagram).

• ./architecture/views

  : View definitions that render diagrams, including system context views.

Relationships in diagrams

• Structurizr DSL language has the

  !include

  directive which serves as a way to reference other files and folders. If the reference includes a file extension (e.g.

  file.dsl

  ), that file at that path is included. If no extension is included, it assumes that all files within that folder are included.

Workspace Scope

• Depending on the workspace scope you are allowed to create or not certain elements. The workspace can be scoped as

  softwaresystem

  or as

  landscape

  .
  1. In both options you are allowed to create

     archetype

     ,

     constant

     ,

     view

     ,

     person

     ,

     external system

     and

     relationship

     .
  2. If it's

     softwaresystem

     you are allowed ONLY to create

     container

     ,

     component

     in addition to the ones listed in point 1.
  3. If it's

     landscape

     you're allowed ONLY to create

     system

     in addition to the ones listed in point 1.
• Find what is the current workspace scope by checking the

  ./architecture/workspace.dsl

  file for the

  workspace

  block. E.g.:

workspace {
    ...
    configuration {
        scope softwaresystem  // <-- Here is where the scope is defined
    }
    ...
}

• Always alert the user when the suggested action would be in conflict with this rule.

Create new elements within the workspace

Archetype

Constant

Software System

External System

Container

Component

Relationship

View

Theme

theme

theme

scfz theme \
  --themeAction "Add themes" \
  --additionalThemes "https://formulamonks.github.io/scaffoldizr/assets/scaffoldizr-shapes.json"

• --themeAction

  :

  "Add themes"

  |

  "Remove themes"

  |

  "List themes"

• --additionalThemes

  : comma-separated theme URLs to add
• Color themes (Blue, Red, Green, Yellow) are mutually exclusive — selecting a new color replaces the existing one

Use Structurizr CLI commands to interact with the workspace

Build process

• The

  ./architecture/workspace.dsl

  is the only source of truth. All architecture changes must be made to

  .dsl

  files — never to

  workspace.json

  .

• ./architecture/workspace.json

  is a compiled artefact. Structurizr overwrites it on every run. ⚠️ DO NOT READ OR MODIFY

  ./architecture/workspace.json

  DIRECTLY ⚠️. Any manual edits will be silently lost.
• To regenerate

  workspace.json

  from the DSL source, run the export script:
  • Linux/macOS:

    ./architecture/scripts/export.sh

  • Windows:

    ./architecture/scripts/export.ps1

• Use

  ./architecture/scripts/run.sh

  (or

  run.ps1

  ) to start Structurizr Lite and visualize diagrams at

  http://localhost:8080

Error Troubleshooting