Use when modeling software architecture using the C4 model (Context, Container, Component, Code) by Simon Brown. Covers hierarchical system decomposition, Structurizr DSL, and C4 diagramming best practices.
USE FOR: C4 model diagrams, system context diagrams, container diagrams, component diagrams, code-level diagrams, Structurizr DSL authoring, architecture decomposition, workspace definitions, C4 views and styles
DO NOT USE FOR: general flowcharts (use mermaidjs), enterprise architecture frameworks (use togaf or archimate), data models (use erd)
Use when modeling software architecture using the C4 model (Context, Container, Component, Code) by Simon Brown. Covers hierarchical system decomposition, Structurizr DSL, and C4 diagramming best practices.
USE FOR: C4 model diagrams, system context diagrams, container diagrams, component diagrams, code-level diagrams, Structurizr DSL authoring, architecture decomposition, workspace definitions, C4 views and styles
DO NOT USE FOR: general flowcharts (use mermaidjs), enterprise architecture frameworks (use togaf or archimate), data models (use erd)
[{"title":"C4 Model — Simon Brown","url":"https://c4model.com/"},{"title":"Structurizr DSL Documentation","url":"https://docs.structurizr.com/dsl"}]
C4 Model Diagrams
Overview
The C4 model, created by Simon Brown, is a hierarchical approach to software architecture diagramming. It uses four levels of abstraction — Context, Container, Component, and Code — to describe a software system at different zoom levels. The primary tooling for C4 is the , a text-based domain-specific language purpose-built for C4 modeling.
Structurizr DSL
The Four Levels
Level 1: System Context
The highest level of abstraction. Shows the system under consideration and its relationships with users (actors) and other systems. Answers: "What is the system and who uses it?"
workspace {
model {
user = person "User" "A customer of the system."
email = softwareSystem "Email System" "Sends transactional emails." "External"
system = softwareSystem "My System" "Handles core business logic."
user -> system "Uses"
system -> email "Sends emails via"
}
views {
systemContext system "SystemContext" {
include *
autolayout lr
}
}
}
Level 2: Container
Zooms into a single software system to show the high-level technology choices — web apps, APIs, databases, message brokers, etc. Answers: "What are the major technology building blocks?"
workspace {
model {
user = person "User"
system = softwareSystem "My System" {
webapp = container "Web Application" "Serves the UI." "React"
api = container "API Service" "Handles business logic." "Node.js"
db = container "Database" "Stores data." "PostgreSQL" "Database"
}
user -> webapp "Visits"
webapp -> api "Calls" "HTTPS/JSON"
api -> db "Reads from and writes to" "SQL/TCP"
}
views {
container system "Containers" {
include *
autolayout lr
}
}
}
Level 3: Component
Zooms into a single container to show the logical components inside it and their interactions. Answers: "What are the major structural building blocks inside a container?"
workspace {
model {
system = softwareSystem "My System" {
api = container "API Service" {
controller = component "API Controller" "Handles HTTP requests." "Express Router"
service = component "Business Service" "Implements domain logic." "TypeScript Class"
repo = component "Repository" "Data access layer." "TypeORM Repository"
}
db = container "Database" "PostgreSQL" "Database"
controller -> service "Delegates to"
service -> repo "Uses"
repo -> db "Reads/writes" "SQL"
}
}
views {
component api "Components" {
include *
autolayout lr
}
}
}
Level 4: Code
The lowest level. Shows the internal structure of a single component — typically a UML class diagram or similar. This level is usually auto-generated from code and is optional in most C4 workflows.
Note: Level 4 is often omitted in practice because it can be generated directly from source code by IDEs or static analysis tools. Use it only when the internal structure of a component is complex enough to warrant explicit documentation.
Structurizr DSL Reference
Workspace Definition
Every Structurizr DSL file starts with a workspace block that contains a model and views.
workspace "Name" "Description" {
!identifiers hierarchical
model {
// Define people, software systems, containers, components
}
views {
// Define diagrams (views) of the model
}
}
Start at Level 1. Always begin with a System Context diagram to define boundaries and external dependencies before zooming in.
Use hierarchical decomposition. Each level should tell a coherent story at its abstraction level. Do not mix abstractions (e.g., do not show database tables in a Container diagram).
Name elements consistently. Use the same name for an element across all levels so readers can trace from Context down to Component.
Limit detail per diagram. Keep each diagram to 5-20 elements. If a diagram is too crowded, it means the container or component needs further decomposition.
Tag elements for styling. Use tags like "Database", "External", "WebBrowser" to apply consistent visual styles.
Skip Level 4 unless necessary. Code-level diagrams are better generated from source code. Reserve manual Level 4 diagrams for algorithmically complex components.
Version your DSL. Store workspace.dsl in Git alongside the source code it describes. Treat it as a first-class artifact.
Use autolayout to get consistent, automated positioning. Override with explicit positioning only when automatic layout produces poor results.
Add deployment views for infrastructure mapping — they show how containers map to cloud services, VMs, or Kubernetes clusters.
Export to Mermaid for embedding in Markdown documentation. Use the Structurizr CLI export -format mermaid command.
