Visualising software

architecture with the

C4 model

@simonbrown
 Simon Brown
Independent consultant specialising in software architecture,
plus the creator of the C4 model and Structurizr

@simonbrown
Do you use UML?
 In my experience, optimistically,

1 out of 10 people use 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.”
7
7
7
7
7
7
6
“Just use a whiteboard!”
If software developers created building architecture diagrams…

Stairs Bed1 Bathroom

Off-peak electricity
Peak electricity
Hallway

Water out
Water in
Stairs Bathroom Bed2 Bed3

Kitchen Living Room

Engineers,
not artists
Moving fast in the same direction
as a team requires

good communication
There are many different audiences for diagrams
and documentation, all with different interests
(software architects, software developers, operations and support staff, testers,
Product Owners, project managers, Scrum Masters, users, management,
business sponsors, potential customers, potential investors, …)
 When drawing software
architecture diagrams,
think like a software developer
A common set of abstractions
is more important
than a common 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, microservice, database schema, file system, etc) mobile app, microservice, database schema, file system, etc) mobile app, microservice, database schema, file system, e

Component Component Component

Code Code Code

A software system is made up of one or more containers,

each of which contains one or more components,
which in turn are implemented by one or more code elements.
C4
c4model.com
 1. System Context
The system plus users and system dependencies.

Overview first
2. Containers
The overall shape of the architecture and technology choices.

3. Components Zoom & filter

Logical components and their interactions within a container.

4. Code (e.g. classes) Details on demand

Component implementation details.
 Diagrams are maps
that help software developers navigate a large and/or complex codebase
 Runtime and
Business
behaviour
(sequence and collaboration
process and
diagrams of elements in the workflow
static model)

A model of the
Static
Data
(entity relationship
model etc…
static structure
forms the basis
diagrams) (software systems,
containers, components
andclasses)
and code)

Infrastructure
for other views
Deployment
(physical, virtual,
(mapping of containers
containerised hardware;
to infrastructure)
firewalls, routers, etc)
 Example
(Internet Banking System)
 Level 1

System Context diagram

 Level 2

Container diagram
 Level 3

Component diagram
 Level 4

Class diagram
Notation
 Titles
Short and meaningful, include the diagram type,
numbered if diagram order is important; for example:

System Context diagram for Financial Risk System

[System Context] Financial Risk System
 Layout
Sticky notes and index cards (e.g. CRC cards)
make a great substitute for hand-drawn boxes,
especially if you don’t have a whiteboard
 Visual consistency
Try to be consistent with notation
and element positioning across diagrams
 Acronyms
Be wary of using acronyms, especially those related
to the business/domain that you work in
 Elements
Start with simple boxes containing the element name, type,
technology (if appropriate) and a description/responsibilities
 techtribes.je
Anonymous User [Software System]

[Person]
techtribes.je is the only way to keep up
to date with the IT, tech and digital
Anybody on the web.
sector in Jersey and Guernsey, Channel
Islands.

Web Application Twitter Connector

[Container: Java + Spring MVC]
[Component: Spring Bean + Twitter4j]

Allows users to view people, tribes,

Retrieves profile information and tweets
content, events, jobs, etc from the local
(using the REST and Streaming APIs).
tech, digital and IT sector.
 Lines
Favour uni-directional lines showing the most important
dependencies or data flow, with an annotation to be explicit
about the purpose of the line and direction
Single Page Application Makes an API request to API Application
[Container] [Container]
Sends an API response to

Single Page Application API Application

[Container] [Container]

Makes API calls using

Summarise the intent of the relationship

Single Page Application API Application
[Container] [Container]
Uses

Single Page Application API Application

[Container] [Container]

Makes API calls using

Summarise, yet be specific

 Requests a list of customers from
[JSON/HTTPS]
Microservice A Microservice B
[Container] [Container]

Sends new customers to

[Kafka topic]

Show both directions when

the intents are different
Microservice A Microservice C
Sends messages to Sends messages to
[Container] [Container]

Kafka
[Container]

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

Beware of hiding the true story

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

 Trade Data System Financial Risk System
[Software System] [Software System]

Trade data

Trade Data System Financial Risk System

[Software System] [Software System]

Sends trade data to

Add more words to make the intent explicit

 Key/legend
Explain shapes, line styles, colours, borders, acronyms, etc
… even if your notation seems obvious!
Use shape, colour and size
to complement a diagram
that already makes sense
Use icons to supplement text,
not replace it
 Increase the readability of
software architecture diagrams,
so they can stand alone
Any narrative should complement
the diagram rather than explain it
 Notation, notation, notation
A software architecture diagram review checklist

General

Does the diagram have a title? Yes No

Do you understand what the diagram type is? Yes No

Do you understand what the diagram scope is? Yes No

Does the diagram have a key/legend? Yes No

Elements

Does every element have a name? Yes No

Do you understand the type of every element? (i.e. the level of abstraction; e.g. software Yes No
system, container, etc)

Do you understand what every element does? Yes No

Where applicable, do you understand the technology choices associated with every Yes No
element?

Do you understand the meaning of all acronyms and abbreviations used? Yes No

Do you understand the meaning of all colours used? Yes No

“ ”
What tools do you
recommend?
A lightweight software architecture modelling tool, specifically designed to support the C4 model;
supplemented with Markdown/AsciiDoc documentation, and architecture decision records (ADRs)
 Abstractions first,
notation second
Ensure that your team has a ubiquitous
language to describe software architecture
Thank you!
[email protected]
@simonbrown