The C4 model

Misconceptions, misuses, and mistakes

Simon Brown
What is the C4 model?
 #2 “Not everybody else on the team knows it.”
#3 “I’m the only person on the team who knows it.”
#36 “You’ll be seen as old.”
#37 “You’ll be seen as old-fashioned.”
#66 “The tooling sucks.”
#80 “It’s too detailed.”
#81 “It’s a very elaborate waste of time.”
#92 “It’s not expected in agile.”
#97 “The value is in the conversation.”
C4
c4model.com
A way to introduce some structure
to “boxes & lines” diagrams,
using a self-describing notation
 Software System

Container Container Container

lient-side web app, server-side web app, console application, (e.g. client-side web app, server-side web app, console application, (e.g. client-side web app, server-side web app, console applic
obile app, database schema, mobile app, database schema, le system, object store, etc) mobile app, database schema,

Component Component Component

Code Code Code

A software system is made up of one or more containers (applications and data

stores), each of which contains one or more components, which in turn are
implemented by one or more code elements (classes, interfaces, objects, functions, etc).
fi
fi
fi
 The C4 model for visualising
software architecture
c4model.com

Zoom in

Zoom in

Zoom in

Level 1 Level 2 Level 3 Level 4

Context Containers Components Code
 Diagrams are maps
that help software developers navigate a large and/or complex codebase
 Diagrams are graphs
that help software developers navigate a large and/or complex codebase
 System Context diagram
What is the scope of the software system we’re building?
Who is using it? What are they doing?
What system integrations does it need to support?
 Container diagram
What are the major technology building blocks?
What are their responsibilities?
How do they communicate?
“ ”
I've only just heard of the
C4 model - I guess it's new?
“ ”
I’m not against using C4,
even though I got the feeling that it
still needs to become more mature
“ ”
C4 has been around over a decade
- if it was truly useful, it would have
replaced UML in most teams
C4 wasn't designed
to replace UML
C4 was designed to bring structure to
the typical ad hoc "boxes and arrows"
diagrams teams typically create
because they are no longer using UML
 I've seen more interest than ever in
C4 over the past few years; many
organisations have adopted it as their
preferred approach for software
architecture diagramming
I’ve run software architecture
workshops
in 30+ countries
for 10,000+ people
across most industry sectors
 My C4 model book is also
used as course material
in many other universities
Why did you reinvent UML?
 The C4 model is…

A set of hierarchical A set of hierarchical

abstractions diagrams
(software systems, containers, (system context, containers, components,
components, and code) and code)

Notation independent Tooling independent

UML + C4 model abstractions
and diagram types
“ ”
Few people use level 4.
Why not just call it C3?
 Software System

Container Container Container

lient-side web app, server-side web app, console application, (e.g. client-side web app, server-side web app, console application, (e.g. client-side web app, server-side web app, console applic
obile app, database schema, mobile app, database schema, le system, object store, etc) mobile app, database schema,

Component Component Component

Code Code Code

A software system is made up of one or more containers (applications and data

stores), each of which contains one or more components, which in turn are
implemented by one or more code elements (classes, interfaces, objects, functions, etc).
fi
fi
fi
Notation
“ ”
The blue and grey notation
is boring
 The C4 model is…

A set of hierarchical A set of hierarchical

abstractions diagrams
(software systems, containers, (system context, containers, components,
components, and code) and code)

Notation independent Tooling independent

“ ”
[C4 is] unclear because you forced
to place a lot of text in each box
“ ”
We found the notation too cluttered,
so removed the metadata
Viewpoints
“ ”
C4 isn’t good at showing decisions
Architecture diagrams show
the outcome of the
decision making process
 “Architecture
Decision Record”
A short description of an
architecturally signi cant decision

http://thinkrelevance.com/blog/2011/11/15/documenting-
architecture-decisions (Michael Nygard)
fi
“ ”
C4 model omits the
deployment story
The C4 model was inspired by
UML and the 4+1 model
“ ”
We don't need C4 because
we do DDD instead
“ ”
I personally prefer Event Modeling
over C4. C4 has the major downside
that it does not re ect the concept of
time very well.
fl
Abstractions
and naming
“ ”
We renamed the abstractions to
software system, component,
sub-component, code
“ ”
We’ve adopted the Spotify model;
we use “software system”
to represent the capability
we (the squad) are building
“C4 is too limiting”
“ ”
A database is a database; debating
whether it is also a Container or a
Component just isn’t worthwhile.
“Concrete Diagramming Models, a Lightweight Alternative to C4“
www.ilograph.com/blog/posts/concrete-diagramming-models
“ ”
The problem is that systems today have many di erent kinds of
things. Servers, databases, virtualized containers, APIs,
pipelines, repositories, packages, libraries, and (many, many)
cloud resources are all real, concrete things that provide real
value. Forcing them into one of C4’s four levels of abstraction
doesn’t really accomplish much.
“Concrete Diagramming Models, a Lightweight Alternative to C4“
www.ilograph.com/blog/posts/concrete-diagramming-models

ff
What is a “database”?
“ ”
microservices shouldn’t
share a database
 Be more precise with your
terminology … which is exactly what
the "system vs container vs
component" debate forces you to do
 The power of the C4 model isn't the
diagrams, it's the small set of named
hierarchical abstractions that help
teams reason about their codebases
in a structured and more precise way
“ ”
Inspired by C4 Model and Structurizr DSL, but
with some exibility. You de ne your own
notation, custom element types and any
number of nested levels in the architecture
model. Perfectly tailored to your needs.
fl
fi
 What is a
“component”?
“ ”
Component
a modular unit with well-de ned Interfaces
that is replaceable within its environment
https://www.omg.org/spec/UML/2.5.1/PDF

fi
Software System

Web
Application

Logging
Component

Relational
Database
 Forcing them into one of C4’s four
levels of abstraction doesn’t really
accomplish much.

Ad hoc abstractions De ned abstractions

Most “boxes and arrows” diagrams C4 model

Inspired by C4 Model and Structurizr

DSL, but with some exibility. You de ne
your own notation, custom element types and
any number of nested levels in the
architecture model.
fi
fl
fi
Ad hoc abstractions De ned abstractions Flexible abstractions
Most “boxes and arrows” diagrams C4 model Ilograph, LikeC4, etc
fi
 Ad hoc abstractions Flexible abstractions
Most “boxes and arrows” diagrams Ilograph, LikeC4, etc

De ned abstractions
C4 model
fi
Abstraction
vs

organisation
“ ”
What are your thoughts on modelling
additional abstractions?
 Subsystem
"part of a larger system"
Bounded context
Layers
Controller Layer

Service Layer

Repository Layer
 Some of these concepts
might be better thought of as
organisational constructs
rather than abstractions
Message-driven
architectures
Service A Service C
Sends messages to Sends messages to
[Container] [Container]

Kafka
[Container]

Service B Service D
[Container] Sends messages to Sends messages to [Container]

Beware of hiding the true story

 Topic X
Service A Service C
[Container: Kafka
[Container] Sends customer update messages to Sends customer update messages to [Container]
Topic]

Topic Y
Service B Service D
[Container: Kafka
[Container] Sends order creation messages to Sends order creation messages to [Container]
Topic]

Beware of hiding the true story

 Topic X
Service A Service C
[Container: Kafka Subscribes to customer update
[Container] Sends customer update messages to [Container]
Topic] messages from

Topic Y
Service B Service D
[Container: Kafka
[Container] Sends order creation messages to
Subscribes to order creation [Container]
Topic] messages from

Beware of hiding the true story

Service A Service C
[Container] Sends customer update messages to [Container]
[via Kafka topic X]

Service B Service D
[Container] Sends order creation messages to [Container]
[via Kafka topic Y]

Beware of hiding the true story

Shared libraries
Micro frontends
Microservices
“ ”
C4 is more suited to monolithic
architectures, and doesn’t support
distributed architectures well
“ ”
We’re modelling microservices as
containers, with APIs and database
schemas as components
A microservice should be modelled
as one of the following:

1. A software system
2. A container
3. A group of containers
 What is a
“microservice”?
 Stage 1: 💵
(monolithic architecture)
Stage 2: 💵 💵
(microservices)
software system
Stage 3: 💵 💵 💵
(Conway’s Law)
The C4 model at scale
 In this example,
a microservice is
a combination of
an API and
a database schema
container softwareSystem {
include user
Include ->service1->
}
container softwareSystem {
include ->service2->
}
container softwareSystem {
include ->service3->
}
 Dependencies to
“external” containers
My recommendation is that container
diagrams only show containers inside
the software system that is the scope
of the diagram
Container diagram for software system A

container a {
include *
}
Container diagram for software system B

container b {
include *
}
I don’t recommend showing
“external” containers
Container diagram for software systems A and B

container a {
include a.app b.api
}
Showing “external” containers implies
some understanding of
implementation details, which makes
the diagrams more volatile to change
This is a form of coupling
There may some useful exceptions
to this guidance…
Container diagram for software system A, showing a shared DB

container a {
include a.app c.db
}
Container diagram for software system B, showing a shared DB

container b {
include b.api c.db
}
 The C4 model is…

A set of hierarchical A set of hierarchical

abstractions diagrams
(software systems, containers, (system context, containers, components,
components, and code) and code)

Notation independent Tooling independent

 Thank you!

https://leanpub.com/b/software-architecture

Simon Brown