Software Architecture as Code With Structurizr

Thumbnail 17

Are you using the C4 model to create your architecture diagrams? Then Structurizr might be a good option for you to consider. With Structurizr, you can createdocker software for windows 10 and maintain your diagrams as code. Let’s take a closer look at it in this blog!

Introduction

The C4 model helps you with visualizing software architecture. We all know the whiteboard diagrams clutteresystem context diagram sysmld with boxes and connectorsdomain-specific language model. The C4 model approach helps you vsystem context diagram legendisualize software architecture in a more structured way. A good explanation is given on the C4 modelsystem context diagram website, so if you do not know what it is, it is worth reading it firstsoftware architecture document.

The next question is which tool you use to create the diagrams. You can use Visio, draw.io, PlantUML, even PowerPoint, ordocker software download for windows whatever tool yosoftware architecture patterns pdfu normally use for creating diagrams. Howeversoftware architecture, these tools do not check whether naming, relations, etc. are consistently ussoftware architecture design patternsed in the different diagrams. Besides that, it might be difficudocker software containerlt to review new versions of diagrams because idocker software for windows 10t is not clear wdocker software download for windowshich changessystem context diagram scd are made.

In order to solvdocker software download for windowse these problems, Simon Brown, thedocker software license author ofsystem context diagram template the C4 model, created Structurizr. Structdocker software licenseurizr allows you to create diagrams as code. Based on the code, Structurizr visualizedocker software downloads the diagrams fodocker software licenser you and allows you to interact with the visualizatiosystem context diagram examplesn. Bsoftware architecture patterns pdfecause the ddomain-specific language examplesiagrams are maintained in code, you can add them to your version condomain-specific languages pdftrol system (Git) and changes in the diagrams are tracked and can be easily resoftware architecture designviewed.

Isoftware architecture documentn the resystem context diagrammaining part of this bldomain-specific language dslog, you will explore some of the features odomain-specific languagef Structurizr. Youdomain-specific languages pdf will only use two diagram types of the C4 moddocker software download for windowsel (the most commonly used ones):

  • System contesoftware architecture toolxsoftware architecturet diagram: Your application as a black box indicating the users of your application
  • Container diagram: An odomain-specific language in writingverview of your software architectursystem context diagram visioe

Soursoftware architecture patternsces used in this blog can be found on Gidomain-specific language dsltHub.

Prerequisites

Prerequisitedocker software for windows 10s for this blog are:

  • Basic knowleddocker software documentationge of the C4 model
  • Basic knowledge of Docker
  • Linux is used, so if you are using a different Operating System, you will need to adjust the commands accordingly.

Installation

There are different installation options for Strucdocker software documentationturizr. In this blog, you will make use of Structurizr Lite, which is adomain-specific language in writingn easy installation using Docker which supportssystem context diagram one workspace.

  • Create in the root of the repository a data directory. Thisoftware architecture documents direcdomain-specific language examplestory will be mapped as a volume in the Ddomain-specific language dslocker container.
  • Execute the following commands from within the root of the repository.
Shedocker software containerll
$ docker pull structurizr/lite
$ docker run -it --rm -p 8080:8080 -v ./data:/usr/local/structurizr structurizr/lite
  • Navigsystem context diagramate in your browser to http://localhost:8080 and the Structurizr webpage is shown.

Insystem context diagram legend the data directory, you notice that sdomain-specific languages pdfome data is added. When you take a closer look at it, yousystem context diagram sysml notdomain-specific languages pdficsystem context diagram legende that all files have the root ownership. This is not very convenient, because when you wantsoftware architecture patterns to edit the files,docker software license you have to do so as root.

Shell
$ ls -la
...
drwxr-xr-x 1 root      root           22 feb 18 12:04 .structurizr/
-rw-r--r-- 1 root      root          316 feb 18 12:03 workspace.dsl
-rw-r--r-- 1 root   root     2218 feb 18 12:04 workspace.json
  • Stop the container with CTRL+C and remove the contents of tdocker software download for windowshesoftware architecture patterns pdf data directory.

You wisoftware architecture design patternsll start the codocker software download for windowsnsoftware architecture patterns pdftainer with the same user you are using on your host machine. Witsystem context diagram visioh the id command, you can retrieve your uid and gid. It is importantdomain-specific language definition that you use the same uid and gid inside the container in order that files can be edited easily inside and outside the container.

Replace in the following commansoftware architecture patterns pdfd <uid> and <gid> with yoursoftware architecture design patterns uid and gid and start the Docker containedomain-specific languages pdfr again.

Shell
<div class="codeMirror-code--wrapper" data-code="$ docker run -it --rm -p 8080:8080 -system context diagram scdu : -v ./data:/udocker software download for windowssr/local/structurizr structurizr/lite" data-lang="text/x-sh">
$ docker run -it --rm -p 8080:8080 -u <uid>:<gid> -v ./data:/usr/local/structurizr structurizr/lite

When you check the ownership of the files again, you will notice that the directory and files are now owned by your host user.

  • Navigate again in tsystem context diagramhe browser to Structurizr and enable Auto canvas sizdomain-specific language dsle and Auto-layout. This will create a more beautiful diagram.

Initial DSL

First, let’s take a closer look at the initialsystem context diagram legend DSL that has been created. Tsoftware architecture designhe complete DSL reference can be found here.

The initial DSL is the folsoftware architecturelowing:

JSON
softwareSystem "Uses" } views { systemContext softwareSystem "Diagram1" { include * } } configuration { scope softwaresystem } }" data-lang="application/json">
workspace {
    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System"
        user -> softwareSystem "Uses"
    }
    views {
        systemContext softwareSystem "Diagram1" {
            include *
        }
    }
    configuration {
        scope softwaresystem
    }
}

The followsystem context diagram sysmling sections can be viewed:

  • model: The model contains the actors and the software system. If you need to redocker software licenseference these in the DSL, esystem context diagram scd.g., in relations, you assign them to a variable. The variablesdomain-specific language definition user and softwareSystem are used here. The model also contains the relatdomain-specific language in writingions. One relation frodomain-specific language examplesm user to softwareSystem is created.
  • views: To visualize the model, you need to crdomain-specific language wikipediaeate views. In this isystem context diagram examplesnitial DSL, a view of the System Context Ddomain-specific languages pdfiagram is created. With the include keyword, yosoftware architecture patternsu can include all or a part of the model.
  • configuration: This section will not be covered insoftware architecture patterns this bdocker software containerlog.

Basic System Context DSL

Now it is tsoftware architecture design patternsime to cresystem context diagram scdate a System Context Diagram for your application. The application is a wedocker software licensebshop with two types of users, a customer and an administrator. The webshop makes use of asystem context diagram legend global payment system thasoftware architecture patternst handles bank transactions.

The DSL is the following:

JSON
myWebshop "Uses" administrator -> mdomain-specific languageyWebshop "Uses" myWebshop -> glsoftware architecture patternsobdomain-specific languagealPayment "Uses&system context diagram c4quot; } views { systemContext myWebshop "MyWebshosoftware architecturepSystemContextView" { include * autolayout } } }" data-lang="applicatiosoftware architecture design patternsn/json">
workspace {
    model {
        customer = person "Customer" "The customer of our webshop"
        administrator = person "Administrator" "The administrator of the webshop"
        globalPayment = softwareSystem "Global Payment" "Used for all banking transactions"
        myWebshop = softwareSystem "My Webshop" "Our beautiful webshop"
        customer -> myWebshop "Uses"
        administrator -> myWebshop "Uses"
        myWebshop -> globalPayment "Uses"
    }
    views {
        systemContext myWebshop "MyWebshopSystemContextView" {
            include *
            autolayout
        }
    }
}

Some thindomain-specific language in writinggs to nosoftware architecture tooltice here:

  • Relations have the following forsystem context diagram examplesmat: identifier -&gdocker software toolt; identifier description technology. The idsystem context diagram scdentifiers must correspond to a variablesystem context diagram template defined abodomain-specific language modelve the relations.
  • Views have the following format: systemContext softwarsoftware architecture diagrameSystem key. The softwareSystem must correspond to an identifier defined in the model. The key cadomain-specific language in writingn be chosen freely.
  • The autolayout option can be added to the viedomain-specific language in writingw so that itsystem context diagram is enabled by defsystem context diagram sysmlault for this viewsystem context diagram visio.
  • A problsystem context diagram scdem I encountered is the followsystem context diagraming:
    • Only one person was shown in the view, the last one defined. I managed to solve this by commenting on the entire view section.software architecture design patterns A default view is used this way. With this default view, all persons were shown. After this, I enabled the view sectionsoftware architecture tool again, and now aldomain-specific language modell persons were shown.

The System Context Diagram is shown as follows. You can also apply themes to the views, which will enhancesoftware architecture patterns your diagram.

You can alssoftware architecture diagramo apply themes to the views, which will enhance your diagram.

JSON
views {
    systemContext myWebshop "MyWebshopSystemContextView" {
        include *
        autolayout
    }
    theme default
}

The System Contexdomain-specific languaget Diagram becomes the following. This already looks more like a C4 model System Context Diagram.

Basic Container DSL

Time to create a diagram fdocker software downloador thsoftware architecture toole software arsoftware architecture documentchitecture, the Container Diagram. Assume that you need a frontend for both users, a common backend, and, odocker software containerf course, a datasystem context diagram examplesbase.

Tsystem context diagram sysmlhe DSL becomes the following:

JSON
mydocker software management toolWebshop "Uses" administrator -> myWebshop "Uses" myWebshop -> globalsystem context diagram templatePayment "Uses" // software system relationships customer -> customerdomain-specific languages pdfFrontend "domain-specific language definitionUses" "https" administrator -> administratorFrontend &quotsoftware architecture design patterns;Usoftware architecture patternsses" "https" customerFrontend -> webshopBackend &qudocker software downloadot;Uses" "http" administratdomain-specific language dslorFrontend -> webshopBackend "Uses" "http" webshopBackend -> webshopDatsoftware architecture patterns pdfabase "Uses" &qusystem context diagram c4ot;ODBC" webshopBackend -> globalPayment "Uses" "https" } views { systemContext myWebshop "MyWebshopSystemContextView&qdomain-specific language dsluot; { include * autolayout } container myWebshop "MyWebshopSoftwareSystemView" { include * autolayout } theme default } }" data-lang="application/json">
workspace {
    model {
        customer = person "Customer" "The customer of our webshop"
        administrator = person "Administrator" "The administrator of the webshop"
        globalPayment = softwareSystem "Global Payment" "Used for all banking transactions"
        myWebshop = softwareSystem "My Webshop" "Our beautiful webshop" {
            customerFrontend = container customerFrontend "The frontend for the customer"
            administratorFrontend = container administratorFrontend "The frontend for the administrator"
            webshopBackend = container webshopBackend "The webshop backend"
            webshopDatabase = container webshopDatabase "The webshop database"
        }
        // system context relationships
        customer -> myWebshop "Uses"
        administrator -> myWebshop "Uses"
        myWebshop -> globalPayment "Uses"
        // software system relationships
        customer -> customerFrontend "Uses" "https"
        administrator -> administratorFrontend "Uses" "https"
        customerFrontend -> webshopBackend "Uses" "http"
        administratorFrontend -> webshopBackend "Uses" "http"
        webshopBackend -> webshopDatabase "Uses" "ODBC"
        webshopBackend -> globalPayment "Uses" "https"
    }
    views {
        systemContext myWebshop "MyWebshopSystemContextView" {
            include *
            autolayout
        }
        container myWebshop "MyWebshopSoftwareSystemView" {
            include *
            autolayout
        }
        theme default
    }
}

What has been added to the DSL?

  • The application myWebshop in the modedomain-specific language in writingl hasystem context diagram templates been extended with the containers defisystem context diagram examplesning the architesoftware architecture diagramcture.
  • In the model, the relatisoftware architecture design patternsondocker software downloads are defined betwdocker software documentationeen the containsoftware architecture diagramers. Note that this time, also the used technology is added to the relations.
  • A container view is added to the views.

The container view is represented as follows.

The fun part is that when you navigate to the System Context Diagram, you can double-click the myWebshop software system and it will show you thsoftware architecture toole Container Diagram. Awesome!

Styling

In the Container Diagram, thsystem context diagram visioe database is represented as a rdomain-specific language dslounded box. Normally, a database is represented as a cyldomain-specific language in writinginder. Is it possible to adjust this? Yes, yodocker software downloadu can. Thsoftware architecture designis can be done by means of styles. The list ofdocker software documentation possible shapes can bdomain-specific language definitione found heresystem context diagram legend.

A style can be applied to an element by using a tag. First, in the views section, add a ssoftware architecture designtyle for an element with the tag Databadomain-specific language modelse. You apply a shape Cylinder to this element.

JSON
views {
    ...
    styles {
        element "Database" {
            shape Cylinder
        }
    }
}

Now you need to add a tag to the corresponding contadocker software licenseiner. When you define a container, you need to define it with tsystem context diagramhe following format: codocker software documentationntainer [description] [technology] [tags].

In the contdocker software toolainer definition, you did not specify the technodocker software toollogy. There are two options here:

  • Add a technology to the container. This idocker software management tools a bidomain-specific language in writingt error-prone, as you have to know the format by heart and you can simply forget to add the technology.domain-specific language dsl
  • Set the tags explicitly. This is tsoftware architecture patterns pdfhe one chodocker software download for windowssen here.
JSON
webshopDatabase = container webshopDatabase "The webshop database" {
    tags "Database"
}

The complete DSL can be found on GitHub. The resulting diagram is the following.

Conclusidomain-specific language dslon

Structurizr helps ysystem context diagram templateou with creating didomain-specific language modelagrams according to the C4 model. The diagramssoftware architecture patterns pdf are created by means of a DSL whichdomain-specific languages pdf has several advantages. You need to learn the Dsystem context diagram templateSL of course, but this can be learneddocker software management tool quite easily.