structurizr.com No paid content found

Software architecture diagrams are visual representations of a system's structure: the people who use it, the software systems it depends on, the applications and data stores inside it, and how those parts communicate. The C4 model organizes these diagrams into a small set of zoom levels — system landscape, system context, container, component, dynamic, and deployment — so each diagram answers a different question for a different audience. Tools such as Structurizr generate all of these diagrams from a single text-based model, which keeps them consistent instead of letting separate drawings drift apart.

Why architecture diagrams need a shared structure

A single "architecture diagram" rarely serves everyone. An executive wants to know which systems exist and who uses them. A developer joining a team wants to know which services and databases make up one application. An operations engineer wants to know where those services run.

Without a defined set of levels and notation, teams end up with a folder of drawings that use different shapes, labels, and boundaries for the same things. Readers then have to relearn the notation on every diagram, and the diagrams quietly disagree with each other as the system changes.

The C4 model addresses this by fixing the levels and the element types, so a box means the same kind of thing wherever it appears.

The C4 model levels

The first four levels are the core hierarchy; dynamic and deployment diagrams are supplementary views that reuse the same elements.

How one model produces many diagrams

The key idea behind a model-as-code tool is that you describe the elements and relationships once, then declare which views to render. Structurizr, created by Simon Brown, the author of the C4 model, works this way using Structurizr DSL.

A minimal workspace looks like this:

workspace {
    !identifiers hierarchical

    model {
        u = person "User"
        ss = softwareSystem "Software System" {
            wa = container "Web Application"
            db = container "Database Schema" {
                tags "Database"
            }
        }

        u -> ss "Uses"
        u -> ss.wa "Uses"
        ss.wa -> ss.db "Reads from and writes to"
    }

    views {
        systemContext ss "Diagram1" {
            include *
        }
        container ss "Diagram2" {
            include *
        }
    }
}

The model block defines the people, systems, containers, and relationships. The views block asks for a system context diagram and a container diagram of the same system. Because both views read from the same elements, adding a container or changing a relationship updates every diagram that includes it — there is no second drawing to edit.

Structurizr describes itself as the original tool for the C4 model and the reference implementation, which matters if you want your diagrams to stay compatible with the model's rules.

Diagram conventions worth keeping

• A key or legend. Structurizr generates a diagram key automatically, so readers can decode shapes and colors without a separate document.
• Consistent notation. The same element type uses the same visual treatment across every view.
• Interactivity. Diagrams can be zoomed, animated to show a flow, and embedded in other pages.
• Themes. Prebuilt themes exist for AWS, Microsoft Azure, Google Cloud Platform, Oracle Cloud Infrastructure, and Kubernetes, so cloud elements render with recognizable icons.
• Alternative visualizations. Beyond the standard diagrams, Structurizr offers tree views and interactive force-directed graphs for exploring the model.

Common pitfalls and how model-based generation avoids them

Diagram drift. When diagrams are drawn by hand, the code changes and the drawings don't. A model-based approach keeps a single source of truth, so a diagram is only out of date if the model is.

Inconsistent notation. Hand-drawn diagrams tend to invent new shapes and colors. Enforcing C4 element types removes that choice.

Wrong level for the audience. Showing container-level detail to a non-technical stakeholder loses them. The C4 levels give you a deliberate way to pick the right zoom.

No path for AI assistance. Text-based models are easy for AI agents and LLMs to parse and generate. Structurizr notes that its model-based consistency and enforcement of C4 rules make it a good fit for generating C4 diagrams with AI, and it provides an MCP server for DSL validation, parsing, and inspection.

Where to start

If you want to try the approach, the Structurizr DSL tutorial and the "Try it" option on the site let you build a small model and see the resulting diagrams. Start with a system context diagram for one system, add containers only when a reader needs that detail, and let the views do the rest.

Structurizr is a "models as code" tool for visualising, documenting, and exploring software architecture. You write Structurizr DSL to define a single model of your system, and from that one model it generates multiple software architecture diagrams following the C4 model. It was created by Simon Brown, the author of the C4 model, and remains the reference implementation — which makes it the strongest choice if C4 compliance and compatibility matter to you.

How the models-as-code approach works

Instead of drawing diagrams by hand, you describe your architecture as text. The model holds the elements (people, software systems, containers, components) and the relationships between them. Views then select what to show. Because every diagram is derived from the same model, the diagrams stay consistent with each other.

The Structurizr DSL example from the site shows this directly:

workspace {
    !identifiers hierarchical

    model {
        u = person "User"
        ss = softwareSystem "Software System" {
            wa = container "Web Application"
            db = container "Database Schema" {
                tags "Database"
            }
        }

        u -> ss "Uses"
        u -> ss.wa "Uses"
        ss.wa -> ss.db "Reads from and writes to"
    }

    views {
        systemContext ss "Diagram1" {
            include *
        }

        container ss "Diagram2" {
            include *
        }

        // styling...
    }
}

This single set of elements and relationships produces two diagrams. Add more views and you get more diagrams without redefining the underlying architecture.

The C4 diagram types Structurizr supports

Structurizr is specifically designed to support the C4 model for visualising software architecture. The diagram types listed on the site are:

• System Landscape diagram
• System Context diagram
• Container diagram
• Component diagram
• Dynamic diagram
• Deployment diagram

Diagrams are interactive (for example, zoom in and out), animatable, embeddable, and include an automatically generated diagram key/legend.

Why model-based consistency matters

When diagrams are drawn separately, they drift apart — a box renamed in one diagram keeps its old name in another. Structurizr avoids this by enforcing the C4 model rules against a single model. Every view is a projection of the same elements and relationships, so a change in the model propagates to all diagrams that include it.

This consistency is also what makes the tool AI-friendly. AI agents and LLMs excel at generating text, and Structurizr's model-based consistency and enforcement of C4 rules make it a good fit for teams generating C4 diagrams with AI. The text-based format is easy for agents to parse, enabling use cases such as AI summaries, queries, and detecting architectural drift. The Structurizr MCP server provides DSL validation, parsing, and inspection tools to assist with creating models.

Documenting and exploring beyond the standard diagrams

• Cloud architecture themes: prebuilt themes exist for Amazon Web Services, Microsoft Azure, Google Cloud Platform, Oracle Cloud Infrastructure, and Kubernetes, so you can document cloud architecture with recognisable icons.
• Alternative visualisations: tree views and interactive force-directed graphs let you explore the architecture from other angles.
• Supplementary documentation: you can publish documentation such as a "software guidebook" alongside the diagrams.

Where to start

1. Read the Structurizr DSL tutorial to learn the syntax.
2. Try it to write a small model and see the generated diagrams.
3. Define your own workspace: model your people, software systems, containers, and components, then add views for the diagram types you need.

If you want a single source of truth that produces consistent, interactive C4 diagrams — and you're comfortable describing architecture as code — Structurizr is built for exactly that. If your team prefers drawing tools over text, the models-as-code workflow will be the main adjustment.

The C4 model is a lightweight way to describe and diagram software architecture at four levels of zoom: system context, container, component, and code. It exists so that different audiences — from non-technical stakeholders to developers — can look at the same architecture at the level of detail they actually need, instead of one crowded box-and-line diagram that tries to serve everyone. You should use it when you need to communicate how a system fits into its environment and how it is built internally, without committing to a heavy formal notation.

The four levels

The name "C4" comes from the first letter of each level. Each level answers a different question and targets a different audience.

| Level | Shows | Typical audience | Key question it answers | |---|---|---|---|---| | System Context | Your system as a single box, plus the users and other systems it interacts with | Everyone, including non-technical stakeholders | How does this system fit into the world around it? | | Container | The separately deployable/runnable units inside the system (web app, database, service, etc.) and how they talk | Technical people, architects, developers, operations | What are the major building blocks and how do they communicate? | | Component | The components inside a single container and their relationships | Developers and architects | How is this container structured internally? | | Code | Classes, interfaces, and other implementation-level detail | Developers, and usually only for the most important parts | How is this component implemented? |

A useful way to think about it: context is for the whole team and beyond, container is for the technical team, component is for the developers of that container, and code is optional detail you add only where it earns its keep.

Why the levels matter

The main value is abstraction discipline. Informal architecture sketches often mix levels — a database box sitting next to a class, or a user drawn beside a message queue — which makes the diagram ambiguous and hard to read. The C4 model forces you to pick a level and stay there, so each diagram has a clear, consistent meaning.

It also separates structure from notation. The model describes elements (people, software systems, containers, components) and the relationships between them. How you draw them is a rendering choice, not part of the model itself.

One model, many diagrams

A defining property of the C4 model is that the diagrams are views over a single underlying model, not four independent drawings. You define the elements and relationships once, then generate each diagram from that shared model.

This is what Structurizr — the "models as code" tool created by Simon Brown, the author of the C4 model — is built around. You write Structurizr DSL to define the model, and the same model produces multiple diagrams. A minimal example from the project's own documentation:

workspace {
    model {
        u = person "User"
        ss = softwareSystem "Software System" {
            wa = container "Web Application"
            db = container "Database Schema" {
                tags "Database"
            }
        }
        u -> ss "Uses"
        u -> ss.wa "Uses"
        ss.wa -> ss.db "Reads from and writes to"
    }
    views {
        systemContext ss "Diagram1" {
            include *
        }
        container ss "Diagram2" {
            include *
        }
    }
}

Here one set of elements and relationships produces both a system context diagram and a container diagram. Because the diagrams share a model, they stay consistent with each other — change a relationship once and every affected view reflects it. Structurizr also generates the standard C4 diagram types (system landscape, system context, container, component, dynamic, and deployment), and its diagrams are interactive, animatable, and embeddable, with an automatically generated key/legend.

Common pitfalls

• Over-detailing the code level. The code level is the most expensive to maintain and the quickest to go stale. Most teams draw context, container, and component diagrams and add code-level detail only for components where it genuinely helps.
• Mixing abstraction levels. Don't put a class next to a system, or a database next to a person. If you find yourself wanting to, you probably need a second diagram at a different level.
• Treating diagrams as the source of truth. If the diagrams are hand-drawn separately, they drift. Generating them from a single model is what keeps them honest.
• Drawing everything. Not every container needs a component diagram, and not every component needs a code diagram. Diagram what communicates something.

Where to go next

If you want to try the model hands-on, Structurizr provides a DSL tutorial and a browser-based playground, and its text-based format is designed to be easy for both humans and AI agents to parse and validate. The reference implementation is a reasonable starting point if C4-model compliance and compatibility matter to you.