Structurizr DSL Migration Showcase

This showcase demonstrates how to migrate an existing Structurizr workspace into kUML C4 using kuml import --format structurizr. The example is Simon Brown’s canonical Big Bank Plc reference architecture — the same workspace featured at https://structurizr.com/share/36141.

After migration, the model lives as a type-safe .kuml.kts script: versionable in Git, renderable to SVG/PNG/PDF, composable with kUML profiles, and ready for AI-assisted editing via the Desktop’s AI panel.

The source workspace

The Big Bank Plc workspace defines:

  • Three people: Personal Banking Customer, Customer Service Staff, Back Office Staff

  • Four software systems: Internet Banking System, Mainframe Banking System, E-mail System, ATM

  • Six containers inside Internet Banking System: Web Application, Single-Page Application, Mobile App, API Application, Database

  • Six components inside API Application: Sign In Controller, Accounts Summary Controller, Reset Password Controller, Security Component, Mainframe Banking System Facade, E-mail Component

  • Four views: System Landscape, System Context, Containers, Components

The full DSL workspace is committed as a test fixture at kuml-cli/src/test/resources/structurizr/bigbankplc.dsl.

Running the import

kuml import --format structurizr bigbankplc.dsl --output bigbankplc.kuml.kts

The importer:

  1. Parses the Structurizr DSL with StructurizrDslParser — a hand-written recursive-descent parser that handles workspace, model, views, relationships (→), and all element types.

  2. Converts the parsed StructurizrWorkspace to a kUML C4 c4Model { … } script via KumlDslGenerator.

  3. Writes the output to the specified file. If --output is omitted, the generated DSL is printed to stdout.

Generated kUML C4 script (excerpt)

// Generated by kuml import --format structurizr
// Source: bigbankplc.dsl
// Review and adjust before use.

import dev.kuml.c4.dsl.*
import dev.kuml.c4.model.*

var webApplication: C4Container? = null
var singlePageApplication: C4Container? = null
var mobileApp: C4Container? = null
var apiApplication: C4Container? = null
var database: C4Container? = null

c4Model(name = "Big Bank Plc") {
    val customer = person(
        name = "Personal Banking Customer",
        description = "A customer of the bank, with personal bank accounts.",
    )
    val internetBankingSystem = softwareSystem(
        name = "Internet Banking System",
        description = "Allows customers to view information about their bank accounts, and make payments.",
    ) {
        webApplication = container(
            name = "Web Application",
            technology = "Java and Spring MVC",
        )
        apiApplication = container(
            name = "API Application",
            technology = "Java and Spring MVC",
        ) {
            component(name = "Sign In Controller", technology = "Spring MVC Rest Controller")
            component(name = "Accounts Summary Controller", technology = "Spring MVC Rest Controller")
            // …
        }
        // …
    }

    customer uses internetBankingSystem with "Views account balances, and makes payments using"
    // …

    systemContext(internetBankingSystem) { include("*"); autoLayout(LayoutDirection.LEFT_TO_RIGHT) }
    container(internetBankingSystem) { include("*"); autoLayout(LayoutDirection.LEFT_TO_RIGHT) }
}

What the import does NOT migrate

The Structurizr DSL has features without a direct kUML equivalent. The generator applies a best-effort mapping and adds // TODO comments where manual review is recommended:

Structurizr feature kUML handling

tags on elements

Dropped — tags are Structurizr-specific and have no kUML C4 counterpart. Review for stereotype opportunities.

theme / styles in views

Dropped — use kUML themes instead (--theme elegant, --theme kuml, or a custom theme plugin).

properties blocks

Dropped — document as comments in the output.

Deployment environments

Deployment nodes are imported as deploymentNode(…) elements. Nested containerInstance / softwareSystemInstance are modelled as uses relationships with a // TODO marker.

Dynamic views

Not yet supported — the view is imported as a systemContext fallback with a // TODO comment.

Rendering after migration

# SVG (default)
kuml render bigbankplc.kuml.kts

# PNG
kuml render bigbankplc.kuml.kts --format png

# All diagrams in one pass
kuml render bigbankplc.kuml.kts --format svg --all

What’s next

Once the model is in kUML format you can:

  • Apply profiles — annotate containers with «Service», «Repository» etc. for codegen.

  • Generate TypeScript stubs — kuml generate --codegen typescript bigbankplc.kuml.kts.

  • Export back to Structurizr — kuml export --format structurizr bigbankplc.kuml.kts for round-trip validation.

  • Edit with AI — open in the Desktop app and describe structural changes in plain language.

See also