Skip to content

C4/Structurizr vs UML — A Practitioner's Comparison

Context

C4 was born from UML. Simon Brown created the C4 model between 2006 and 2011, explicitly inspired by UML and Kruchten's 4+1 View Model, as a pragmatic alternative for teams that found UML too complex for day-to-day architecture communication. Understanding the relationship between the two — what C4 took from UML, what it deliberately left behind, and where UML still has no substitute — is essential for any architecture practice deciding how to document software systems.

This document is not a "which is better" argument. It's a precise mapping of what each can express, where they overlap, where they diverge, and how they can work together.

1. What Each Is

1.1 UML (Unified Modeling Language)

UML is a standardized, general-purpose modeling language maintained by the Object Management Group (OMG). Version 2.5.1 (current) defines 14 diagram types organized into two categories:

Structural diagrams (7):

Diagram Purpose
Class Diagram Classes, attributes, operations, and relationships (inheritance, association, composition)
Object Diagram Instances of classes at a specific point in time
Component Diagram Components, their interfaces, and dependencies
Deployment Diagram Mapping of software artifacts to infrastructure nodes
Package Diagram Organization of model elements into packages and their dependencies
Composite Structure Diagram Internal structure of a class or component, including ports and connectors
Profile Diagram Extensions to the UML metamodel for domain-specific customization

Behavioral diagrams (7):

Diagram Purpose
Use Case Diagram Actors and their interactions with system use cases
Activity Diagram Workflows and business processes (similar to flowcharts, with concurrency)
State Machine Diagram States, transitions, and events for a single object's lifecycle
Sequence Diagram Time-ordered message exchanges between objects/components
Communication Diagram Message exchanges organized by object relationships (same info as sequence, different layout)
Timing Diagram State changes over time with precise timing constraints
Interaction Overview Diagram High-level flow of control between interaction fragments

UML was designed in the 1990s to be comprehensive — a single language for modeling everything from business requirements to code structure. The specification is ~796 pages.

1.2 C4 Model / Structurizr

C4 defines 4 core diagram types plus 3 supplementary types, all focused on the static structure of software systems at different zoom levels:

Core diagrams (4):

Diagram Purpose
System Context The system in scope, its users, and external systems
Container Deployable units inside the system (APIs, apps, databases, queues)
Component Logical modules inside a single container
Code Classes and interfaces (optional — rarely used)

Supplementary diagrams (3):

Diagram Purpose
System Landscape All systems in the enterprise and their relationships
Dynamic Runtime interactions for a specific scenario (numbered sequence)
Deployment Mapping of containers to infrastructure nodes per environment

C4 uses ~5 element types (Person, Software System, Container, Component, Code element) and 1 relationship type (labeled arrow). It is notation-independent — you can render C4 diagrams with any tool.

Structurizr is the primary tooling for C4, providing a text-based DSL for defining a single model from which all diagram views are generated. It exports to PlantUML, Mermaid, DOT, SVG, and PNG.

2. Diagram-by-Diagram Mapping

2.1 Where C4 diagrams map to UML diagrams

C4 Diagram Closest UML Equivalent Key Differences
System Context No direct equivalent (closest: Use Case Diagram at system level, or a high-level Component Diagram) C4 shows systems and users with labeled relationships. UML Use Case Diagrams show actors and use cases, not system-to-system dependencies. UML Component Diagrams can approximate this but are typically more detailed.
Container Component Diagram (UML 2.0) C4 Containers are deployable units with technology annotations. UML Components are logical units with provided/required interfaces and ports. UML is more precise about interfaces; C4 is more explicit about technology choices.
Component Component Diagram (nested) or Package Diagram C4 Components are logical modules inside a container. UML Components can be nested and have formal interface specifications. UML Package Diagrams show module organization with dependencies.
Code Class Diagram Nearly identical purpose. C4 explicitly says "use a UML Class Diagram or equivalent" for this level. Simon Brown recommends generating these from code rather than maintaining them manually.
Dynamic Sequence Diagram or Communication Diagram C4 Dynamic diagrams show numbered interactions between C4 elements (containers, components). UML Sequence Diagrams are far richer: lifelines, activation bars, combined fragments (alt, loop, opt, par), return messages, creation/destruction.
Deployment Deployment Diagram C4 uses DeploymentNodes (nestable) with ContainerInstances. UML uses Nodes, Execution Environments, Artifacts, and Deployment Specifications. UML has richer semantics; C4 has deployment environments as a first-class concept.
System Landscape No direct equivalent (closest: high-level Component Diagram or custom diagram) C4 System Landscape shows all systems in the enterprise. UML has no standard diagram type for this — it's typically done as a custom Component Diagram or a non-standard "system context" diagram.

2.2 UML diagrams with no C4 equivalent

UML Diagram What it models C4 Gap
Class Diagram (detailed) Attributes, operations, visibility, inheritance hierarchies, abstract classes, interfaces, generics C4's Code level is optional and rarely used. Most teams use their IDE or auto-generated class diagrams instead.
Sequence Diagram (full) Lifelines, activation bars, combined fragments (alt/loop/opt/par/break), synchronous vs asynchronous messages, return values, creation/destruction of objects C4 Dynamic diagrams are simplified numbered sequences. No combined fragments, no activation bars, no formal message typing.
Activity Diagram Workflows with decision nodes, fork/join (concurrency), swim lanes, object flows, signals C4 has no behavioral/process modeling. This is a fundamental gap — C4 models structure, not behavior.
State Machine Diagram States, transitions, guards, actions, composite states, history states C4 has no state modeling.
Use Case Diagram Actors, use cases, include/extend relationships, system boundaries C4's System Context diagram shows users and systems but not use cases.
Object Diagram Instances and their relationships at a specific point in time C4 has no instance-level modeling (except ContainerInstance in deployment).
Composite Structure Diagram Internal structure with ports, connectors, and collaboration roles C4 Component diagrams are simpler — no ports, no formal connectors.
Timing Diagram State changes with precise timing constraints No C4 equivalent.
Interaction Overview Diagram High-level flow of control between interaction fragments No C4 equivalent.
Profile Diagram UML metamodel extensions Not applicable — C4 has no formal metamodel to extend.
Package Diagram Module organization and dependencies C4 Component diagrams partially cover this, but without UML's package semantics (visibility, imports, merges).

2.3 C4 concepts with no UML equivalent

C4 Concept Gap in UML
Hierarchical zoom (Context → Container → Component → Code) UML has no prescribed zoom hierarchy. You choose diagram types independently. The 4+1 View Model provides a framework, but it's not built into UML itself.
Deployment Environment UML Deployment Diagrams don't have a first-class "environment" concept. You model separate diagrams or use stereotypes.
Container (as a deployable unit with technology annotation) UML's Component is a logical unit. UML's Artifact is a deployable unit. Neither combines the two the way C4's Container does — a single concept that is both a logical grouping of functionality AND a deployable unit with a named technology.
System Landscape UML has no standard enterprise-level system overview diagram.
"Models as code" workflow UML was designed for GUI-based modeling tools. Structurizr DSL is designed for text editors and Git. PlantUML bridges this gap for UML, but it's a third-party tool, not part of the UML standard.

3. Expressiveness Comparison

3.1 Structural modeling

Concern UML C4 / Structurizr
System-level overview ⚠️ Custom Component Diagram ✅ System Context diagram (purpose-built)
Deployable units and their technology ⚠️ Component + Artifact + stereotypes ✅ Container (single concept, technology annotation)
Internal modules of a service ✅ Component Diagram (nested, with interfaces) ✅ Component diagram (simpler, no formal interfaces)
Class/interface structure ✅ Class Diagram (rich: attributes, operations, visibility, generics, inheritance) ⚠️ Code diagram (optional, usually auto-generated)
Object instances at runtime ✅ Object Diagram ❌
Internal structure with ports ✅ Composite Structure Diagram ❌
Package/module organization ✅ Package Diagram ⚠️ Component diagram (partial)
Deployment to infrastructure ✅ Deployment Diagram (Nodes, Execution Environments, Artifacts) ✅ Deployment diagram (DeploymentNodes, ContainerInstances, Environments)
Enterprise system landscape ❌ No standard diagram ✅ System Landscape diagram

3.2 Behavioral modeling

Concern UML C4 / Structurizr
Runtime message sequences ✅ Sequence Diagram (lifelines, activation, combined fragments, return messages) ⚠️ Dynamic diagram (numbered arrows, no combined fragments)
Workflows and processes ✅ Activity Diagram (decision, fork/join, swim lanes) ❌
Object lifecycle states ✅ State Machine Diagram ❌
Actor-system interactions ✅ Use Case Diagram ⚠️ System Context (shows users but not use cases)
Timing constraints ✅ Timing Diagram ❌
Interaction flow overview ✅ Interaction Overview Diagram ❌

3.3 Summary

UML covers both structural and behavioral modeling across 14 diagram types. C4 covers structural modeling at 4 zoom levels plus simplified behavioral (Dynamic) and deployment views. The gap is entirely on the behavioral side — C4 has no equivalent for Activity, State Machine, Use Case, Timing, or Interaction Overview diagrams.

4. The Relationship: C4 Was Designed to Complement UML, Not Replace It

Simon Brown has been explicit about this. From the C4 model FAQ:

"The C4 model was created during a time where teams, influenced by the agile movement, were less than enthusiastic about using the Unified Modeling Language (UML) to document software architecture. Despite this, the C4 model was inspired by UML and the 4+1 model for software architecture."

And from his GOTO 2024 talk on misconceptions:

"C4 replaces UML" is listed as a misconception. "C4 was never designed to replace UML but rather to offer a more structured approach to boxes-and-arrows diagrams. UML and C4 can complement each other."

The design intent is clear: C4 replaces the ad-hoc "boxes and arrows" diagrams that teams draw on whiteboards and in draw.io. It does not replace UML's detailed behavioral and structural modeling capabilities.

5. Where UML Is Still Necessary (Even If You Use C4)

5.1 Detailed behavioral modeling

When you need to show: - The exact sequence of messages in a complex interaction (authentication flow, payment processing, saga orchestration) → UML Sequence Diagram - A business process or workflow with decision points and parallel paths → UML Activity Diagram (or BPMN, which is purpose-built for this) - The lifecycle states of an entity (Order: Created → Confirmed → Shipped → Delivered → Cancelled) → UML State Machine Diagram

C4's Dynamic diagram is too simple for these. It shows numbered arrows between C4 elements but has no combined fragments (alt/loop/opt), no activation bars, no formal message typing, and no concurrency notation.

5.2 Detailed class/interface design

When you need to show: - Inheritance hierarchies, abstract classes, interfaces - Attributes with types and visibility - Operations with signatures - Design patterns (Strategy, Observer, Factory) at the code level

C4's Code level is explicitly optional and Simon Brown recommends auto-generating it from code rather than maintaining it manually. UML Class Diagrams remain the standard for this level of detail.

5.3 Formal interface specifications

UML Components have provided and required interfaces (the "lollipop and socket" notation), ports, and connectors. These formally specify what a component offers and what it needs. C4 Components have a name, a description, and labeled relationships — no formal interface specification.

When you need to define API contracts at the architectural level (not just label them on arrows), UML's interface notation is more precise.

6. Where C4 Is Better Than UML

6.1 The "what is this system?" question

UML has no standard diagram for answering "what is this system, who uses it, and what does it depend on?" You can approximate it with a Use Case Diagram (but that shows use cases, not system dependencies) or a high-level Component Diagram (but that's not its intended purpose).

C4's System Context diagram is purpose-built for this. It's the single most useful architecture diagram for onboarding, stakeholder alignment, and design reviews.

6.2 The "what runs where?" question with technology context

UML's Component Diagram models logical components. UML's Deployment Diagram models physical deployment. The two are separate — you need to cross-reference them to understand "this Spring Boot API runs on this Kubernetes pod."

C4's Container concept combines both: it's a deployable unit with a named technology ("Orders API — Spring Boot, REST"). The Container diagram shows both the logical structure and the technology choices in a single view. The Deployment diagram then maps these containers to infrastructure.

6.3 Progressive zoom as a communication framework

UML's 14 diagram types are independent — there's no prescribed order or hierarchy. A team can create a Sequence Diagram without a Component Diagram, or a Deployment Diagram without a Class Diagram. This flexibility is powerful but provides no guidance on "where to start" or "what level of detail is appropriate for this audience."

C4's four levels are a communication framework: start with Context (for everyone), zoom to Container (for technical staff), zoom to Component (for developers), zoom to Code (only if needed). Each level has a defined audience and a defined level of detail. This progressive disclosure is C4's core innovation — it's not a notation, it's a communication strategy.

6.4 "Models as code" with Structurizr

UML was designed for GUI-based modeling tools (Rational Rose, Enterprise Architect, MagicDraw). While PlantUML and Mermaid provide text-based UML rendering, they are third-party tools that support a subset of UML.

Structurizr DSL is purpose-built for text-based architecture modeling: - A single model generates multiple views (you don't duplicate elements across diagrams) - The DSL is version-controlled in Git - Changes are reviewed in pull requests - CI/CD pipelines can validate models and generate diagrams - Exports to PlantUML, Mermaid, DOT, SVG, PNG

This "model once, view many" approach is architecturally sound and practically superior to maintaining separate UML diagrams that can drift out of sync.

6.5 Learning curve and adoption

UML: 14 diagram types, hundreds of notation elements, stereotypes, tagged values, OCL constraints. The specification is ~796 pages. Effective use requires training (days to weeks).

C4: 4 diagram types, ~5 element types, labeled arrows. The entire model can be explained in 30 minutes. A developer can create useful C4 diagrams after a 2-hour workshop.

7. Using C4 and UML Together — The Practical Approach

7.1 C4 for architecture, UML for design

Level Tool Diagram
Enterprise landscape C4 System Landscape
System scope and context C4 System Context
System internals (deployable units) C4 Container
Container internals (modules) C4 Component
Runtime scenarios UML Sequence Diagram (for complex flows) or C4 Dynamic (for simple flows)
Workflows and processes UML Activity Diagram (or BPMN)
Entity lifecycles UML State Machine Diagram
Class/interface design UML Class Diagram (or auto-generated)
Deployment topology C4 Deployment diagram (per environment)

7.2 Structurizr exports to PlantUML

Structurizr can export all C4 views to PlantUML format, including C4-PlantUML notation. This means you can:

  1. Define your architecture model in Structurizr DSL
  2. Export C4 diagrams as PlantUML
  3. Add UML Sequence Diagrams, Class Diagrams, and Activity Diagrams as separate PlantUML files in the same repository
  4. Render everything with the same PlantUML toolchain

This gives you a unified "diagrams as code" workflow where C4 and UML coexist in the same Git repository, rendered by the same tool.

7.3 Naming convention as the bridge

The key integration point is consistent naming. A C4 Container named "Orders API" should appear as the same named participant in UML Sequence Diagrams and as the same named component in UML Component Diagrams. No formal linking mechanism is needed — just discipline.

8. Decision Framework

flowchart TD
    Q["What are you modeling?"]

    Q --> SS["System scope and dependencies"] --> C4SC["C4 System Context"]
    Q --> DU["Deployable units and technology"] --> C4Con["C4 Container"]
    Q --> IM["Internal modules of a service"] --> C4Comp["C4 Component"]
    Q --> DI["Deployment to infrastructure"] --> C4Dep["C4 Deployment"]
    Q --> ESL["Enterprise system landscape"] --> C4SL["C4 System Landscape"]

    Q --> CRI["Complex runtime interaction<br/>(auth flow, saga, payment)"] --> UMLSD["UML Sequence Diagram"]
    Q --> SRI["Simple runtime interaction"] --> C4Dyn["C4 Dynamic Diagram"]
    Q --> WF["Workflow or business process"] --> UMLAD["UML Activity Diagram / BPMN"]
    Q --> ELS["Entity lifecycle states"] --> UMLSM["UML State Machine Diagram"]
    Q --> CID["Class/interface design"] --> UMLCD["UML Class Diagram"]
    Q --> AUC["Actor-system use cases"] --> UMLUCD["UML Use Case Diagram"]
    Q --> FIC["Formal interface contracts"] --> UMLComp["UML Component Diagram (with ports)"]

9. Summary

Dimension UML C4 / Structurizr
Diagram types 14 (7 structural + 7 behavioral) 7 (4 core + 3 supplementary)
Element vocabulary Hundreds (classes, interfaces, actors, nodes, artifacts, states, activities, ...) ~5 (Person, Software System, Container, Component, DeploymentNode)
Relationship vocabulary Dozens (association, dependency, generalization, realization, composition, aggregation, include, extend, message, transition, ...) 1 (labeled arrow)
Structural modeling Comprehensive Focused on 4 zoom levels
Behavioral modeling Comprehensive (sequence, activity, state, use case, timing) Minimal (Dynamic diagram only)
Deployment modeling Rich (Nodes, Execution Environments, Artifacts) Practical (DeploymentNodes, ContainerInstances, Environments)
Specification size ~796 pages ~10 pages
Learning curve Days to weeks Hours
Standardization OMG standard (ISO/IEC 19505) Community practice
Primary tooling GUI-based (Enterprise Architect, MagicDraw, StarUML) + PlantUML Text-based (Structurizr DSL) + exports to PlantUML/Mermaid
"As code" support Via PlantUML/Mermaid (third-party, subset) Native (Structurizr DSL)
Model-to-view Typically 1:1 (one diagram = one model fragment) 1:many (one model → multiple views)
Audience Architects, developers, analysts Architects, developers, non-technical stakeholders
Designed for Comprehensive software modeling (design through implementation) Architecture communication (structure at multiple zoom levels)

C4 is not a replacement for UML. It's a replacement for the ad-hoc boxes-and-arrows diagrams that most teams actually draw. For structural architecture communication, C4 is simpler, more consistent, and more adoptable. For detailed behavioral modeling, class design, and formal interface specification, UML remains the standard. The best practice is to use both: C4 for the architecture views that everyone needs to understand, and UML for the detailed design views that developers need to implement.

References

Official Sources

Comparison Articles

History and Context

Linked.Archi — This Repository