Getting started with the Structurizr DSL
Tags: architecture, productivity, c4model
Published: 2020-07-04 15:44:19

---
title: Getting started with the Structurizr DSL
published: true
description: 
series: Software architecture diagrams as text
tags: #architecture #productivity #c4model
//cover_image: https://direct_url_to_image.jpg
---

Now that we've looked at diagramming vs modelling, and some of the tooling choices, let's see how to get started with the [Structurizr DSL](https://github.com/structurizr/dsl). This open source project defines a text-based domain specific language (DSL) that can be used to create software architecture diagrams based upon the [C4 model](https://c4model.com).

## Defining a model and view

Let's imagine that we want to create a [System Context diagram](https://c4model.com#SystemContextDiagram) showing a user using a software system. This can be described with the DSL as follows. 

```
workspace {

    model {
        user = person "User" "A user of my software system."
        softwareSystem = softwareSystem "Software System" "My software system."

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem {
            include *
            autoLayout
        }
    }
    
}
```

This DSL definition:

- creates a person named "User"
- creates a software system named "Software System"
- creates a relationship between the person and the software system
- creates a System Context view for the software system (including all applicable elements, with auto-layout enabled)

## Rendering the diagram

To render the diagram, we need some additional tooling in the form of the [Structurizr CLI](https://github.com/structurizr/cli), but we'll look at that in the next blog post. For now, there's a demo page that we can use to try out the DSL. If you browse to [structurizr.com/dsl](https://structurizr.com/dsl) and copy the above DSL into the textbox, you should see something like the following when you click the "Refresh" button. Alternatively, [clicking this link](https://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/examples/getting-started-short.dsl) will do that for you.

![Structurizr DSL demo](https://dev-to-uploads.s3.amazonaws.com/i/yuuif8zm5d2c3adk2cfl.png)

This demo page shows you how the diagram is rendered with the Structurizr tooling, plus it provides diagram definitions for PlantUML and Mermaid.

## For more information

If you're interested in learning more about the DSL, take a look at the following links:

- [Amazon Web Services example](https://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/examples/amazon-web-services.dsl)
- [Big Bank plc example](https://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/examples/big-bank-plc.dsl)
- [DSL language reference](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md)

## Summary

The [Structurizr DSL](https://github.com/structurizr/dsl) is an open source project defining a text-based domain specific language (DSL) that can be used to create software architecture diagrams based upon the [C4 model](https://c4model.com). The next blog post will show how to use the DSL in conjunction with the [Structurizr CLI](https://github.com/structurizr/cli).