Technical Documentation Sites

Your team may wish to create a technical documentation website in order to provide a public documentation reference point consistent with GOV.UK’s Design System. This can contain any content required, examples include:

How to access support
Architecture documentation
Onboarding guides
A site for Community-of-Practise documentation

There is a Middleman template which enables this. You can find examples of its usage and site setup.

This page covers adding architectural diagrams using the C4 model. Once your site is running and deploying, then come back here to continue adding C4 diagrams.

Architecture diagrams - the C4 model

The C4 model is a diagrams-as-code option used within the DfE for visualising architectural design. An advantage of the C4 model is that multiple different levels of abstraction (like zoom levels of a map) can be generated from one file.

A summary of the levels follows, with each taking a more concrete and less abstract view of the system as we go down the list:

Level 1 - Context - consisting of the system landscape and context diagrams, this level focuses on the interactions between high level systems, users, organisations and personas. It is suitable for a non-technical audience.
Level 2 - Containers - shows the interactions between containers (databases, web apps, file system, etc). Intended for technical people inside and outside of the development team; including software architects, developers and operations/support staff.
Level 3 - Components - this level of diagram breaks containers into their structural components, e.g. individual data access components and domain services.
Level 4 - Code - this is generated by existing tooling - typically IDEs - which will output UML class diagrams, entity relationship diagrams or similar.

There are supplementary diagram types available, such as the Deployment diagram type to illustate the deployment environments.

For further guidance on the C4 model, visit here.

Adding C4 generation to the Tech Docs template

Prerequisites: you have some C4 diagrams-as-code ready to publish, and your technical documentation site is already using GitHub Actions to publish to AKS.

The structurizr.com website provides a SaaS offering to generate diagrams from this code. There is a Free Tier Cloud offering available which allows for one workspace to be created (feature comparison).

The approach will be to store the C4 code within the repository of the technical documentation site, and to modify GitHub Actions steps to automate the diagram export (render) to PNG from structurizr.com.

Generating the diagrams

Firstly we must set up the Cloud Account for structurizr usage from GitHub Actions:

Sign up for a free Cloud account at structurizr.com (prefereably with a mailbox/service user, not a personal address).
Create an empty workspace. This will be used by the build process to automate image export.
Aquire the following configuration settings and put them in to your repository’s secrets:

Secret Key	Secret Value
STRUCTURIZR_USERNAME	Website login username
STRUCTURIZR_PASSWORD	Website login password
STRUCTURIZR_WORKSPACE_ID	Workspace ID to upload the work space file (`<repo>/<diagrams-directory>/workspace.dsl`) into as part of build
STRUCTURIZR_API_KEY	API key of workspace
STRUCTURIZR_API_SECRET	API secret of workspace

All the workspace-related settings (workspace ID, API key and API secret) can be found in the ‘Settings’ page of the workspace.

Next we must setup the GitHub Actions to publish:

Copy the automation script to <repository-root>/source-c4-diagrams/export-private-cloud-diagrams.js.

Modify your GitHub Actions file to include the following step before the middleman build is invoked, and after checkout:

- name: Upload and publish C4 diagrams
  run: |
    mkdir ./screenshots
    chmod -R 777 ./screenshots
    docker run --rm -v $(pwd):/usr/local/structurizr structurizr/cli push -id ${{ secrets.STRUCTURIZR_WORKSPACE_ID }} -key ${{ secrets.STRUCTURIZR_API_KEY }} -secret ${{ secrets.STRUCTURIZR_API_SECRET }} -workspace ./source-c4-diagrams/workspace.dsl
    docker run --shm-size 1G --rm -v $(pwd)/source-c4-diagrams/export-private-cloud-diagrams.js:/app/index.js -v $(pwd)/screenshots:/screenshots alekzonder/puppeteer:latest node index.js "https://structurizr.com" "${{ secrets.STRUCTURIZR_USERNAME }}" '${{ secrets.STRUCTURIZR_PASSWORD }}' png ${{ secrets.STRUCTURIZR_WORKSPACE_ID }}
    cp ./screenshots/structurizr-${{ secrets.STRUCTURIZR_WORKSPACE_ID }}-SystemLandscape.png ./source/architecture/context/images/SystemLandscape.png
    cp ./screenshots/structurizr-${{ secrets.STRUCTURIZR_WORKSPACE_ID }}-AcademyTransfersSystem-SystemContext.png ./source/architecture/context/images/SystemContext.png
    cp ./screenshots/structurizr-${{ secrets.STRUCTURIZR_WORKSPACE_ID }}-AcademyTransfersSystem-Container.png ./source/architecture/containers/images/Containers.png
    cp ./screenshots/structurizr-${{ secrets.STRUCTURIZR_WORKSPACE_ID }}-AmazonWebServicesDeployment.png ./source/architecture/deployment/images/Deployment-Live.png

Step-by-step, this script:

Creates a directory for the diagrams to land in (screenshots), then utilizes the structurizr/cli image to upload the ./source-c4-diagrams/workspace.dsl file in to the previously created workspace identified by ID STRUCTURIZR_WORKSPACE_ID.

A puppeteer automation script is used to automate a headless browser to log in to the cloud service and export the diagrams.

Finally, the exported files are copied in to their correct positions in the check-out repository file system - ready for the Middleman build process.

Commit, push and then run a build. Make a note of the generated file names (workspace ID will be redacted with asterix) and make any necessary amends to the GitHub Actions cp lines to copy the files defined in your C4 workspace to the correct place in the tech docs directory structure you have defined for your site.