Importing a Structurizr DSL Workspace into Revelation

Structurizr DSL is the most widely used text-based format for the C4 model — a single workspace file defines your people, software systems, containers and components once, with multiple views generated from it automatically. It's a natural fit for version control, but on its own it stops at the diagram: there's no table of systems and interactions to browse, filter, or hand to a colleague who just wants the data.

Revelation imports a Structurizr DSL workspace directly — no export step, no conversion tool. Point it at a .dsl file and you get a typed, validated Revelation model with one view per Structurizr view, ready to browse, edit, and lay out.

Here's exactly what that looks like, using the internet banking workspace shipped with Revelation as a worked example.

Open the Revelation EA tool and follow along, or jump straight to Menu → Open local model….

The example workspace

The source file is a self-contained Structurizr DSL workspace modelled on the C4 model's own Big Bank plc example: an Internet Banking System used by a customer and support staff, talking to a mainframe banking system and an internal e-mail system.

Source: internet-banking.dsl

workspace "Internet Banking" "Online banking for personal customers" {
  model {
    customer = person "Customer" "A bank customer with personal bank accounts"
    internetBanking = softwareSystem "Internet Banking System" "Lets customers view accounts and make payments" {
      webApp = container "Web Application" "..." "Java, Spring MVC"
      api = container "API Application" "..." "Java, Docker" {
        accounts = component "Accounts Controller" "..." "Spring MVC"
      }
      database = container "Database" "..." "SQL Database" {
        tags "Database"
      }
    }
    customer -> internetBanking "Views accounts and makes payments using"
  }
  views {
    systemContext internetBanking "Context" { include *; autolayout lr }
    container internetBanking "Containers" { include *; autolayout lr }
    component api "Components" { include *; autolayout lr }
  }
}

In full, the workspace defines 2 people, 8 systems/containers/components, and 14 relationships between them — and declares three views: a system context view, a container view, and a component view scoped to the API application.

Opening it in Revelation

1. Menu → Open local model…
   Revelation detects the .dsl extension automatically — there's no separate "import from Structurizr" dialog to find.
2. Select the file
   If your own workspace is split across several files with !include or extends, select all of them together — Revelation works out which one is the actual workspace from the others' own include statements.
3. The Context view opens
   Structurizr doesn't mark a default view, so Revelation opens the first one declared in the DSL — here, the system context view — with the other two available from the toolbar's view picker.

What you get

Three views, laid out automatically on import using Revelation's Drag & Drop layout — drag anything to refine it, and the rest re-routes around your change:

• Context — the customer and support staff either side of the Internet Banking System, with the mainframe and e-mail system it depends on.
• Containers — the web, single-page and mobile front ends, the API application, and the database behind it.
• Components — the API application opened up into its accounts, payments, and mainframe-facade components.

Switch to the Systems or Interactions tab at any point and the same import is sitting there as a flat, filterable table — the same model, not a separate copy of it.

Try it

Download the example and open it yourself, or point Revelation at a Structurizr workspace of your own — .dsl in, structured model out.

Open the Revelation EA tool

The source file used in this article is available at /app/reference/migration-examples/structurizr/, alongside the same scenario written in Mermaid and PlantUML for comparison.