Over the past few years I have drawn many Architecture diagrams in a variety of tools like drawio, visio, Lucid Chart, etc. and always found there were many hours spent doing rework and updates.

I generally draw diagrams using the C4 model for detailed architecture but still would have drawn them by hand and totally forgetting about the fact there is a lot of support for building diagrams as code. First time I looked at the C4 model I used code to draw diagrams, so why had I not been using it? to be honest I have no idea why, but it’s definitely time to embrace it again.

If you are not familiar with the C4 model I suggest you checkout the website and I recommend Simon Brown’s books on Software Architecture for Developers, which is available on Leanpub.

Getting Started

So, I recently embarked on creating diagrams as code using the C4 model and Structurizr. First thing is create a free account on Structurizr to get started.

I now needed to decide what to language to use for my diagram as code. Structurizr supports a number of languages for authoring, Java, .NET, TypeScript, PHP, Python, Go and of course its own DSL. I choose the Structurizr DSL for my diagram as it looked easy enough. For editing the code I used Visual Studio Code and an extension for code highlighting by Ciaran Treanor. The DSL demo page and language reference were really helpful to get started as well as the examples.

Building architecture diagrams using the C4 model is great and using the DSL made it easy to build my diagram quite quickly and using the demo page I could see what my diagram was going to look like.

Publish

Having created my diagram as code and added it to source control, I now needed to push my diagram to my Structurizr workspace. Structurizr has a CLI that you can use to do this.

structurizr-cli push -id <my workspace> -key <workspace key> -secret <workspaceSecret> -workspace mydiagram.dsl

The details for the workspace can be found on your Structurizr page by selecting ‘Show more’.

The CLI has other features including exporting to different formats e.g. Mermaid (for more details on the supported outputs see the website)

structurizr export -workspace mydiagram.dsl -format mermaid

Having published my diagram to my workspace, it would be really good to automate this process so any changes to the diagram get pushed.

Currently I am using Azure Pipelines a lot, so it seemed fitting to create this process using Azure Pipelines YAML.

Building the Pipeline

This should be straight forward, I just need to perform the same steps as I did locally to push my diagram to Structurizr.

The build pipeline automatically checkouts my code from my repo so that step is done for me. The Microsoft Build Agents already have HomeBrew installed so that makes installing the CLI simple.

- bash: |
    brew install structurizr-cli
  displayName: 'Install Structurizr'

Pushing to Structurizr needs a number of parameters which should be kept secret so adding them as secure variables in the Pipeline is one solution.

- bash: |
    structurizr-cli push -id $(workspaceId) -key $(workspaceKey) -secret $(workspaceSecret) -workspace $(workspaceFile)
  displayName: 'Push Diagram to Structurizr'

Enhancing the Pipeline

The diagram has been updated in Structurizr but I now usually need images to add to a presentation or documentation. I could go to Structurizr and export the images for each diagram by hand but that takes time and is not helpful is someone else needs them.

Fortunately there are some examples of how to do this using Puppeteer with Structurizr on GitHub which is great and the export of private diagrams worked out of the box with no modification.

The pipeline can be updated now to Install Puppeteer

- bash: |
   npm install puppeteer 
  displayName: 'Install Puppeteer'

And get the example from the Structurizr/Puppeteer repo

- bash: |
    git clone 'https://github.com/structurizr/puppeteer.git'
  displayName: "Get Structurizr Puppeteer"    

Using the example and providing the required details, png files can now be exported.

- bash: |    
    cd $(Build.ArtifactStagingDirectory)
    node $(System.DefaultWorkingDirectory)/puppeteer/export-private-diagrams.js $(workspaceUrl) $(workspaceUsername) $(workspacePassword) png $(workspaceId)
  displayName: 'Export Diagram from Structurizr'

Or svg files.

- bash: |    
    cd $(Build.ArtifactStagingDirectory)
    node $(System.DefaultWorkingDirectory)/puppeteer/export-private-diagrams.js $(workspaceUrl) $(workspaceUsername) $(workspacePassword) svg $(workspaceId)
  displayName: 'Export Diagram from Structurizr'

The images are outputted to the ArtifactStagingDirectory and can now be published as an artifact.

- publish: '$(Build.ArtifactStagingDirectory)'
  displayName: Publish Diagrams
  artifact: 'mydiagrams'

The artifacts will be individual files and so it might be easier to zip them for easier download from Azure Pipelines using the ArchiveFiles task.

 - task: ArchiveFiles@2
   inputs:
      rootFolderOrFile: '$(Build.ArtifactStagingDirectory)'
      archiveFile: '$(Build.ArtifactStagingDirectory)/diagrams.zip' 
 - publish: '$(Build.ArtifactStagingDirectory)/diagrams.zip'
   displayName: Publish Diagrams
   artifact: 'mydiagrams'

Final Pipeline

Putting all that together, my final pipeline looks like this:

trigger: 
- main

pr: none

variables:
  workspaceFile: 'mydiagram.dsl'
  isMain: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')]

jobs:
  - job: UpdateArchitecture
    displayName: Update Architecture
    condition: and(succeeded(), eq(variables.isMain, true))
    pool:
      vmImage: ubuntu-18.04
    steps:
      - bash: |
          brew install structurizr-cli
          brew info structurizr-cli
        displayName: 'Install Structurizr'
      - bash: |
          npm install puppeteer 
        displayName: 'Install Puppeteer'
      - bash: |
          git clone 'https://github.com/structurizr/puppeteer.git'
        displayName: 'Get Structurizr Puppeteer'
      - bash: |
          structurizr-cli push -id $(workspaceId) -key $(workspaceKey) -secret $(workspaceSecret) -workspace $(workspaceFile)
        displayName: 'Push Diagram to Structurizr'
      - bash: |    
          cd $(Build.ArtifactStagingDirectory)
          node $(System.DefaultWorkingDirectory)/puppeteer/export-private-diagrams.js $(workspaceUrl) '$(workspaceUsername)' '$(workspacePassword)' png $(workspaceId)
        displayName: 'Export Diagram from Structurizr'
      - publish: '$(Build.ArtifactStagingDirectory)'
        displayName: Publish Diagrams
        artifact: 'mydiagrams'

Final Thoughts

I started on a journey to automate building architecture diagrams and export the images and this satisfies todays need but in the future I may need to enhance the pipeline to push the images to another system or export them in to another format.

I will certainly be using this article to remind me about diagrams as code, I hope you consider diagrams as code for you own needs and that this has been useful to share.

Happy diagramming.