Structurizr Site Generatr

A static site generator for C4 architecture models created with Structrizr DSL. See Background for the story behind this tool.

Click here to see an example of a generated site. This site is generated from the example workspace in this repository. This example is based on the Big Bank plc example from https://structurizr.com.

Features

Generate a static HTML site, based on a Structurizr DSL workspace.
Generates diagrams in SVG, PNG and PlantUML format, which can be viewed and downloaded from the generated site.
Start a development server which generates a site, serves it and updates the site automatically whenever a file that's part of the Structurizr workspace changes.
Include workspace-level documentation (in Markdown format) in the generated site.
Include system-level ADR's in the generated site.
Include static assets in the generated site, which can be used in ADR's and workspace-level documentation.
Generate a site from a Structurizr DSL model in a Git repository. Supports multiple branches, which makes it possible to for example maintain an actual state in master and one or more future states in feature branches. The generated site includes diagrams for all configured branches.
Include a version number in the generated site.

Installation

You can install structurizr-site-generatr using Homebrew:

brew tap avisi-cloud/tools
brew install structurizr-site-generatr
structurizr-site-generatr --help

Docker image

You can also use the Docker image:

docker pull ghcr.io/avisi-cloud/structurizr-site-generatr:<version>
docker run -it --rm ghcr.io/avisi-cloud/structurizr-site-generatr:<version> --help

Replace <version> with the version you want to use.

Verify image with cosign

cat cosign.pub
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzezKl0vAWSHosQ0JLEsDzNBd2nGm
08KqX+imYqq2avlbH+ehprJFMqKK0/I/bY0q5W9hQC8SLzTRJ9Q5dB9UiQ==
-----END PUBLIC KEY-----
cosign verify --key cosign.pub ghcr.io/avisi-cloud/structurizr-site-generatr:<version>

Replace <version> with the version you want to verify.

Example usage

These examples use the example workspace in this repository.

Start a development server

structurizr-site-generatr serve --workspace-file docs/example/workspace.dsl

Generate a site from a Git repository

structurizr-site-generatr generate-site \
    --git-url https://github.com/avisi-cloud/structurizr-site-generatr.git \
    --workspace-file docs/example/workspace.dsl \
    --branches main \
    --default-branch main

Background

At Avisi, we're big fans of the C4 model. We use it in many projects, big and small, to document the architecture of the systems and system landscapes we're working on.

We started out by using PlantUML, combined with the C4 extension. This works well for small systems. However, for larger application landscapes, maintained by multiple development teams, this lead to duplication and inconsistency across diagrams.

To solve this problem, we needed a model based approach. Rather than maintaining separate diagrams and trying to keep them consistent, we needed to have a single model, from which diagrams could be generated. This is why we started using the Structurizr for Java library. About a year later, we migrated our models to Structurizr DSL.

We created custom tooling to generate diagrams and check them in to our Git repository. All diagrams could be seen by navigating to our GitLab repository. This is less than ideal, because we like to make these diagrams easily accessible to everyone, including our customers. This is why we decided that we needed a way of publishing our models to an easily accessible website.

This tool is the result. It's still a work in progress, but it has already proven to be very useful to us.

julrichkieffer / structurizr-site-generatr