structurizr-dsl

name	structurizr-dsl
description	Draft, review, and refactor Structurizr DSL workspaces for C4 architecture diagrams. Use this skill whenever a user mentions Structurizr, C4 model diagrams, system context/container/component/deployment views, `workspace.dsl`, `structurizr validate`, or converting architecture notes into DSL, even if they do not explicitly ask for a "skill".

Structurizr DSL Skill

Use this skill to create, update, or troubleshoot Structurizr DSL files with clean C4 modeling structure.

When to use

Use this skill when the user asks for any of the following:

• Create a new Structurizr DSL workspace.
• Convert architecture notes into a workspace.dsl model and views.
• Add or fix C4 views (systemContext, container, component, deployment, dynamic).
• Clean up identifiers, relationships, tags, styles, or view keys.
• Diagnose DSL parser/validation errors.

Core workflow

1. Identify intent and target scope

• Determine whether the user needs modeling from scratch, edits to an existing file, or debugging.
• Infer the desired abstraction level (landscape, context, container, component, deployment, dynamic).

2. Build or edit the model first

• Define people and software systems before containers/components.
• Add relationships after both source and destination elements exist.
• Keep identifiers stable and readable.

3. Define views second

• Add explicit, stable view keys for each view.
• Include only what supports the view's purpose; avoid over-cluttered diagrams.
• Use autoLayout only as a starting point if manual layout is expected later.

4. Style and documentation last

• Add tags/styles only when they clarify meaning.
• Add focused properties, docs, or ADR hooks only if user needs them.

5. Validate and report

• Validate syntax and structural consistency.
• Return a concise changelog and any follow-up recommendations.

Structurizr DSL rules to enforce

• Treat the language as imperative: no forward references.
• Keep opening { on the same line as the statement.
• Keep closing } on its own line.
• Use unique names within required scopes:
  • People and software systems: globally unique.
  • Containers: unique within a software system.
  • Components: unique within a container.
• Ensure each relationship description from one source to one destination is unique.
• Prefer explicit view keys to avoid unstable autogenerated keys.
• Keep relationships meaningful; avoid duplicate semantic edges.

Modeling guidance

Minimal workspace skeleton

workspace "Name" "Description" {
    model {
        user = person "User"
        system = softwareSystem "System" {
            webapp = container "Web App" "Delivers UI" "React"
            api = container "API" "Business logic" "Kotlin"
            db = container "Database" "Stores data" "PostgreSQL"

            webapp -> api "Calls"
            api -> db "Reads and writes"
        }
    }

    views {
        systemContext system "sysctx" {
            include *
            autoLayout lr
        }

        container system "containers" {
            include *
            autoLayout lr
        }

        styles {
            element "Person" {
                shape Person
            }
            element "Container" {
                background "#1168bd"
                color "#ffffff"
            }
        }
    }
}

View selection heuristics

• systemLandscape: enterprise-level context across systems and people.
• systemContext: one software system and its external interactions.
• container: internals of one software system.
• component: internals of one container.
• dynamic: behavior/sequence for a scenario using existing static relationships.
• deployment: runtime topology by environment.

Relationship quality heuristics

• Use short, specific verbs: Uses, Publishes, Queries, Sends command.
• Put protocols/tech in technology field when helpful.
• Do not over-specify implementation detail at higher C4 levels.

Refactoring patterns

• If a model is large, split with !include and keep a clear root workspace file.
• If identifiers are inconsistent, normalize naming and update references in one pass.
• If views are noisy, replace include * with targeted include/exclude expressions.
• If styles are duplicated, centralize tags and style blocks.

Troubleshooting checklist

When the DSL fails or diagrams look wrong, check in this order:

1. Parse/syntax issues

• Missing/extra braces.
• Invalid token ordering.
• Quoting problems around values with spaces.

2. Model consistency

• Undefined identifiers.
• Forward references.
• Duplicate names in invalid scopes.
• Duplicate relationship descriptions between same source and destination.

3. View consistency

• Wrong scope identifier in systemContext, container, component, or deployment views.
• Missing explicit view key (layout instability risk).
• Includes/excludes that hide required elements.

4. Style/notation issues

• Missing tags referenced by styles.
• Theme/icon sources unavailable.

Output format

For any substantial request, respond with:

1. Result

• What was created or changed.

2. Updated DSL

• Provide full DSL when creating from scratch.
• Provide a focused patch/snippet when editing existing files.

3. Validation Notes

• Confirm rule checks performed and list any unresolved concerns.

4. Next Improvements (optional)

• 1-3 practical steps (e.g., add deployment view, split with !include, add ADR links).

Guardrails

• Preserve user intent and naming unless there is a correctness issue.
• Do not invent systems/components not implied by user input; label assumptions clearly.
• Prefer small, reversible edits over sweeping rewrites when modifying existing files.