Visualising software architecture with the C4 model - Simon Brown, Agile on the Beach 2019

Summary

In this talk, Simon Brown emphasizes the importance of effective communication in software architecture through clear and understandable diagrams. He critiques the common use of whiteboards and generic diagramming tools, advocating for the C4 model, which offers a structured approach to diagramming software systems. Brown highlights the need for diagrams that reflect reality and are comprehensible to developers, using UML as a foundation for abstractions and notation. He provides practical tips for creating diagrams that are both aesthetically pleasing and informative, ensuring they stand alone in conveying architectural information.

Takeaways

• 📈 Embrace software architecture diagramming to improve communication and understanding within your team.
• 🚫 Avoid using general-purpose diagramming tools like Visio for software architecture as they lack domain-specific features.
• 🎨 Use the C4 model (Context, Containers, Components, Code) to structure your architecture diagrams at different levels of abstraction.
• 📐 Start with high-level system context diagrams to establish the environment and users of your software system.
• 🔍 Zoom into container diagrams to detail applications, data stores, and their runtime relationships.
• 📂 Dive deeper with component diagrams to illustrate the structure of individual applications and their components.
• 📝 Include a key legend in your diagrams for clarity, especially when using shapes, colors, and line styles.
• 📝 Use descriptive text within boxes to provide context and responsibilities of each element in the diagram.
• 🔄 Focus on bidirectional relationships in diagrams, but avoid clutter by summarizing or using a single arrow where appropriate.
• 🖼️ Use icons to add an extra layer of information, but ensure the diagram still makes sense without them.
• 🛠️ Explore domain-specific tools and plugins for the C4 model to streamline the diagramming process.

Q & A

What is the main focus of Simon Brown's talk?

The main focus of Simon Brown's talk is on software architecture, specifically diagramming, describing, and explaining software architecture in a way that is effective and understandable to various audiences.

Why does Simon Brown mention that UML usage is often lower than expected?

Simon Brown mentions that UML usage is often lower than expected because there are many reasons and excuses people give for not wanting to use UML anymore, such as it being seen as old-fashioned, not fitting well with agile practices, and the existence of myths and misconceptions about its value.

What is the C4 model mentioned by Simon Brown?

The C4 model stands for Context, Containers, Components, and Code. It is a way of mapping the levels of abstraction in software architecture through four levels of diagrams, allowing for clear and concise communication of the system's structure.

What are the four levels of diagrams in the C4 model?

The four levels of diagrams in the C4 model are: Level 1 - System Context Diagram, Level 2 - Container Diagram, Level 3 - Component Diagram, and Level 4 - Code Diagram. Each level provides a different level of detail and targets different audiences.

Why does Simon Brown emphasize the importance of not using Level 4 diagrams in the C4 model?

Simon Brown emphasizes not using Level 4 diagrams because they are often not worth the effort and can usually be generated automatically from the codebase. They can also be too detailed and cluttered, which detracts from the main purpose of the C4 model, which is to communicate the architecture effectively.

What is Simon Brown's advice on creating effective software architecture diagrams?

Simon Brown's advice for creating effective software architecture diagrams includes focusing on abstractions first and notation second, using clear and concise titles and descriptions, being careful with acronyms, using consistent layout and color coding, and ensuring that diagrams can stand on their own without needing additional explanation.

What are some common mistakes people make when drawing software architecture diagrams, according to Simon Brown?

Some common mistakes include using general-purpose diagramming tools that don't understand software architecture, overusing icons without context, hiding the narrative within the diagram, and creating diagrams that are too detailed or cluttered, which can confuse the audience.

What tooling does Simon Brown recommend for drawing C4 model diagrams?

Simon Brown recommends using tools that are specifically designed for the C4 model, such as PlantUML with C4 model plugins, or his own set of tools that he has developed, which range from free to commercial offerings.

How does Simon Brown suggest using icons in software architecture diagrams?

Simon Brown suggests using icons to add an additional layer of information, but only if they complement the diagram that already makes sense. The key is to ensure that the diagram remains understandable even if the icons are removed or their meaning is not immediately clear.

What is the importance of having a consistent key or legend in software architecture diagrams?

A consistent key or legend is important because it helps to explain the shapes, colors, line styles, borders, and acronyms used in the diagrams. This ensures that everyone, including new team members or those who are not familiar with the diagrams, can understand the meaning and structure of the diagrams.

Outlines

00:00

🗣️ Introduction to Software Architecture Diagramming

The speaker, Simon Brown, introduces the topic of software architecture and the importance of diagramming. He discusses the common reluctance to use UML and the prevalence of poor architecture diagrams. He emphasizes the need for effective communication in software development and suggests that UML can be a valuable tool despite its critics.

05:00

📚 The C4 Model for Software Architecture

Simon Brown explains the C4 model, which stands for Context, Containers, Components, and Code. He outlines the four levels of diagrams in the C4 model and their purpose, emphasizing the importance of abstractions over notation. The model aims to help developers and architects communicate software architecture effectively to different audiences.

10:01

🔍 System Context Diagram

The speaker illustrates how to create a system context diagram, which shows the software system in relation to its environment, including users and other systems. He uses the example of an internet banking system to demonstrate the process of identifying users and external systems and how they interact with the system.

15:02

📱 Container Diagram

Simon Brown explains the container diagram, which focuses on the applications and data stores within the software system and their runtime interactions. He details the components of an internet banking system, such as the web application, mobile app, API application, and database, and how they connect and communicate.

20:06

📁 Components Diagram

The speaker delves into the components diagram, which provides a detailed view of the architecture within a specific container. Using the API application as an example, he describes the components and their responsibilities, such as sign-in controllers and account summary controllers, and their interactions with other systems.

25:08

📃 Notation and Diagramming Tips

Simon Brown offers advice on notation and diagramming, emphasizing the importance of titles, layout consistency, and the use of acronyms. He discusses the use of boxes and lines to convey structure and relationships, and the need for a legend to explain diagram elements. He also advises against overcomplicating diagrams and recommends using tools that support the C4 model.

30:09

🚫 Avoiding Common Pitfalls

The speaker warns against common pitfalls in diagramming, such as using general-purpose tools like Visio, which are not tailored to software architecture. He recommends using tools that support the C4 model and provides his own recommendations for such tools. He also stresses the importance of abstractions over detailed notation and the need for diagrams to stand alone without additional explanation.

35:10

🙌 Conclusion and Q&A

Simon Brown concludes his talk by summarizing the key points of the C4 model and diagramming tips. He encourages the audience to adopt the model and avoid using level 4 diagrams. He invites questions from the audience, wrapping up the session with a call to improve software architecture documentation.

Keywords

💡Software Architecture

Software architecture refers to the structure of a software system, the discipline of creating such structure, and the documentation of that structure. In the video, Simon Brown emphasizes the importance of effectively communicating and documenting software architecture through diagrams, which helps teams understand and build systems collaboratively.

💡UML (Unified Modeling Language)

UML is a standardized modeling language used to visualize, specify, construct, and document the artifacts of software systems. The speaker mentions that while UML is widely known, it's not universally used, and he discusses reasons for its underutilization and how to overcome these challenges.

💡Diagramming

Diagramming in the context of software architecture involves creating visual representations of system components and their relationships. The video script highlights the challenges of diagramming, such as the use of whiteboards and the resulting poor quality of diagrams, and suggests that proper training and tools can improve this process.

💡C4 Model

The C4 Model is a method for visualizing and documenting software architecture using four levels of abstraction: system context, containers, components, and code. Simon Brown introduces this model as a structured approach to creating diagrams that can be understood by different stakeholders, from developers to product owners.

💡Containers

In the C4 Model, containers represent the runtime elements of a software system, such as applications, databases, and file stores. The video explains that containers are crucial for understanding how different parts of a system interact and are deployed.

💡Components

Components are the building blocks within a container, representing modular parts of the software system with well-defined interfaces. The video emphasizes the importance of accurately depicting components in architecture diagrams to reflect the actual code structure and responsibilities.

💡Notation

Notation refers to the symbols, shapes, and lines used in diagrams to represent different elements and relationships. The speaker provides tips on using consistent and clear notation to make diagrams more understandable and effective for communication.

💡Agile and Lean

Agile and lean methodologies are approaches to software development that emphasize flexibility, collaboration, and rapid iteration. The video discusses how good communication, including the use of architecture diagrams, is essential for teams to work effectively in an agile or lean environment.

💡Tooling

Tooling in the context of software architecture refers to the software applications used to create and manage diagrams. The speaker recommends against general-purpose diagramming tools and suggests using tools specifically designed for the C4 Model to improve the quality of architecture diagrams.

💡Communication

Effective communication is a key theme in the video, where it is stressed that clear and consistent communication through diagrams is vital for team collaboration and understanding. The speaker advocates for diagrams that can stand alone and convey a clear narrative without needing additional explanation.

Highlights

The talk focuses on software architecture, diagramming, and explaining software systems.

Simon Brown, an independent consultant, discusses the use and misuse of UML in software architecture.

The speaker addresses the common reluctance to use UML and the prevalence of poor architecture diagrams.

The importance of effective communication in software development is emphasized to avoid slowing down teams.

The speaker introduces the C4 model, which stands for Context, Containers, Components, and Code.

The C4 model provides four levels of diagrams to map different levels of abstraction in software architecture.

The speaker advocates for a back-to-basics approach to software architecture diagramming.

The importance of abstractions over notation is highlighted, with a focus on understanding the system's structure and components.

The speaker suggests using UML as a standard notation to diagram software systems, similar to how maps use key legends.

The C4 model is presented as a way to create diagrams that can stand on their own, providing clear and understandable information.

The speaker recommends against using general-purpose diagramming tools like Visio for software architecture diagrams.

The speaker provides tips for creating effective diagrams, including using titles, layout consistency, and avoiding excessive text or icons.

The speaker emphasizes the need for diagrams to reflect reality and be understandable to developers and other stakeholders.

The speaker suggests using tools specifically designed for the C4 model to improve the quality of software architecture diagrams.

The speaker concludes by encouraging the audience to focus on telling valuable stories with their diagrams rather than getting caught up in the details of notation.

Transcripts

right good morning thank you for joining

me

so this talk is about software

architecture and specifically

diagramming and describing and

explaining software architecture for

those of you who don't know me my name's

Simon Brown I'm an independent

consultant specializing software

architecture show of hands who here uses

UML that's more than I was expecting

which still not everybody so when I

asked this question in my travels around

the world it's typically a little bit

lower than this and maybe this is a sign

of why companies get me in so typically

it's about Tim set of people who use UML

and there are lots of reasons for this

and I think I've heard every single

reason you can possibly imagine as to

why people don't want to use UML anymore

and there's a book about this you can go

by it's called 97 ways to sidestep UML

by no formality and I've literally heard

all of these different excuses some of

these are just crazy you know you'll be

seen as old-fashioned if you use UML

it's not expected in agile the value is

in the conversation and you know since

we've been doing the outdoor thing we

perpetuated lots of these myths and lots

of these excuses for not using UML and

of course one of the recommendations for

drawing architecture diagrams to explain

your software to other people is to just

use a whiteboard and although that kind

of makes sense on the face of it we

don't teach people how to do this so one

of the things I do is I get to travel

the world and I run software

architecture diagramming Carter's

exercises where we give people

requirements and I say go draw some

pictures and we get diagrams like this

and that and this one which is my

favorite I think

that's like London Heathrow Airport this

one here shows that our system does

business logic the logical view

Stormtroopers whatsit crossing out

renaming these are real pictures and

real works that sort of run over the

years and to be fair some of these are

the more extreme diagrams because I'm

trying to make a point let me show you

some diagrams from a workshop I did last

month it's not as bad as some of the

diagrams I've just shown part of the

exercises we get we switch diagrams so

every group gets different set of

diagrams to look at and we rcent to give

these diagrams a score out of 10 what

school would you give this diagram out

of 10

8 7 6 this is called a 7 it's not great

doesn't tell you anything all right this

one what score do you give that for 8

note 7 this one 7 that one 7 there

doesn't tell you anything this one here

7 I did not I'm not making this up all

of these people scored other group 7 out

of 10 this one here 7 this one here no 6

and the funny thing about this diagram

it is actually has more detail than the

others and for some reason the teams

thought now this is too much and we

don't understand it so we're gonna grate

it lower so this whole just use a white

ball thing doesn't necessarily work very

well

now the exercises I run they tend to be

quite short they're like 69 to 90

minutes so maybe people had more time or

they had a tool they were allowed to use

computers they could draw better

diagrams and unfortunately that's not

the case so if you go to Google and you

do a search for the software actitude

diagram it goes sure here are some

diagrams for you and these are all

garbage

well so they look nice they're all Nina

nice squarish boxes and stuff and we've

got nice colors they all have exactly

the same problems as the hand-drawn

pictures we have boxes and no lines we

have different shapes but we don't know

why different colors we don't know why

different sizes of boxes we have layers

both horizontally vertically we have

acronyms no titles there's just our

whole bunch of stuff going wrong with

all of these diagrams the building

industry if we look at the building

industry if you ask an architect to draw

you a floor plan of where you live

you'll get a floor plan and you can look

at the floor plan and go yes I'm windows

doors I get this if we were asked to

draw a floor plan we go yeah sure here

you go he's a floor plan of my house

it's like what but logically and

conceptually speaking this makes perfect

sense so these little red dots here

that's my Wi-Fi hot spot because it's

important but don't ask me all the dash

lines mean I have no idea so I think we

need to take a little bit of a kind of

back-to-basics approach because we

should be engineers and we're trying to

be artists and I think we should do

something a bit more engineering and the

whole point of this of course is if we

want to be lean and agile we want to

move fast as a team unit we need to

communicate well and I've visited lots

of organizations recently where their

lack of communication is literally

slowing them down because teams don't

have a common vision of even what they

are going to build or what they are

building or what they have built one of

the other things against UML potentially

is that it's very technical in nature

and if you want to describe your

software systems to developers and

architects that's fine if you want to

talk to product owners scrum masters

testers whatever there's a whole

audience out there that doesn't

necessarily know UML so we need to

target again the storytelling we need to

target our stories of different types of

audiences so our top tip in all of this

is when you're drawing architecture

diagrams don't think like an architect

think like a developer and this won't

affect counterintuitive but when I'm

running these design exercises

the developers and the people who attend

my workshops they can do the design part

so they can design a solution but when

you ask them to draw it they forget

everything they've ever known they put

their architects hat on and they start

drawing all these really high-level

fluffy conceptual pictures that

literally make no sense and one of my

goals here is when I when I get when I'm

asking if you have to draw acted two

diagrams good architecture diagrams I

want them to reflect reality so when you

show them into another developer they go

yes and that's exactly what we're

building I think in order to do this we

could look at UML UML gives you a sense

set of things and a standard notation to

diagram those things I think the things

the abstractions is actually much more

important than the notation and one of

the reasons people cite for not using

UML is that the notation is very

complicated so I'm a abstractions first

kind of person here notation second and

although this might sound a bit foolish

if we go get two local maps of this area

the two local maps are going to show you

the same things aren't they the towns

the train lines the bus routes the

schools the churches the museums the

points of interest the two maps will

show the same things the same

abstractions but they'll likely use

different color coding line styles

notations shading icon symbols and so on

and the key to understanding a map is

the key there's a key legend on the map

and it tells you we know when you see

this sign that's what it means and I

think that's a really really powerful

and simple concept that we can just

borrow so what are the abstractions when

I'm thinking about describing and

documenting and explaining a software

system for me that software system is

made up of one or more containers not

docker so I've been teaching this

approach for well over 10 years now and

docker got popular and kind of stole the

word container by container I basically

mean an application or a datastore so

something to runs your code something

you need to deploy and run somewhere or

something where your data is being

stored

so in real terms a container might be a

mobile app running on your mobile device

back-end server side app a console app a

Windows service written c-sharp a Python

script a database schema a folder on a

file share and Amazon s3 buckets a

dynamo DB you know all of that type of

stuff that's what I mean by container we

look inside these containers I'm going

to say they are made up of components so

components is a hugely overloaded word

but basically what I mean by component

is a grouping with stuff yeah modularity

nice boundary nice clean simple

interface running inside a containers

that's the important part here we've got

a hierarchy and if we look inside

components they're mostly made up of

code level elements so if you're

building your Java apps you have a bunch

of components built with Java classes

and interfaces for example and that's it

it's a simple hierarchy a hierarchy of

structural elements so we can then use

to describe software architecture and

then that leads me to the c-4 model

which is in the title of this talk so if

you want to point other people at the c4

model you can go to c4 model dot-com c4

stands for context containers components

and code and it's four levels of diagram

that map ons those levels of abstraction

as Tendai said in the keynote I'm going

to tell you a story and that story is

going to be linear the one thing I do

not want you to take away is Simon says

we must draw diagrams in this order

because a lot of people do that and then

they kind of superimpose Simon therefore

says we should do design in this order

as well and that's not what I'm saying

so this is just the collective diagrams

you can draw in any order to describe

your software systems at different

levels of detail that's basically what

this is all about and it's essentially

the way I think about this is diagrams

as maps so I live in Jersey in the

Channel Islands and if you open up your

your Maps app on your smartphone and you

do search for Jersey you'll get that

picture by default so Google Maps for

example zoom straight in says are you

interested Jersey

this is what Jersey looks like if you

want to know what the major places are

in Jersey where I live that's useful if

you've never heard of it and you've done

the where Jersey is it's pointless you

have no context so you get to zoom out

or zoom in to tell different stories to

get different levels of information and

it's the same thing with these diagrams

we have different levels of diagrams to

tell different stories different

audiences and the purpose of this talk

is really just to show you the sea for

kind of core diagrams the static

structural diagrams but once you have a

good idea of your static structure and

you're able to talk about your static

structure you can then use these same

concepts to draw runtime diagrams

sequence diagrams deployment diagrams

and so on and so forth so this is kind

of really nice starting place I'm going

to show you a bunch of example diagrams

based upon an internet banking system so

imagine we work for a bank

and the bank wants us to build an

internet banking system so I'm going to

start from the top again storytelling

and I'm going to draw a level 1 system

context diagram and the system context

diagram basically shows the thing you

are working on or building and stuff

around it in terms of other systems it

talks to and the people who use your

system so we're going to start with a

box in the middle and this represents

our internet banking system as a

software system don't worry about

notation and shapes and color coding

I'll cover all of those tips later so in

order to draw this diagram we now need

to ask a bunch of questions like who's

using it so now we look at roles or

users or personas and we come up with a

bunch of people who are gonna be using

our software system so in this example

let's say there's only one type of user

it's personal users of the personal

banking customers so you and I as

account holders we want to use the

internet banking system to get

information about our accounts and maybe

make some payments where does this

system get its information from well

let's say the bank has an existing

software system a mainframe back-end

banking system and that's where all of

the core banking data is stored so we're

going to have some interaction with that

let's also imagine for the purposes of

this story that we need to send emails

to our customers and rather than

creating our

an email system we just can use the

bank's internal email system so that's a

really nice simple example of a system

context diagram it basically shows you

that's the thing we are working on and

this is the environment the context

around it in terms of people and other

software systems for large environments

you have more boxes and there's a longer

question there about how do you deal

with larger diagrams and we can we can

cover that in a Q&A if you want to so

that's that's level one it's nice and

high level nice and straightforward not

much tech choices on here it's great for

a really wide range of audiences

so it's developers and architects we now

want more detail so what's inside the

interbank you system you know what tech

is it made of how does it work so now

what we're going to do is we're going to

pinch to zoom in to that internet

banking system box and we're going to

drop down to level 2 and level 2 is a

container diagram and this is showing

you all of your apps and safe and data

stores and how they relate and run at

runtime and we're going to build this up

piece by piece so the currently empty

looking box here that is the internet

banking system box from the previous

diagram that's the thing we're going to

look into and we're still going to show

the people and the external systems we

have some one dependency on caveat time

what you're about to see is how I might

design an internet banking system you

might not agree with my design that's

fine park those thoughts but this is how

I might design the diagram and of course

I needed to do that in order to show you

a diagram so first we're gonna have a

deployable web application so imagine

you open up your web browser you go to

my bank comm forward slash internet

banking you get a bunch of static

content back in your browser HTML CSS

JavaScript that's gonna be served from

this back-end web app which I'm going to

say is a Java spring MVC app once you

get all of the static content back into

your browser I'm going to say that

actually that's going to be a single

page app essentially running client-side

in your browser so I'm going to model

that as a separate box in this diagram

so now I've got a bunch of JavaScript

code essentially running on my web

browser that's my UI for my interbank

Inc system it's a single

jab in this case it's JavaScript and

angular how about we give people a

mobile app as well so let's build a

separate mobile application using this

case the cross-platform xamarin

framework and that's an alternative UI

that we can present present to our

customers how do the single page app and

the mobile app gets data from the

backend banking system well they need to

go through something so I'm gonna say

we're gonna have a separate API

application exposing a bunch of jason

that over HTTP endpoints that's a

separately deployable Java spring MVC

web application so now we have two web

applications where we're deploying

server-side you could have one I'm

choosing two we need to sign in so we go

to the front page we need to add

username password imagine we work for

the bank we go ask the bank can we put

our usernames and passwords in your

back-end banking system they say no so

we need to somewhere to store our own

data so let's have our own database

schema to do that so that's basically in

this case an example contain a diagram

it's showing you the various

applications and data stores the

technologies that built with a bit about

responsibilities on there and how they

connect at runtime so each of these

containers is mostly no I'll tell you

later why I'm using the word mostly

mostly a separately deployable thing and

the links the lines between the

containers are mostly inter-process

communication calls so something with a

network involved somewhere typically

that's level 2 let's imagine that we are

now in a team and we are working on the

API application and we want to see how

that code base is structured so now

we're going to pinch to zoom in and

we're going to down so we're going to

drop down to level 3 and I'm now going

to draw you a components diagram for

that API application now I'm going to do

the same thing so this currently empty

box here represents the API application

box from the previous diagram it's used

by the single page app and the mobile

app and we're going to add some other

stuff to this picture so

you open up the mobile app you need to

sign in so I'm going to say we need some

sort of sign-in API so we can have a

sign-in controller that's going to use

some sort of security component we're

just going to do authentication against

our credentials in the database

hopefully using hash passwords and all

the rest of it once you signed in you

get a list of your accounts let's

imagine that that's serviced by a

separate accounts summary controller

again that's providing another API

endpoint and that's going to use this

really horribly names mainframe banking

system facade component which talks to

the horrible back in banking system if

somebody wants to reset the password

yeah we'll give them the way to do that

as well in a more real-world example you

could seed have many many more

components on this diagram and again

there's another question here about how

do you deal with larger systems but this

is a nice simple example of the

components that sit inside that API

application it's at this point of course

that we now need to start talking about

lower-level text choices so we got

spring beans and spring MVC rest

controllers and there's some other

high-level Czech tech choices and

frameworks on here if I were to open the

code base for this API application I

would expect to see very clearly these

six things somewhere in my codebase so

at level 3 at the component level your

architecture diagram now needs to start

reflecting your code structure at a high

level so it needs to be a nice one to

one mapping between concepts on this

diagram and concepts in your code base

whether those concepts are language

level modules maven modules Gradle

modules components packages namespaces

jar files dll's so there has to be some

organization structure which is reflect

on your diagram South's level 3 level 4

so I don't recommend doing level 4 I'm

going to say that again because people

always miss this I do not recommend

doing level 4 because it's not worth it

and often you could just generate level

4 automatically from your IDs

to show to tell the story I'm going to

show you an example so let's imagine we

are working on this horribly names of

mainframe banking system facade

component thing and we want to see

inside it class diagram so this is where

UML is super useful for documenting and

diagramming those low-level aspects if

you want to diagram level 4 for

complicated components or when there's

something bit funky going on feel free

but in most in 99% of situations do not

draw a level 4 diagrams just automate

them for your your IDs so that's the

diagrams system context containers

components code and we're done

notations important and there's lots of

subtleties in the notation and the

example diagrams I wanted to go through

very very quickly so some tips for

notation tip number one put titles on

pictures I know this sounds super

obvious but when I run my workshops 80%

of diagrams first time rounds do not

have a title and you have no idea what

you're looking at so when I'm titling a

diagram I want to be very explicit about

two things what type of diagram is this

and what's the scope so if I'm drawing a

system context diagram for a financial

risks and I'll let you leave it like

that so I'm very specific and very clear

here layout if you don't have access to

whiteboards you know if you're writing

on paper it's kind of hard to raise you

can use sticky notes and then index

cards represent your boxes

move them around get a like you like

that's fine

I wouldn't necessarily deliver diagrams

as a collection of sticky notes because

they will fall off and it just kind of

looks a bit cluttered I will try to aim

for some visual consistency so if I've

got multiple levels of detail I will try

to always keep my people in the same

visual location on the diagram cameras

for example and I'll try to use the same

color codings and shapes across all of

my levels of diagram and you would have

seen that in the examples I just showed

you be super careful with acronyms if

you are targeting your diagrams at

technical people like developers and

architects don't worry about explaining

MVC and ASP and JDBC and all that stuff

because we probably get that focus more

on the domain-specific acronyms the

business acronyms or the funny jargon

that lives in your companies so code

names for systems or code names for

teams that sort of stuff catches our new

joiners really really quickly boxes and

lines so that start with boxes or more

specifically elements when I'm drawing a

diagram for the first time I'm going to

forget about shape and color and I'll

talk about why in a second but I'm going

to just draw plain boring boxes and

inside my boring boxes is a bunch of

text if you look at the top three levels

of the C for diagrams so context

contains components these are basically

the only four types of elements I expect

to see on the diagrams so it's a very

simple language you can teach people so

the system contexts diagram shows people

and software systems the container

diagram shows people software systems

and containers and the component diagram

tension shows all of these things so

every box is going to have a name a

naming is hard and whatever but

hopefully we're going to give everything

a nice simple easy to remember name I'm

also going to be very explicit about the

type of the elements so I'm going to

write in the box this is a person or

this is a software system because then

we know what we're getting and there's

no guessing for the two technical things

down here the containers and the

components this is where we can start to

weave in those text choices so this is a

database scheme or this is a spring MVC

app the rest of the text in the box is a

short description either as a sentence

like you see here or maybe just so you

know five or seven bullet points to list

out the key responsibilities of that

element and it's at this point people

say well why are you putting so much

text in your boxes because that's not

how we do actor two diagrams well that's

why they're a problem

so here are two example Arteta diagrams

this is the one

on the left is what we typically do it's

just a bunch of named boxes and I do

something like that on the right if I if

you saw this diagram on the left for the

very first time and I said to you can

you describe what the content of data

does your response would be it updates

content yes what about the file system

what is a file system do it stores files

so the names are not particularly

helpful but over on the right-hand side

here we've got more text so even if the

names are a bit odd and a bit ambiguous

and bit vague at least we can now read

the text and go okay the name doesn't

make sense but now I know what the thing

does so we're adding a degree of

explicitness to our diagrams but do keep

that short I've seen people writing

entire essays in the boxes and that's

not what our employer either lines pay

some attention to lines because lines

give you structure lines glue your boxes

your elements together my preference

here is you need directional lines only

so all of my arrows go one way so you'll

never see my diagrams with straight

lines for now arrowheads or lines with

arrowheads on both sides and this raises

an interesting question we're twenty

point arrows and it's up to you so there

are no hard and fast rules in any of

this my preference is for thing a calls

thing B or thing a depends on thing B if

you want to show events or messages or

information flow that's absolutely fine

just make sure the direction of your

arrow matches the text you put on the

arrow to describe it the other kind of

catch here is that most relationships

are actually bi-directional aren't they

so if we think back to the intent

banking system we've got the single page

app and that's making a request to the

API app and the API app is sending a

response back essentially so two

bi-directional relationship and although

that makes sense if we show both

directions for every relationship we

came to get a very very cluttered

diagram really really quickly so what

I'm going to do instead is I'm going to

summarize the intent of those two arrows

in a single arrow so I would rather say

something like that the single page

application

makes API calls using the API

application I will try to avoid users

again uses is quite a general vague

generic term so I'll try to be as

specific as I can but keep it short and

having said all of this sometimes you do

want to show both directions so if

you're if you know you've got a

bi-directional relationship but those

two directions are very different in

nature very different in its intent then

I will show those directions so maybe we

have two micro-services a and B and

maybe at startup time a can request a

list of stuff and be using a synchronous

call so that's one relationship and then

maybe at runtime as events are coming in

we've got a kind of rule cast thing

going on as well so because those are

two very different types and

relationships I want to show those very

clearly on the diagram

another trap people fall into is they

kind of hide the two-story so imagine

you drawing a container diagram you've

got a microservices architecture

everything was going into and out of a

message bus you tend to get

hub-and-spoke diagrams that look a lot

like this and again although that's

factually correct you know we've got a

couple of micro versus here if stuffing

things into a barson stuff coming out we

may be missing some really important

information so what I'd rather do is

perhaps draw something like this instead

so miss off the message bus and instead

say actually there's a point-to-point

relationship here between a and B and

we're just using Kafka or rabbit as the

messaging mechanism for doing that so

again there are no hard and fast rules

here it's really do the diagrams tell

the story that you want to tell and add

more words a lot of this is adding more

words to make stuff much more explicit

and a really good simple tip here is

just read your diagrams out aloud so in

this case the trade data system sends

trade trade data to the financial risk

system and because that makes sense as a

sentence we could have a key legend so

every set of diagrams should have a

consistent key and

to describe shapes colors line styles

borders acronyms and so on even if it

seems obvious to you so we're not a hawk

tetra Carters we kind of draw some

diagrams in the morning and everybody's

using different color Sharpie markers

then we go for lunch and then they come

back and like why is this line red they

drew two hours ago but they've forgotten

this is an example of a diagram keyer

diagram legend so this is my container

diagram up here for the interbank II

system and that's the key of the legends

that I would use to describe this

diagram so that - box is the system we

got these various blue boxes here for

showing containers and I'm using

different shapes to show different types

of containers

people-people gray boxes are external

software systems in this case I'm just

saying there are relationships and I'm

not being specific about relationships

but you can be so if you want to show

synchronous relationships different from

asynchronous relationships you could do

something like solid lines for

synchronous relationships and and dash

lines for asynchronous and you'd have

that in your key or a lot or your legend

if you wanted to use different colors

for different protocols so maybe green

lines are secured by HTTPS and red lines

are insecure then feel free do watch out

for colorblindness especially red-green

color blindness and also watch out for

black and white printers because that

will happen at some point so with that

in mind my advice is to use shape and

color to complement a diagram that

already makes sense so in other words if

you take a diagram and you remove all of

its color and you remove all of the

shapes the diagram should still make

sense and the reason it makes sense is

because a lot of the texts we add to the

diagram helps it make sense to versions

of the same diagram which one D tend to

prefer that one on the right yeah it

kind of looks nicer it's a bit more

aesthetically pleasing because you can't

read the text so I can't read the text

from here either by the way because you

can't read the text

looking at the diagram on the right

you're you're able to kind of understand

it and comprehend it a bit quicker

because you're confirming what you think

you're seeing so we think those things

that top look like people I guess

they're people when you read sex these

things look like data storage things

down here so and again that the shapes

help but fundamentally these diagrams

have the same level of information and

that information is captured in the text

all of this advice goes for icons as

well do you ever see people drawing

these diagrams with the Amazon AWS icon

set or the Azzurri I can set they kind

of look pretty and they're great if you

want to show all of their own Amazon

services you're using but they're

basically pointless because I don't

understand what half the icons mean and

I don't know why these things have been

chosen anyway so these diagrams don't

tell me enough from a software

architecture perspective so what I'm

gonna do here is if you do want to use

icons feel free but use the icons to

again add an additional level or layer

of information so here's an alternative

version of my inset banking system

container diagram now we've removed the

color and I'm now using some icons

instead so if you know what the icons

mean you can see there's a couple of

Java spring apps there's a database

schema we've got angular and xamarin if

you have no idea what the icons mean it

doesn't matter because all they're all

the informations in in there in the text

and your key or your legend should have

examples of what those things mean of

course and the whole point that this is

what what I'm trying to do is make the

diagrams able to stand on their own so

whenever I see arced it two diagrams you

normally have to have a conversation to

explain what the diagram means because

the diagrams are basically hopeless and

that's fine if you're there but often

what happens is people draw a diagram on

a whiteboard I take a photo stick on

confluence and that's where it lives

forever more someone new joins your team

send them to confluence they have no

idea what the diagram means they have to

go find the person who drew the diagram

Oh guess what they quit four months ago

so what we do is we'll spend another

three hours with a different group of

people at the same whiteboard redrawing

the same one not the same picture

something that we hope looks like the

same sort of picture and we just

repeating whistling as I was down any

narrative you give any presentation you

give any supplementary documentation he

write again should tell stories on top

of a diagram that already makes sense so

what I'm trying to do is I'm trying to

make us spend our time telling more

valuable stories rather than why's that

box blue and this one's red well let's

let's just get that stuff down

next time you draw a diagram there's a

notation checklist you can find at c4

model of comets or a single page PDF

completely free to download run through

this answers them yes-or-no questions

and this will hopefully give you some

tips on how you can improve your

software architecture documents I have a

couple of slides left and then we can

open the floor for Q&A a lot of people

ask me what tooling do I recommend I'm

going to give you two recommendations

recommendation one I'm gonna give you

three recommendations recommendation one

do not use Visio and by Visio I mean

Visio OmniGraffle lucidchart

draw the i/o and Gliffy all of those

stuff please do not use them because

they're general-purpose diagramming

tools and they don't know anything about

software architecture so those are the

worst categories of tools you can use

they're the most common but they're the

worst categories of tools you can use so

my first recommendation there's a whole

bunch of tooling out there for the c4

model c4 plant two UML so if you come

across plant to your mail it's a way to

draw UML diagrams or not I'm using text

so you write some text you throw it

through a tool and it does automatic

layout thing for you so someone created

a set of macros a set of plugins for

plant UML and they allow you to draw the

c4 diagrams using a kind of c4 model ish

domain-specific language all complete

battle applying UML so that's my

recommendation number one recommendation

number two is my own tooling sorry so

I've been dissatisfied with a lot of the

tooling out there for drawing acted two

diagrams so I've got a whole bunch of

tooling I've built myself some of its

free something's open saw some of its

commercial but there's a whole bunch

tooling out that you can find that helps

you draw

software architecture diagrams

specifically targeted to add the c-4

model

no matter which tooling you do use

abstractions first notation second so if

you take this back to your team so

anyone to adopt it make sure everybody

understands those four levels of

abstractions the four key diagram types

tell them not to use level four and then

just go forward from there and that's me

thank you very much

[Applause]