The C4 model - misconceptions,

misuses, and mistakes

Simon Brown
@simonbrown
What is the C4 model?
@simonbrown
 #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.”

@simonbrown
C4
c4model.com
@simonbrown
If you’re going to use “boxes & lines”,
at least do so in a structured way,
using a self-describing notation

@simonbrown
 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).
@simonbrown
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

@simonbrown
 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?

@simonbrown
@simonbrown
 Container diagram
What are the major technology building blocks?
What are their responsibilities?
How do they communicate?

@simonbrown
@simonbrown
@simonbrown
Okay, but…
“ ”
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
“ ”
Why did you reinvent UML?
 #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.”

@simonbrown
 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

“ ”
I've recently come across the C4
model in software architecture
discussions … any insights, tips, or
anecdotes would be greatly
appreciated!
“ ”
We went down that path for awhile. It's a giant waste
of time, any tooling that markets "automating keeping
it up to date" are outright lying to you, and the process
is so cumbersome that engineers will start making
technical decisions based on avoiding having to
update the architectural documentation.
 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

“ ”
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).
@simonbrown
fi
fi
fi
“ ”
Why doesn’t your own tooling
(Structurizr) support level 4?
Very few teams use level 4
It’s a lot of work to fully support every
OO/functional/procedural language,
data schema/model, etc
UML, ERD, etc exist already,
and many tools support
automatic generation
@simonbrown
@simonbrown
Notation
“ ”
The blue and grey notation
is boring
“ ”
the default theme (grey boxes) is an eyesore
… should we create our own theme?
 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

“ ”
But C4 is really limited …
1 type of relationship

@simonbrown
“ ”
[C4 is] unclear because you forced
to place a lot of text in each box

@simonbrown
@simonbrown
“ ”
We found the notation too cluttered,
so removed the metadata
@simonbrown
@simonbrown
@simonbrown
Viewpoints
“ ”
C4 isn’t good at showing decisions

@simonbrown
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)

@simonbrown
fi
“ ”
C4 model omits the
deployment story
@simonbrown
@simonbrown
@simonbrown
“ ”
We don't need C4 because we do
DDD/event modeling instead
@simonbrown
“ ”
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
“ ”
I personally prefer Event Modeling
knives
over C4. C4 has the major downside
forks. A fork

that it does not re ect the concept of

time very well.
cutting
fl
@simonbrown
@simonbrown
“ ”
Event Modeling is a way to design a blueprint for an
Information System of any size or scale. It is done in a
way that allows the clearest communication of the
system's workings to the largest possible cross-section
of roles in an organization.
“Event Modeling: What is it?”
eventmodeling.org
@simonbrown
@simonbrown
@simonbrown
Abstractions
and naming
“ ”
Why not show multiple levels of
abstraction on one diagram?
“ ”
We renamed the abstractions to
software system, component,
sub-component, code
“ ”
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

@simonbrown
“ ”
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

@simonbrown

ff
What is a “database”?
“ ”
microservices shouldn’t
share a database

@simonbrown
 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
 What is a
“component”?
model {
softwareSystem "service" {
container "backend1" {
component "api"
}
container "backend2" {
component "api"
component "graphql"
}
}
}
model {
softwareSystem "service" {
group "backend1" {
container "api1"
}
group "backend2" {
container "api2"
container "graphql"
}
}
}
“ ”
C4 is more suited to monolithic
architectures, and doesn’t support
distributed architectures well
 What is a
“microservice”?
“ ”
We’re modelling microservices as
containers, with APIs and database
schemas as components
 In this example,
a microservice is
a combination of
an API and
a database schema

@simonbrown
@simonbrown
container softwareSystem {
include user ->service1->
autolayout
}

@simonbrown
container softwareSystem {
include ->service2->
autolayout
}

@simonbrown
container softwareSystem {
include ->service3->
autolayout
}

@simonbrown
@simonbrown
@simonbrown
@simonbrown
@simonbrown
@simonbrown
“ ”
What are your thoughts on modelling
N layers of abstractions?
(e.g. software system, containers, modules,
components, packages, code)
Abstraction
vs

organisation
“ ”
Should we show dependencies to
containers in an external system?
Showing “external” containers implies
some understanding of
implementation details, which makes
the diagrams more volatile to change
 This is a form of coupling
(and I might question your team boundaries)
There may some useful exceptions
to this guidance…
How should we…
“ ”
How should we model
message-driven architectures?
Microservice A Microservice C
Sends messages to Sends messages to
[Container] [Container]

Kafka
[Container]

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

Beware of hiding the true story

@simonbrown
 Topic X
Microservice A Microservice C
[Container: Kafka
[Container] Sends customer update messages to Sends customer update messages to [Container]
Topic]

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

Beware of hiding the true story

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

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

Beware of hiding the true story

@simonbrown
Microservice A Microservice C
[Container] Sends customer update messages to [Container]
[via Kafka topic X]

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

Beware of hiding the true story

@simonbrown
“ ”
How should we model
shared libraries?

@simonbrown
tl;dr 😂
@simonbrown
 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!

Simon Brown
@simonbrown