Structurizr: Architecture Modelling as Code · Architecture as Code: the course

All courses / Architecture as Code / Module 2 / Chapter 6

Learning objectives

After the lesson the participant can:

Describe the four levels of the C4 model and the audience of each.
Explain why generating views from a single model prevents diagram decay.
Draft the structure of a workspace with people, software systems, containers and views.
Choose between Structurizr, Mermaid, PlantUML and drag-and-drop tools for a given scenario using the chapter's recommendation matrix.

Key concepts

C4 model: A hierarchical approach to software architecture diagrams with four levels: System Context, Container, Component and Code. Each successive level narrows the audience and scope, and the Code level is optional.
Diagram decay: The gradual divergence between architecture diagrams and the systems they represent when updates rely on manual effort. Model-based tooling answers it by generating diagrams from a single source of truth.
Workspace: model and views: A Structurizr workspace holds a model of people, software systems, containers, components and relationships, and a set of views that define which diagrams are generated from it. One model yields many consistent views.
DSL and workspace JSON: The DSL holds the model and view definitions, while the JSON file saved by the diagram editor holds the manual layout. Both are committed, so a diff on the JSON shows when an element moves.
Governance patterns for enterprise workspaces: A sequence for large workspaces: a domain folder structure, intent-revealing include files, centrally enforced naming conventions, documented relationship expectations and local validation before review.

Interactive exercises

Do them here and get feedback at once. Choose a card and then where it belongs, or drag it.

Interactive exercise 1 · Match

Structurizr commands and workspace features

Match each command or workspace feature to what the chapter says it does.

Interactive exercise 2 · Put in order

Contributing a diagram update

Put the steps of the chapter's contribution workflow for diagram updates in order.

Teaching plan

15 min	Teacher presents the C4 levels with their audiences and the reason the model fits Architecture as Code: hierarchical, technology agnostic, lightweight and composable.
15 min	Demonstration: the teacher builds a small workspace live, from person and software system to a container view, and shows the three commands local, server and export.
15 min	Teacher explains governance patterns, quality gates, the manifest digest check and the seven-step contribution workflow with dual review.
35 min	Exercise in pairs: model one system at the context and container levels and review another pair's model.
10 min	Close with the comparison tables and the recommendation matrix: when another tool is the better choice.

Discussion

The chapter's comparison gives drag-and-drop tools a lower learning curve. What does an organisation pay later for that convenience?
Why does the contribution workflow ask for dual review by a platform engineer and a product architect, and what would each miss alone?
Which capability metric from the adoption playbook would tell you earliest that modelling has become a heroic effort by one maintainer?

Written exercise

Exercise · 35 minutes

Model a system at two C4 levels

Choose a system from your own organisation. Write, in outline or in DSL, a workspace with one model: at least two kinds of people, the software system in scope, two neighbouring systems, and four to six containers with their technology and responsibilities. Describe every relationship with a verb phrase and a protocol, following the chapter's advice to document relationships. Define two views from the model, a System Context view and a Container view, and add tags that would let you filter external integrations. Finally write three naming rules a quality gate could check in the pipeline, and exchange models with another pair for review.

Deliverable: A workspace outline or DSL file with one model and two views, a list of three checkable naming rules, and the review notes from the other pair.

Your work

Self-test

Choose an answer to see whether it is right, or open the answer below each question.

Which C4 level illustrates how the software system in scope fits into its environment of users and neighbouring systems?
Show the answer
B. System Context
The System Context level shows how the system fits into its environment, highlighting users and neighbouring systems, for both technical and non-technical stakeholders.
Why does the chapter say both the DSL file and the workspace JSON belong in version control?
Show the answer
D. The DSL holds model and views, the JSON holds the manual layout
Layout changes made in the diagram editor are saved to the JSON file next to the DSL. The DSL holds the model and view definitions and the JSON the manual layout, so both are committed.
In the chapter's recommendation matrix, which tool is recommended for quick diagrams in a README?
Show the answer
A. Mermaid
The matrix recommends Mermaid for quick diagrams in a README because of native GitHub support and simple syntax, and Structurizr for large-scale system architecture and Architecture as Code practice.