Visualising

software architecture
with the C4 model

@simonbrown
https://leanpub.com/visualising-software-architecture/c/…
What is software
architecture?
 Structure
The definition of software in terms
of its building blocks and their interactions
 Vision
The process of architecting;
making decisions based upon business goals,
requirements and constraints,
plus being able to communicate this to a team
 Enterprise Architecture
Structure and strategy across people, process and technology

System Architecture
High-level structure of a software system
(software and infrastructure)

Application Architecture
The internal structure of an application
“ ”
As a noun, design is the named
structure or behaviour of a system whose
presence resolves ... a force on that
system. A design thus represents one
point in a potential decision space.
Grady Booch
“ ”
All architecture is design, but
not all design is architecture.

Grady Booch
“ ”
Architecture represents the
significant decisions, where significance
is measured by cost of change.

Grady Booch
 Draw one or more software
architecture diagrams to describe
the system/project you
are currently working on

60 minutes
 Design a software solution for
the ”Financial Risk System”, and
draw one or more architecture
diagrams to describe your solution

90 minutes
Did you find anything
about this exercise

challenging?
 Swap and review your diagrams
Focus on the diagrams rather than the solution itself;
do you understand the notation, colour coding, symbols, etc?

15 minutes
The perfection game
We rate the diagrams… (1-10)
We liked…
To make the diagrams perfect…

15 minutes
1 1 1 2 2 2
 Information is likely
still stuck in your heads
“ ”
This doesn’t make sense,
but we’ll explain it.
• What is this shape/symbol?
• What is this line/arrow?
• What do the colours mean?
• What level of abstraction is shown?
• Which diagram do we read first?
Moving fast in the same direction
as a team requires

good communication
I’ve run diagramming workshops
in 30+ countries
for 10,000+ people
 Software architects
struggle to communicate
software architecture
Do you use UML?
 In my experience, optimistically,

1 out of 10 people use UML

 Who are the stakeholders that
you need to communicate
software architecture to;
what information do they need?
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, …)
 The primary use for
diagrams and documentation is
communication and learning
Software architecture diagrams,
when connected to the code,
are also a fantastic tool for
architectural improvement
“ ”
To describe a software architecture,
we use a model composed of
multiple views or perspectives.
Architectural Blueprints - The “4+1” View Model of Software Architecture
Philippe Kruchten
“Viewpoints and Perspectives”
Why is there a separation
between the logical and
development views?
“ ”
Our architecture diagrams
don’t match the code.
“model-code gap”
 We lack a common vocabulary
to describe software architecture
Software System

Web
Application

Logging
Component

Relational
Database
Ubiquitous
language
Abstractions
Would you code it that way?
(ensure that your diagrams reflect
your implementation intent)
 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.
Static structure diagrams
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. Classes (or Code) 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
and classes)

Infrastructure
for other views
Deployment
(physical, virtual,
(mapping of containers
containerised hardware;
to infrastructure)
firewalls, routers, etc)
Example
(techtribes.je)
 techtribes.je
A simple content aggregator for
the local tech and digital industry
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
 Orientation
Most important thing in the middle;
try to be consistent 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
Financial Risk System Trade Data System
[Software System] [Software System]

Gets trade data from

Trade Data System Financial Risk System

[Software System] [Software System]

Sends trade data to

Dependency vs data flow

 Read the relationship out loud

Web Application Database

[Container] [Container]

Reads from and writes to

 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
 Increase the readability of
software architecture diagrams,
so they can stand alone
Any narrative should complement
the diagram rather than explain it
Draw a Component diagram
to describe a container
(components within the container in scope)

30 minutes
Designing software is where
the complexity should be,
not communicating it!
 Richer diagrams lead to
richer design discussions
The perfection game
We rate the diagrams… (1-10)
We liked…
To make the diagrams perfect…

15 minutes
Similar levels of abstraction provide
a way to easily compare solutions
C4 and UML
 Spring PetClinic
A sample application that illustrates how to build Java web applications using the Spring MVC framework
https://github.com/spring-projects/spring-petclinic/

JSP-with--
Views custom-tags-
|| Thymeleaf-

+ Bootstrap-(CSS)- && webjars- && Dandelion-

Spring-@MVC-annotaGons-
Controller
Bean-ValidaGon-

@Cacheable-
Service
@TransacGonal-

Spring-Data-JPA-
Repository 3-profiles- default-(JPA)-
jdbc-

https://speakerdeck.com/michaelisvy/spring-petclinic-sample-application
System landscape diagrams
Runtime/behavioural diagrams
Static structure diagrams
are very useful, but they
don’t tell the whole story
 JSP-with--
Views custom-tags-
|| Thymeleaf-

+ Bootstrap-(CSS)- && webjars- && Dandelion-

Spring-@MVC-annotaGons-
Controller
Bean-ValidaGon-

@Cacheable-
Service
@TransacGonal-

Spring-Data-JPA-
Repository 3-profiles- default-(JPA)-
jdbc-
Use dynamic diagrams to describe
patterns or complex interactions
Deployment diagrams
Deployment is about the mapping
of containers to infrastructure
 Deployment Node
Physical infrastructure (a physical server or device),
virtualised infrastructure (IaaS, PaaS, a virtual machine),
containerised infrastructure (a Docker container),
database server, Java EE web/application server,
Microsoft IIS, etc
A deployment node can contain
other deployment nodes
or container instances
Frequently asked questions
What's the inspiration
behind the C4 model?
Why "container"?
Can we change the terminology?
How do you model microservices
and serverless?
How do you diagram large and
complex software systems?
Option 1: Introduce additional abstractions
(nested components, sub-components, layers, etc)
 Web controllers

Business components
 Option 2: Partition the diagrams
(one diagram per business concept, feature set,
bounded context, aggregate root, vertical slice, etc)
Will the diagrams become
outdated quickly?
Why doesn't the C4 model cover
business processes, workflows,
state machines, domain models,
data models, etc?
The C4 model vs UML,
ArchiMate and SysML?
Can we combine C4 and arc42?
 Does the C4 model imply a
design process or team structure?
 Draw a System Context diagram
to describe your software system
(people and software systems)

30 minutes
 Draw a Container diagram
to describe your software system
(deployable/runnable units within the software system in scope)

30 minutes
 Draw System Context and
Container diagrams to describe
your software system

60 minutes
Tooling
“ ”
What tools do you
recommend?
Whiteboards and paper
for up front design
General purpose diagramming tools
allow you to draw anything
Microsoft Visio, OmniGraffle, Gliffy,
Lucidchart, draw.io, Creately, …
 Static diagrams need to be
kept up to date individually
Diagrams vs models
 Text-based tools allow you to
create diagrams using text
PlantUML, WebSequenceDiagrams, yUML, nomnoml, …
 Text-based diagrams
can be version controlled,
generated from build scripts, etc
Text-based diagrams
can’t be queried
Architecture description languages
provide a way to describe
architecture as text
Darwin, ACME, Koala, Wright, …
Modelling tools allow you to create
a model of your software system
Sparx Enterprise Architect, IBM Rational Software Architect,
StarUML, GenMyModel, Visual Paradigm, …
Static analysis and dependency
management tools can help
understand code structure
Structure101, Lattix, JArchitect, NDepend,
JDepend, jQAssistant, Degraph, …
 Modelling tools
Sophisticated and often complex tooling to create rich models using
UML, ArchiMate, SysML, etc; either by “drag & drop” or reverse-engineering code.
Richness of model

Static analysis tools

Often complex to setup; creates a model
based upon code only; designed for
understanding code rather than
communicating software architecture.
Text-based tools
Very quick and easy to use;
text can be version controlled;
designed to create individual
diagrams rather than models.

General purpose tools

Easy to use; very flexible;
unstructured; no underlying model.
Whiteboard
Create diagrams easily;
usually transient.

Ease of use
 Virtual Panel on
Software
Architecture
Documentation
(2009)
http://www.infoq.com/articles/virtual-panel-arch-documentation
Do structural engineers and building architects
use general purpose drawing tools?
 Diagrams are not useful for
architectural improvement if they
are not connected to the code
Reverse-engineer
code to diagrams?
 Spring PetClinic
A sample application that illustrates how to build Java web applications using the Spring MVC framework
https://github.com/spring-projects/spring-petclinic/

JSP-with--
Views custom-tags-
|| Thymeleaf-

+ Bootstrap-(CSS)- && webjars- && Dandelion-

Spring-@MVC-annotaGons-
Controller
Bean-ValidaGon-

@Cacheable-
Service
@TransacGonal-

Spring-Data-JPA-
Repository 3-profiles- default-(JPA)-
jdbc-

https://speakerdeck.com/michaelisvy/spring-petclinic-sample-application
Most tools see code,
not components
 Information about
software architecture
doesn’t exist in the code
“architecturally-evident coding style”
Examples of architecturally-evident
coding styles
Annotations/attributes (@Component, [Component], etc)
Naming conventions (*Service)
Namespacing/packaging (com.mycompany.system.components.*)
Maven & Gradle modules, OSGi & Java 9 modules
JavaScript module patterns, ECMAScript 6 modules,
microservices, etc
 Extract as much of the
software architecture from the code
as possible, and supplement
the model where necessary
Executable architecture
description language
Structurizr for Java and .NET
 Modelling tools
Sophisticated and often complex tooling to create rich models using
UML, ArchiMate, SysML, etc; either by “drag & drop” or reverse-engineering code.

Creates a relatively rich yet simple model,

Richness of model

in a developer-friendly way using

Java/C# code, supplemented with
Static analysis tools
Markdown/AsciiDoc documentation.
Often complex to setup; creates a model
based upon code only; designed for
understanding code rather than
communicating software architecture.
Text-based tools
Very quick and easy to use;
text can be version controlled;
designed to create individual
diagrams rather than models.

General purpose tools

Easy to use; very flexible;
unstructured; no underlying model.
Whiteboard
Create diagrams easily;
usually transient.

Ease of use
public static void main(String[] args) throws Exception {
Workspace workspace = new Workspace(
"Spring PetClinic",
"This is a C4 representation of the Spring PetClinic sample app
(https://github.com/spring-projects/spring-petclinic/)");

Model model = workspace.getModel();

}
// software systems and people
SoftwareSystem springPetClinic = model.addSoftwareSystem(
"Spring PetClinic",
"Allows employees to view and manage information regarding the
veterinarians, the clients, and their pets.");

Person clinicEmployee = model.addPerson(

"Clinic Employee", "An employee of the clinic");

clinicEmployee.uses(springPetClinic, "Uses");
// containers
Container webApplication = springPetClinic.addContainer(
"Web Application",
"Allows employees to view and manage information regarding the
veterinarians, the clients, and their pets.",
"Apache Tomcat 7.x");

Container relationalDatabase = springPetClinic.addContainer(

"Relational Database",
"Stores information regarding the veterinarians, the clients,
and their pets.", "HSQLDB");

clinicEmployee.uses(webApplication,
"Uses", “HTTP");

webApplication.uses(relationalDatabase,
"Reads from and writes to", "JDBC, port 9001");
// components
ComponentFinder componentFinder = new ComponentFinder(
webApplication,
"org.springframework.samples.petclinic",
new SpringComponentFinderStrategy(
new ReferencedTypesSupportingTypesStrategy()
),
new SourceCodeComponentFinderStrategy(
new File(sourceRoot, "/src/main/java/"), 150));

componentFinder.findComponents();
// connect components with other model elements
webApplication.getComponents().stream()
.filter(c -> c.getTechnology().equals(SpringComponentFinderStrategy.SPRING_MVC_CONTROLLER))
.forEach(c -> clinicEmployee.uses(c, "Uses", "HTTP"));

webApplication.getComponents().stream()
.filter(c -> c.getTechnology().equals(SpringComponentFinderStrategy.SPRING_REPOSITORY))
.forEach(c -> c.uses(relationalDatabase, "Reads from and writes to", "JDBC"));
// system context, container and component views
ViewSet viewSet = workspace.getViews();

SystemContextView contextView = viewSet.createContextView(

springPetClinic, "context", "Context view for Spring PetClinic");
contextView.addAllSoftwareSystems();
contextView.addAllPeople();

ContainerView containerView = viewSet.createContainerView(

springPetClinic, "containers", "Container view for Spring PetClinic");
containerView.addAllPeople();
containerView.addAllSoftwareSystems();
containerView.addAllContainers();

ComponentView componentView = viewSet.createComponentView(

webApplication, "components", "Component view for the Spring PetClinic webapp.");
componentView.addAllComponents();
componentView.addAllPeople();
componentView.add(relationalDatabase);
 You can create
many visualisations
from a single model
// upload the software architecture model to structurizr.com
StructurizrClient client = new StructurizrClient("key", "secret");
client.putWorkspace(1234, workspace);
{
 "id" : 0,
 "name" : "Spring PetClinic",
 "description" : "This is a C4 representation of the Spring PetClinic sample app (https://github.com/spring-projects/spring-petclinic/)",
 "model" : {
   "people" : [ {
     "tags" : "Element,Person",
     "id" : "2",
     "name" : "Clinic Employee",
     "description" : "An employee of the clinic",
     "relationships" : [ {
       "tags" : "Relationship,Synchronous",
       "id" : "3",
       "sourceId" : "2",
       "destinationId" : "1",
       "description" : "Uses",
       "interactionStyle" : "Synchronous"
     }, {
       "tags" : "Relationship,Synchronous",
       "id" : "6",
       "sourceId" : "2",
       "destinationId" : "4",
       "description" : "Uses",
       "technology" : "HTTP",
       "interactionStyle" : "Synchronous"
     }, {
       "tags" : "Relationship,Synchronous",
       "id" : "28",
       "sourceId" : "2",
       "destinationId" : "8",
       "description" : "Uses",
       "technology" : "HTTP",
       "interactionStyle" : "Synchronous"
 Diagrams are maps
that help software developers navigate a large and/or complex codebase
Integration with your
build process keeps
models up to date
Once you have a model
of your software system,
you can explore it
 The 1990’s called and
they want their tools back!
It’s 2018 and we shouldn’t be using a general purpose
diagramming tool for software architecture
 Abstractions first,
notation second
Ensure that your team has a ubiquitous
language to describe software architecture
 Thank you!
[email protected]
@simonbrown