If you've ever tried to explain a complex software system to a new developer, a product manager, or an executive, you know how quickly diagrams turn into messy boxes and arrows that nobody agrees on. The C4 model solves that by giving teams a structured way to describe software at four levels of detail. But drawing those diagrams by hand takes time, and they get outdated fast. That's where C4 model DSL notation comes in it lets you define your architecture as text, keep it in version control, and generate consistent diagrams automatically.

This article explains what C4 model DSL notation is, how it works in practice, and how you can use it to document enterprise architecture without the usual headaches of manual diagramming.

What is the C4 model and why does it use DSL notation?

The C4 model was created by Simon Brown as a way to communicate software architecture at four zoom levels: Context, Container, Component, and Code. Each level answers a different question from "what does this system do in the business landscape?" down to "how is this specific class structured?"

A DSL (Domain-Specific Language) is a small, focused language built for one purpose. In this case, the DSL lets you describe your C4 diagrams as plain text files instead of dragging boxes around in a drawing tool. You write declarations like which systems exist, how they connect, and at which level and a rendering tool turns that into a visual diagram.

The combination matters for enterprise architecture because large organizations have hundreds of systems. Manually maintaining diagrams across all four C4 levels is impractical. A DSL-based approach keeps diagrams version-controlled, diffable, and consistent across teams.

What does C4 model DSL notation look like in practice?

Several tools support C4-style DSL notation. The most common ones are:

  • Structurizr DSL the most mature option, purpose-built for the C4 model. It has its own syntax for defining workspaces, software systems, containers, components, and relationships.
  • PlantUML with C4 extensions uses PlantUML's general-purpose diagramming DSL with C4-specific macros maintained by the community.
  • Mermaid.js supports C4 diagrams with a simpler syntax, often used directly inside Markdown files.

Each tool has trade-offs. If you're comparing Structurizr DSL against PlantUML specifically, we cover that in detail in our Structurizr DSL vs PlantUML comparison.

A simple Structurizr DSL example

Here's what a basic C4 Context diagram looks like in Structurizr DSL:

workspace "Online Store" {
  model {
    customer = person "Customer" "Buys products online"
    store = softwareSystem "Online Store" "Allows customers to browse and purchase"
    payment = softwareSystem "Payment Gateway" "Processes credit card payments"
    customer -> store "Uses"
    store -> payment "Delegates payment processing to"
  }
  views {
    systemContext store "StoreContext" {
      include
      autolayout lr
    }
  }
}

This is roughly 15 lines of text, and it generates a clean, labeled diagram. No alignment issues, no missing arrows, and it lives in your Git repo next to the code it describes.

When should an enterprise architecture team use C4 DSL notation?

C4 DSL notation works best in specific situations:

  • Your architecture changes frequently. If you're in a microservices environment where services get added or restructured every few weeks, hand-drawn diagrams are always stale. Text-based diagrams update with a pull request.
  • Multiple teams need consistent views. DSL files serve as a single source of truth. Everyone generates diagrams from the same definitions, so there are no conflicting versions floating around in Confluence.
  • You want architecture documentation close to the code. Keeping DSL files in the same repository as your application code makes it easier for developers to keep them current.
  • Compliance or audit requirements exist. Regulated industries often need traceable, version-controlled documentation. DSL-based diagrams give you that history automatically.

How do you decide between Structurizr DSL and PlantUML for C4 diagrams?

This is one of the most common questions teams ask. Both tools can produce C4 diagrams, but they approach it differently.

Structurizr DSL was designed specifically for the C4 model. It understands the hierarchy of systems, containers, components, and code elements natively. You define your model once and generate views at any level. It also supports deployment diagrams, animation, and documentation embedded alongside diagrams.

PlantUML is a general-purpose diagramming tool. Its C4 support comes through community-maintained macros. You get more flexibility (sequence diagrams, activity diagrams, etc.) but less built-in structure for C4-specific concepts. For teams already using PlantUML for other diagram types, adding C4 support means staying in one ecosystem.

For a deeper side-by-side breakdown, see our full comparison of Structurizr DSL and PlantUML for microservices.

Can you use C4 model DSL notation for cloud architecture specifically?

Yes, and many teams do. Cloud platforms like AWS, Azure, and GCP introduce their own components load balancers, managed databases, message queues, serverless functions that you need to represent at the Container level of the C4 model.

PlantUML has well-maintained libraries for cloud provider icons, making it straightforward to create cloud-specific C4 diagrams. If that's your use case, our guide on writing PlantUML syntax for cloud architecture walks through the exact syntax.

Structurizr handles cloud architecture too, though it uses a more abstract approach you describe containers and their relationships rather than naming specific AWS or Azure services directly. Some teams prefer this because it keeps the architecture model technology-agnostic. Others find it too abstract. The right choice depends on your audience.

What are the most common mistakes teams make with C4 DSL notation?

After seeing teams adopt C4 DSL tools over the past several years, a few patterns come up repeatedly:

  1. Mixing abstraction levels in one diagram. The whole point of C4 is four distinct zoom levels. If your Context diagram includes database servers and API endpoints, you've crammed three levels into one. Keep each diagram focused on its level.
  2. Over-documenting the Code level. For most enterprise architecture purposes, the Context and Container levels deliver the most value. Diving into class-level diagrams for every service creates maintenance overhead without proportional benefit.
  3. Writing DSL files but never reviewing them. Text-based diagrams only stay accurate if someone checks them. Build architecture diagram reviews into your sprint retrospectives or quarterly planning.
  4. Ignoring relationships. A list of boxes without labeled arrows tells you nothing useful. Every relationship in your DSL should have a meaningful description not just "connects to" but "sends order events to" or "retrieves user profile from."
  5. Choosing tools without team buy-in. If only one architect writes Structurizr DSL and nobody else reads it, the diagrams don't serve the team. Pick the tool that your team will actually maintain.

How do you get started with C4 DSL notation for your enterprise architecture?

Start small and expand:

  1. Pick one system boundary. Don't try to diagram your entire enterprise on day one. Choose one significant system or product and create its C4 Context and Container diagrams in DSL.
  2. Choose your tooling. If your team already uses PlantUML, start there with C4 extensions. If you're starting fresh, Structurizr DSL has a lower learning curve for C4 specifically. We cover more options in our overview of C4 model DSL notation for enterprise architecture diagram DSLs.
  3. Store DSL files in version control. Put them in the same repo as the system they describe, or create a dedicated architecture repository. Either way, they need to live in Git (or your equivalent).
  4. Generate and share diagrams in CI. Set up a build step that renders your DSL files into SVG or PNG and publishes them to your internal wiki or documentation site. This removes the manual export step that often causes diagrams to fall behind.
  5. Review and iterate. Treat diagram accuracy like code quality. Review DSL changes in pull requests. Ask teammates if the diagrams match their understanding of the system.

What tools render C4 model DSL notation into actual diagrams?

Depending on your chosen DSL, rendering options include:

  • Structurizr offers a free cloud service, an on-premises deployment option, and a CLI that generates diagrams locally. The Structurizr DSL is documented at structurizr.com.
  • PlantUML renders locally via a Java JAR, or through web services like plantuml.com. It integrates with many IDEs and documentation tools.
  • Mermaid.js renders in the browser and is built into GitHub, GitLab, and many Markdown editors.
  • IDE plugins VS Code has extensions for both Structurizr DSL and PlantUML that provide live previews as you type.

Practical checklist: adopting C4 DSL notation for enterprise architecture

  • Identify 1–2 key systems to model first
  • Choose between Structurizr DSL, PlantUML, or Mermaid based on team familiarity
  • Write Context and Container level diagrams in DSL files
  • Commit DSL files to version control
  • Set up automated diagram rendering in your CI pipeline
  • Add diagram review to your regular team process
  • Expand to additional systems and deeper abstraction levels as needed

Start with one diagram, get feedback from your team, and build from there. Text-based architecture diagrams only become valuable when the team trusts them and trust comes from keeping them accurate and visible.