Visualising software architecture with the C4 model - Simon Brown, Agile on the Beach 2019
Summary
TLDRIn 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
🗣️ 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.
📚 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.
🔍 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.
📱 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.
📁 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.
📃 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.
🚫 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.
🙌 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.
Mindmap
Keywords
💡Software Architecture
💡UML (Unified Modeling Language)
💡Diagramming
💡C4 Model
💡Containers
💡Components
💡Notation
💡Agile and Lean
💡Tooling
💡Communication
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]
Weitere verwandte Videos ansehen
![](https://i.ytimg.com/vi/9Az0q2XHtH8/hq720.jpg)
Five Things Every Developer Should Know about Software Architecture • Simon Brown • GOTO 2020
![](https://i.ytimg.com/vi/jCd6XfWLZsg/hq720.jpg)
Top 6 Tools to Turn Code into Beautiful Diagrams
![](https://i.ytimg.com/vi/U5e7F3LnHvY/hq720.jpg?v=638f0a8e)
Mehr als Pfeile und Kästen: Architekturdiagramme mit Ralf D. Müller und Lisa Moritz
![](https://i.ytimg.com/vi/pmDhEitrXXU/hq720.jpg?sqp=-oaymwEmCIAKENAF8quKqQMa8AEB-AH-CYAC0AWKAgwIABABGGUgVihUMA8=&rs=AOn4CLCeypYq2TOphxt1bNHHKaw3rE8vbQ)
Project Based Internship Klinikgo Health System Analyst - Company Coaching Video 1
![](https://i.ytimg.com/vi/AwJxkLRfaWI/hq720.jpg?v=5a2ede27)
Como descomplicar seu processo de não conformidades com o Qualiex
![](https://i.ytimg.com/vi/4Q-0JUkLVwQ/hq720.jpg)
Tutorial Diagrammi di Bode lezione #1: introduzione, cosa sono e a cosa servono
5.0 / 5 (0 votes)