What are software architecture diagrams and how does the C4 model organize them?

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.