Home › Guides › Structurizr DSL

Structurizr DSL import and export

Structurizr DSL is a text language for C4 models. ArchLens reads its model, so a workspace you already wrote becomes a diagram your team can edit together, and it writes a diagram back out as DSL.

What Structurizr DSL is

The Structurizr DSL is part of Structurizr, the set of tools by Simon Brown, who created the C4 model. You describe the model (people, software systems, containers, components and their relationships) and its views as text, and the diagrams are generated from it. Many teams keep a workspace.dsl next to their code.

workspace {
  model {
    customer = person "Customer"
    shop = softwareSystem "Shop" {
      web = container "Web app" "Lets customers buy" "React"
      api = container "API" "" "Node.js"
      db  = container "Orders DB" "" "PostgreSQL" "Database"
    }
    payments = softwareSystem "Payments" "" "External"
    customer -> web "Browses and buys"
    web -> api "Calls" "HTTPS/JSON"
    api -> db "Reads and writes" "SQL"
    api -> payments "Charges cards" "HTTPS"
  }
}

Import a Structurizr workspace

Open a workspace and go to Diagrams.
Choose Import diagram and pick your .dsl file (.json ArchLens files are read too). Files up to 5 MB.
A new diagram is created from the file's model and opens auto-arranged, since the DSL has no positions. Rearrange anything by hand, or run Auto layout again.

The objects become part of the workspace's shared model, so you can place them on other diagrams too.

What is read, and what is skipped

In the DSL	In ArchLens
`person`, `softwareSystem`, `container`, `component` (nested)	the same objects, at the same levels, with name, description and technology
`a -> b "label" "technology"`	a connection with that label and protocol
a container tagged `Database`	a Store
an element tagged `External`	an external object
`dynamic` views	flows: each `a -> b` step follows an existing relationship; a step written backwards is that relationship's reply; a `{ }` block is a parallel step
`group`, `enterprise`	read through: their contents belong to the enclosing element
other views, `styles`, themes, `!docs`, `!adrs`	skipped quietly (ArchLens lays out and drills down itself)
`!include` and anything else not understood	skipped and listed after the import

One import reads at most 2,000 elements, 4,000 relationships and 200 dynamic views. Anything the model rules refuse (for example a relationship between an object and its own parent) is left out and counted.

Export a diagram as Structurizr DSL

In a diagram, open Share at the top right (viewers see Export) and choose Structurizr DSL (.dsl): Copy or Download. Unlike the Mermaid and PlantUML exports, which describe the view on screen, the DSL export is the whole diagram: every object placed on it with the parents it needs, their relationships, and one view per level that has something to show.

Stores are written as containers tagged Database and external objects carry the tag External, so ArchLens reads the file back to the same model. Positions, tag colours and drawings are not part of the DSL export; for a complete copy use Diagram file (JSON).

Import from an AI assistant

The ArchLens MCP server has an import_structurizr tool. An assistant such as Claude can write DSL from your description, a repository or an existing document, open a draft and import into it; you review the draft and merge it. Objects the workspace already has (same type, name and parent) are placed on the new diagram rather than copied, unless the assistant asks for new ones.

Start free with Google or GitHubImport your first workspace in a minute.