Category: Solutions Architect

A guide to getting started with C4 diagrams and Structurizr

Discover the benefits of using Structurizr and Domain Specific Language (DSL) to create interactive and versioned C4 diagrams as code, enabling precise CA modelling and visualization for your software architecture.

Table of Contents

What are C4 diagrams?

The C4 model diagram strategy was created to establish a standard set of simple notation principals for visually documenting software architectures.

It consist of a standard set of hierarchical abstractions (software systems, containers, components, and code) that are used to create a set of hierarchical diagrams (system context, containers, components, and code). Although the code diagram is almost never created, other than from the code itself.

Each level of diagram digs deeper into the details of the systems you are trying to communicate and can be thought of as different scales on a map.

The C4 model for visualising software architecture from c4modeI.com

For detailed explanations see The C4 model for visualising software architecture

Structurizr is a toolset that helps code, manage and display C4 diagrams. This guide will help you get setup and started quickly.

You can use a variety of tools to create and conform to this diagramming standard. The key ones I have used are:

For a full list of tools see C4 model tools

Using Structurizr and Domain Specific Language (DSL)

Getting started with Visio is straight forward, just using the stencil. However, what we are after is diagrams as code, that we can version along with our design and code changes. To do this we can either use Mermaid or Domain Specific Language (DSL). DSL allows for more precise C4 modelling and Structurizr allows for creating interactive visualizations.

This is a quick getting started guide to get going locally rendering views of your models on Windows. You can read all the details and options of Structurizr and the DSL syntax at Structurizr.

Prerequisites

Setup Steps and getting started

1. Working Folder

You will need to have a folder that’s dedicated for the Structurizr C4 diagrams code and configuration files. Ideally this will be for a single domain and in your local git folders. That way you can branch, versions and commit your diagrams as versioned code.

For example: c:\gitrepos\myprojectrepo\docs\architecture\diagrams\my-domain\structurizr-data\

Note: Currently you can only have one workspace per folder, so you may need several workspaces, such as one per domain.

2. Docker setup

After you have installed Docker Desktop then the next step is to ‘pull’ (or download) the Structurizr docker image from a Docker registry, typically Docker Hub. By pulling this image, you鈥檙e downloading the necessary files to run Structurizr Lite in a Docker container on your local machine. To do this run the following command

# Pull the Structurizr docker image
docker pull structurizr/lite

The easiest way to execute these commands is from the Docker Desktop built-in Terminal. Click on the ‘>_ Terminal’ button at the bottom.

3. Create and run a container

Once the image is downloaded and ready in Docker, then from the Docker terminal run the following command in this format

docker run -it --rm -p <local port>:8080 -v "<host machine Structurizr folder>:/usr/local/structurizr" structurizr/lite

The -it option supports both:
-i (interactive) keeps the STDIN open even if not attached.
-t (tty) allocates a pseudo-TTY, which allows you to interact with the container.

The -rm option automatically removes the container when it exits, ensuring no leftover containers. You may not want to do this if you are going to run this container repeatedly and have the necessary disk space.

In this case it would be something like…

docker run -it --rm -p 8080:8080 -v "c:\gitrepos\myprojectrepo\docs\architecture\diagrams\my-domain\structurizr-data\:/usr/local/structurizr" structurizr/lite

Once you have your command line tested, it’s a good idea to put this into a readme.md file in the structurizr-data folder, so that others can easily create a server pointing to the correct folders (unless everyone uses the same root paths, they will need to adjust it for themselves, but it’s a good starter).

If you have all the paths correct then you should see a successful start and something like this in the terminal.

4. Access Structurizr Web Dashboard

Once the container is running you can now simply open a browser and navigate to http://localhost:<local port> or in our example http://localhost:8080

A default Structurizr workspace will be automatically created for you. It will look like this…

and a corresponding set of file and folders will be added to your folder.

It’s the workspace.dsl that you will be editing to define your architectural model and how it should be visualized.

Quick-start on modelling using DSL

workspace.dsl

The workspace.dsl file is a text-based domain-specific language (DSL) file used to define a software architecture model based on the C4 model. This file allows you to describe the elements of your software system, their relationships, and how they should be visualized. Here are some key components:

  • Model Definition: Defines the people, software systems, containers, components, and their relationships.
{
    "model": {
        "people": [
            {
                "id": "1",
                "name": "User",
                "description": "A user of my software system."
            }
        ],
        "softwareSystems": [
            {
                "id": "2",
                "name": "Software System",
                "description": "My software system."
            }
        ],
        "relationships": [
            {
                "sourceId": "1",
                "destinationId": "2",
                "description": "Uses"
            }
        ]
    }
}
  • Views: Specifies how the elements should be visualized in different diagrams (e.g., system context, container, component diagrams).
{
    "views": {
        "systemContextViews": [
            {
                "softwareSystemId": "2",
                "description": "System Context diagram for Software System",
                "elements": [
                    { "id": "1" },
                    { "id": "2" }
                ],
                "automaticLayout": true
            }
        ],
        "styles": {
            "elements": [
                {
                    "tag": "Software System",
                    "background": "#1168bd",
                    "color": "#ffffff"
                },
                {
                    "tag": "Person",
                    "shape": "person",
                    "background": "#08427b",
                    "color": "#ffffff"
                }
            ]
        }
    }
}

workspace.json

Both files serve the same purpose but cater to different use cases. The DSL file is more human-readable and easier to write manually, while the JSON file is better suited for automated processing and integration with other tools.

The web app, Structurizr Lite generates and maintains this file and you should very rarely need to view or update this file manually.

.structurizr folder

The .structurizr folder is a directory used by Structurizr to store various configuration and data files related to your workspace such as images, other assets, logs and temporary files used during operations. This is managed by the app should not be interferred with 馃槈

Tips for building you model

Add a title and description to your workspace

workspace "Model Title Here" "Add a description of the model here" {

    model {
    ...
    }
    views {
    ...
    }
    configuration {
    ...
    }

Set Identifiers as hierarchical

By default, all identifiers are treated as being globally scoped, however by using the !identifiers keyword you can specify that element identifiers should be treated as hierarchical (relationship identifiers are unaffected by this setting).

workspace {

    !identifiers hierarchical

    model {
        softwareSystem1 = softwareSystem "Software System 1" {
            api = container "API"
        }

        softwareSystem2 = softwareSystem "Software System 2" {
            api = container "API"
        }
    }
}

So now each api can have the same local name, but be referenced softwareSystem1.api and softwareSystem2.api respectively.

see Identifiers | Structurizr

Add your users/personas at the top

Syntax

person <name> [description] [tags] {
    // Define properties and relationships here
}

Example

model {
        customer = person "Online Shopping Customer" "A customer"
        picker = person "Picker" "A warehouse picker" "Warehouse"
        whmanager= person "Warehouse Manager" "A warehouse manager" "Warehouse"
        despatcher = person "Despatch Operator" "A warehouse despatcher" "Warehouse"
        ...

Then your high level systems

In Structurizr DSL, the softwareSystem element is used to define a software system within your architecture model. A software system represents a major part of your overall system, typically encompassing multiple containers and components.

Syntax

softwareSystem <name> [description] [tags] {
    // Define properties and relationships here
}

Example

webapp= softwaresystem "Store Web App" "The main web store" "Existing System"
email = softwaresystem "E-mail System" "The internal Microsoft Exchange e-mail system." "Existing System"
atm = softwaresystem "ATM" "Allows customers to withdraw cash." "Existing System"

Use Groups

The group element is used to define a named grouping of elements, which will be rendered as a boundary around those elements. This is useful for organizing and visually separating different parts of your architecture model.

Example

workspace {
    model {
        group "Company 1" {
            a = softwareSystem "System A" "Description of System A."
        }
        group "Company 2" {
            b = softwareSystem "System B" "Description of System B."
        }
        a -> b "Uses"
    }
    views {
        systemLandscape {
            include *
            autoLayout lr
        }
        styles {
            element "Group" {
                color #ff0000
            }
        }
    }
}

Use the Azure or other custom themes

The theme element is used to apply a set of predefined styles to your diagrams and is used in the views section. Themes help you maintain a consistent look and feel across your diagrams, especially when using common visual styles for elements and relationships.

Syntax

theme <url>

Example of the Azure theme

Here I have also added some shapes that get overridden by the Azure theme.

views {
        // theme default
        themes https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json
        // https://structurizr.com/help/theme?url=https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json
        styles {
            element "Database" {
                shape "cylinder"
            }
            element "Person" {
                shape "Person"
                background "#08427b"
                color "#ffffff"
            }
            element "Software System" {
                background "#1168bd"
                color "#ffffff"
            }
        }
        ...

For more themes see Themes | Structurizr

Allow manual layout in Structurizr Lite

The autolayout element is used to automatically arrange the elements in a view, making it easier to create well-organized and visually appealing diagrams without manually positioning each element.

Syntax

autolayout [direction] [rankSeparation] [nodeSeparation]
  • Direction: Specifies the direction of the layout. Possible values are:
    • lr (left to right)
    • rl (right to left)
    • tb (top to bottom)
    • bt (bottom to top)
  • Rank Separation: (Optional) Specifies the separation between ranks (levels) in the layout. Default is 300.
  • Node Separation: (Optional) Specifies the separation between nodes (elements) in the layout. Default is 300

When you add this to a view definition, you will not be able to manually reposition the shapes in the GUI. Just remove or remark the line to allow it.

views {        
       systemLandscape "SystemLandscape" {
            include *
            // autolayout lr
        }

        systemContext eCommerceSystem "SystemContext" {
            include *
            autolayout lr
        }
        ...

Here the SystemLandscape is manually arranged and the eCommerceSystem is arrange left-to-right.

Notes, Examples and References

Cloud Resource Naming Convention (Azure)

In any organisation it is important to get a standard naming convention in place for most things, but especially with cloud-based resources.

As many types of cloud resources require globally unique names (due to platform DNS resolution), it’s important to have a strategy that will give you a good chance of achieving global uniqueness, but also as helpful as possible to human beings, as well as codifiable in DevOps CD pipelines.

Continue reading “Cloud Resource Naming Convention (Azure)”

Resource Tag management in Microsoft Azure

Adding tags to resources in Azure is generally a good idea. This helps administrators manage billing, knowing what things are and when they can be safely decommissioned etc..

I have includes here some guidance and useful scripts for adding tags and managing tags on resources and resource groups.

Continue reading “Resource Tag management in Microsoft Azure”

My Microsoft Azure Certification Revision Sheets

I finally successfully passed the three exams necessary to certify as a Microsoft MCSD: Azure Solution Architect (now becoming the MCSE: Cloud Platform and Infrastructure). \o/

  • Exam 70-532: Developing Microsoft Azure Solutions
  • Exam 70-533: Implementing Microsoft Azure Infrastructure Solutions
  • Exam 70-534: Developing Microsoft Azure Solutions

It was no easy feat, not least because of the absolutely massive number of topics that you need to learn, but also that Microsoft decided to update the syllabus’s of all three exams just as I was ready to take them (Nov/Dec 2016). Continue reading “My Microsoft Azure Certification Revision Sheets”

How to reset your Remote desktop user account expiry date on your Azure cloud service

If you have not re-deployed your azure cloud service for a while you might just find that your remote access account has expired. Here is a simple way to push out the expiry date without re-deploying.

  1. Login to the Azure Management Console ( https://manage.windowsazure.com ), navigate to you cloud service and select the configure tab
  2. Download the configuration and save to a local temp area.
  3. Open it up in notepad
  4. Find the setting that looks like
    <ns0:Setting name=”Microsoft.WindowsAzure.Plugins.RemoteAccess.AccountExpiration” value=”2013-09-07T23:59:59.0000000+01:00″ />
  5. Just change the year to sometime in the future e.g. 2016 and save.
  6. Then from the same configure page in the Azure management console, upload the config file.
  7. Wait a few minutes while the file is process and voila! you can now log in. Of course you must know the original password and usename you used when you last deployed.

Why Cloud Based Email Hosting is the Better Option for Business Email

Hosting your corporate or business email in-house on an exchange server can entail several
risks. After all, buildings, businesses and even people have no guarantee of always remaining
safe. Fires, tornadoes, hurricanes and earthquakes happen all the time, and severe damage
occur to both homes and businesses. If the building where you house your exchange server was
ever damaged as a result of flood, fire, or any other natural disaster, your server would also be
damaged. OK, so let’s say you are never hit by a natural disaster, you are one of the lucky ones.
Still, having an on-site exchange server implies a great responsibility – you must have the latest
firewall implementation, your IT personnel has to be trained in the latest security measures, and
you constantly have to update these skills to prevent hacker or phishing infiltration.

Is there a Better Solution?

Of course there is! A more cost efficient and safer solution to operating your email system
in a cloud based email infrastructure. Cloud computing is the latest in technology, and many
businesses are opting to sub-contract their email services to a cloud based email server because
of all the benefits this affords.

What is Cloud Computing?

Cloud is the latest hosting technique and is used for a number of business and personal services,
among which is email hosting. This has become a better option for storing confidential data like
email because the data resides in a central location that is off premises. So while your physical
location may be in Texas your cloud email infrastructure could be held in New York. Even then,
when you partner with a Cloud email hosting service, they usually back up your information to a
secondary cloud location, just to make sure the cloud location is not affected by a natural disaster
either.

The Benefits

Traditional email server exchange hosting requires a dedicated server and the installation of
Microsoft Exchange server software. This implies a substantial business cost, often running
into the thousands of dollars. On the other hand, when you associate with a cloud based email
infrastructure partner, most of these costs are absorbed by the associated company and you share
the costs of the server and Microsoft exchange with other users.

Additionally, the outsourcing of your email servers means you can use your IT department
personnel more efficiently, placing them on tasks that influence the actual running of your
business and not on the management of your email systems.

Is this Safe?

While email is certainly confidential and you may be concerned about trade secrets, most of
these are not carried over email information. Additionally, Cloud email hosting services offer the
highest of encryption services, often compared to that used by military departments. This means

your email is kept as safe as possible and hackers, phishing experts and fraudsters are unable to
access these email databases.

Back Ups

By contracting an external cloud based email service you no longer have to worry about back
up issues. Your new service provider offers this task within its service contract. Backups
are performed automatically and kept available for a period of time (based on the contract
specifications).

Bottom Line

There is a valid reason for the turning of many companies to cloud based hosting of email
services. Primarily, these involve more safety but also lower costs. It is a more streamlined and
functional way of keeping your email system working efficiently.

Checkout the offering from SendGrid at聽http://sendgrid.com/