C4 models as code, Simon Brown, NDC Oslo 2023

The Agony of Outdated Architecture Diagrams

We've all been there. You're trying to understand a complex system, and you finally hunt down the architecture diagrams, only to be hit with a soul-crushing realization: they haven't been updated since the project's kickoff. The diagrams show a pristine monolith, but you know for a fact that the reality is a sprawling jungle of microservices, serverless functions, and cryptic third-party integrations. The documentation lies, and the "source of truth" is now just a source of confusion.

This is the problem that Simon Brown, the creator of the C4 model, tackles in his brilliant talk from NDC Oslo 2023. While "Diagrams as Code" tools like PlantUML and Mermaid have been a huge step forward, they often have a fundamental flaw when used at scale.

The Flaw of "Diagrams as Code"

Tools like PlantUML allow us to write text that generates a diagram. This is great! We can now version control our diagrams, diff them, and embed them in our documentation pipelines.

However, they are diagram-centric. Each .plantuml file typically describes a single diagram. If you want to show the same microservice in a high-level system context view and a more detailed container view, you end up defining that microservice in two separate files.

Now, multiply that by a dozen services and five different views for each. What happens when a service is renamed? You have to hunt down and update every single file where it's mentioned. This manual effort leads to inconsistencies, and before you know it, you're right back where you started: with outdated, untrustworthy diagrams.

A Better Way: Models as Code

Simon Brown presents a powerful paradigm shift: move from "Diagrams as Code" to "Models as Code".

Instead of writing files that describe diagrams, what if we wrote a single file that describes the model of our software architecture? We define all the building blocks—the people, software systems, containers (applications, databases, etc.), and components—and the relationships between them, all in one place.

This is precisely what the open-source Structurizr DSL allows you to do.

How Structurizr Works

With the Structurizr DSL, you create a central definition of your architectural elements. It looks something like this (in pseudocode):

// Define the elements in your model
user = person "Customer" "A user of our system"
ecommerceSystem = softwareSystem "E-commerce Platform" {
  webapp = container "Web Application" "Handles user requests"
  database = container "Database" "Stores product and order info"
}

// Define the relationships
user -> webapp "Uses"
webapp -> database "Reads from and writes to"

Once you have this central model, you can create as many different views (diagrams) as you need, all from the same source of truth. You simply tell Structurizr what you want to see in a particular diagram.

// Define a System Context diagram
systemContext ecommerceSystem {
  include * // a wildcard to include all top-level elements
  autoLayout
}

// Define a Container diagram
container ecommerceSystem {
  include * // show all containers within the e-commerce system
  autoLayout
}

If you rename the "Web Application," you only have to change it in one place in the model. Every single diagram that includes it is automatically updated. Boom. Consistency restored.

The Key Benefits

1. Single Source of Truth: Your model is the truth. Your diagrams are just views of that truth.
2. Consistency Guaranteed: No more drifting between different diagrams.
3. Separation of Concerns: The model (the content) is separate from the view (the presentation). You can even render your model using different tools like PlantUML, Mermaid, or Structurizr's own tooling.
4. Full Automation: Because it's all text, you can integrate it into your CI/CD pipeline to ensure your architecture documentation is never out of date.

By treating your architecture as a model, you transform your documentation from a static, decaying artifact into a living, breathing part of your system that evolves right alongside your code.

---

Watch the full talk here:

C4 models as code - Simon Brown - NDC Oslo 2023