Are you still drawing boxes? That's
probably why your architecture diagrams
fail. Let's be honest, most architecture
diagrams are a disaster.
Imagine that you walk in a new team and
the only diagrams that they have is from
3 years ago. So, a monolith that they
modernize and it's just a distributed
mess. or someone is uh sending a system
overview and at the end it's just a
lucid chart diagram with 47 unlabeled
arrows and the arrows are going
everywhere and the consequences
new engineers takes week to ramp up
teams misunderstands the scope of the
things that we need to build and they
build something that we don't want
architecture became a guessing
Instead, it should be share knowledge
across the teams. That's why your
diagram don't work because you are
drawing the wrong boxes to the wrong
audience at the wrong level. They
reflect the creator's perspective, not
the needs of the readers. This is where
the C4 model flips again. It's a visual
language designed with layers of
obstruction so you can show the right
details to the right people at the right
time. So in this video I will introduce
you to the technique. But first let's
define what the C4 stands for. It's
called C force because there are four
layers in these diagrams. Context,
container, component and at the top we
have the context level. This is the big
picture, the blackbox view. You describe
your system as a single unit, its
purpose and how it interacts with the
external actors, users, other systems,
APIs. This is the view I would use when
talking to business stakeholders or the
tech leadership. It gives them clarity
on what the system does and who it
serves without getting lost in technical
details. Usually it should answer the
questions what is the scope of software
system we are building? Who is using it?
What system integration does it need to
support? Next is the container level and
no this container has nothing to do with
Docker. Here you break down the system
into runnable applications or services
like a front- end web app, a backend
API, a database and so on. This is where
I start having productive discussions
with tech leaders and platform teams.
It's still abstract but technical enough
to talk about how the system is
structured and how responsibilities are
split across different parts. At the
container level, we can also discuss
about uh the organization, therefore
team topologies or how we are going to
structure our teams in order to deliver
uh the system that we are expecting to
build. We should answer the questions
what are the major technology building
blocks, what are the responsibilities
and how do they communicate. Then we go
deeper into the component level inside
each container. What are the logical
building blocks? Think about features,
modules or internal services.
This is the level where developers
usually get involved. We start talking
about responsibilities, interfaces, and
collaboration boundaries inside each
application. Finally, there's the fourth
C, code level. This is the most detailed
view in the C4 model, but in reality,
it's rarely used. In my experience, most
teams don't need code level. If you have
modeled components well, you have
already got 90% of the clarity you need.
Code level is meant for very specific
situations. Documenting internals for
audits or aligning on a critical
implementation detail. Most of the time
the component level is already more than
enough. But now we need a tool in order
to express these things. And for today I
decided to go with ice panel. Icepanel
is a visual software that enables us to
design C4 model properly with guidance
and that's the part that I love the most
about uh this this tool. But without
further ado, let's try to discuss a
concrete example. What we are going to
talk about is a modernization
This is uh what we are going to uh look
at as an example. Uh it will be just uh
the beginning where we already have
e-commerce that has to be modernized. We
are going to use uh let's say
cloudnative solutions and we are going
to uh use NodeJS for few things. So we
already have let's say uh some context
that is provided by the current context
because the developers maybe are already
JavaScript developers. They're using
Node etc. and we are just breaking up
into uh uh multiple microservices.
Usually what I do is three things. So I
try to use um uh this mental model where
I understand the business part. I
understand the architecture
characteristics uh and I define them
where uh I want to understand better
what are the latency requirements or
what are the availability security where
you name it and finally I look into tech
and those are the three steps that I
take when I start to design a brand new
architecture. Now potentially if I go in
a room with you and start to design
something like this uh to say okay so we
start with the user that uh will access
our catalog and then in order to make a
uh a purchase or place an order uh is
going uh through the sign up process
first and then the checkout and I
explain all of these it might be enough
for this meeting but the reality is we
want to do more. We want to have the
possibility to uh explain more details
based on the type of audience that we
have uh what we want to achieve with
this modernization. Hence why we're
going to jump into uh ice panel for
designing uh our architecture. Let's
start with the context view. So as you
can see here we have a very high level
design of how our modernization uh is
going on. So we have our new e-commerce
that we are going to drill down at the
next level of the C4 model that is
connected with different external
system. We have for instance Contentful,
we have Twilio uh and so on so forth. We
have also some internal system like the
fulfillment system. This is uh part of
the monolith and therefore we are not
going to touch it. Uh so we are just
signaling the fact that we are going to
use for orders. uh if we want to model
later on and transform into uh a
modernized system like we have done uh
with the e-commerce we can then do that
but at this stage uh is fine one thing
that I really love about this view is a
very coarse grain so you have a
eagle-eye view of how the system works
you can explain to uh the seuite what is
the complexity that you need to handle
inside the system and moreover if you
properly design through cifer model you
can have this nice annotation like as
you can see Here uh I can have an
e-commerce that is connected with
bootable parts and the notifying users
through to Ilio and send a push
notification to the new customer. Now
here I'm just showing uh clicking around
the diagram because it's an interactive
diagram that is offered by uh ice panel
but at the same time later on we are
going to see a more powerful tools uh
for uh dealing with this kind of
scenario. One thing that I want to
highlight to you is that always design
properly the diagram because you will
thank yourself later when you want to
add the new feature or the new box. It
will be a breeze to do that and it's not
going to be as complicated as it uh
usually be. So I highly encourage you to
spend time designing proper diagrams
because that will provide clarity, will
provide uh simplicity and also uh will
simplify your life in the long run. Now
let's drill down uh to another level
from context diagram into the containers
diagram. So I'm just I just entered
inside the e-commerce as you can see
there is a a big blocks here uh that is
this uh rectangle here say e-commerce
and all these stuff are the
microservices and micro front ends that
we have created uh for our e-commerce so
far they are currently uh available
inside AWS that is the cloud provider of
our choice and we have all the different
integration now uh I've also divided
this system in different subdomains or
groups as they are called in in uh ice
panel and here um I can think about
groups like a way for logically divide
my system but also I can have multiple
groups that are needed uh in order to
associate a group or a part of the
system to teams that is another
capability that you have inside uh uh
ice panel as you can see here at the
bottom I have teams and I can have let's
say a team that is responsible for a
system or for uh a specific part of the
system or a service whatever. So that is
a very handy feature that you have uh in
order to handle uh this capability in
every single box when you select them
you have uh this area on the right this
panel that uh shows up and you have here
add technology. So over here you can add
one and say okay so this one is another
Dynamob stream uh sorry Dynamob table
and here we are. So now you have uh and
you can add obviously multiple
technology you can search from all the
one you can create your own if you have
your specific technology and so on.
Let's try to drill down a bit more about
the system. So um we have a a new
customers that wants to browse uh a
specific for a specific product in this
case a new camera uh is going to call
this catalog mic front end and then you
have catalog back end uh catalog
databases catalog database and catalog
metadata. As you can see here, I want to
draw your attention that there is this
part that I modeled already uh as a
component diagram and we are going to uh
see that how it works. Uh and also we
can see that this catalog metadata uh
back end is interacting with fetches
data from uh the CMS and pump data into
uh personalization uh so this is a very
uh clear way to handle that. But let me
show you also how you can do what you
can do with the ice panel. Here there is
a capability called flow that imagine is
like a sequence diagram that is fully
interactive. So let me show you how it
works. So select the flow then I click
play flow. Now I can walk you through
all the different steps that are
happening or for placing an order. So
first of all a new user wants to place
an order called the checkout mic front
end retrieve the serverside render
version of the checkout page. When they
place an order the first thing that
happens is uh request an order ID to the
checkout back end is returning uh the
order ID to the checkout front end
therefore to the browser. So that is
used in order to uh let's say associate
the ID with all everything that's
happening uh after that. Then it's
calling a user inserted card details uh
to aeron system is ADM. So it's
redirecting the user towards the ADM
payment part and what returns his
receipt ID. Then it will uh pass to the
checkout back end and uh now it's ready
to store this order. Let's now see how
the component level works. So I select a
container that in this case is orders
manager and here I've already specified
uh my components inside the specific
container. So I created a flow so I can
walk you through what I have created. So
the first step is selecting the flow and
uh select the one that I created the
orders manager flow. So as you can see
here I have all the steps available. Now
we start to play the flow. So I can walk
you through what uh uh is happening at
the component level of this C4 model
diagram. So the first step is that the
order database when we store some uh new
order is sending through the Dynamob
stream that is a service that enables us
to capture any change that is happening
into the table uh into uh um an event
transformant that in this case uh is
eventbridge pipes. Even beach pipes is a
service uh that AWS created for
connecting two services one to one. Uh
uh it enables also to have uh the
possibility to run a lambda function uh
while you're receiving a message or in
this case an event and uh in this case
we are leveraging that capability for
retrieving some information from an API
that is still living inside the monolith
and it's the customer's API. So we're
going to gather this data uh from uh the
customer API and then uh when the data
are returned the new message is created
with the order and the information of
the customer uh that we needed to
augmented with and we pass this message
to the order queue. The idea of using
SQS as a queue is because if we have a
million of uh new orders created in a
very short amount of time, we don't want
to overwhelm some services that maybe
doesn't have the throughput that uh is
needed. uh and therefore we want to
capture and create this buffer. Uh so we
want to capture these uh events or
messages into a queue and then another
event bridge pipes will uh take in
batches these messages and send to an
orders orchestrator. This order
orchestrator is uh uh create with step
function. This is another serverless
service that enables us to orchestrate
uh the uh a bunch of fun actions. So in
this case we are going to first send
data for the push notification to an
external system called Twilio that will
send the push notification to the user.
Secondly we are going to send the data
to the fulfillment system that is an
internal system that is needed in order
to uh fulfill the order. Then we send
the data to the CRM that is used from
customer support sending uh the uh
marketing email uh for the order is
dispatch and so on so forth. Now there
is an interesting uh thing. So some
sometimes you need to show uh this level
of detail with also the feature
implementation. So for instance in this
case we want to uh use another server
service that enables us birectional
communication with Salesforce without
using the Salesforce SDK. So we don't
have to maintain the code and integrate
with all the complexity of the API
integration that Salesforce has but we
can do through evenbridge because uh in
this case even brbridge has the
capability uh to integrate directly with
some partners and one of those is
Salesforce and I can have a birectional
communication. So I send the data from
step function to eventbridge and then I
send the information to to Salesforce.
But now this part is new right? So it's
a part that we didn't build yet. There
is an interesting capability of uh um
ice panel for this specific reason. So
if I go here as you can see there is
hide future right. So I can uh go into
the status and as you can see I can tag
my element in uh uh future deprecated
removed or live. This part is the one
that is live. So if can focus uh in the
live part I can uh hide the um the
future implementation or I can show the
future implementation I can focus only
on that and show basically uh what will
be the specific thing that we want to
build what are the uh part of the system
that are in play uh for this specific
future implementation. So if you think
about this and you have a more complex
system, this feature comes extremely
handy because uh in uh uh very few
clicks you can have you filter out all
the noise and you focus on what you
really need to discuss with your
colleagues. That is spoton in my
opinion. Another challenge that I often
have uh is understanding uh the
connection between uh uh objects. In
this case uh I have the orders manager
that as you can see has different
arrows. It's quite pivotal. So if I
select that and I go to connection, I
can see a list of connection uh of this
uh orders manager. But it's by far more
interesting when I click view
dependencies. So now this one is
relatively simple, but imagine when you
have like a ton of connection and tons
of errors going towards a specific uh
application or uh system or whatever.
here immediately you can see who is
calling and what orders manager in this
case is uh interacting with how many
connection they have and so on so forth.
So I think this one uh is extremely
interesting because uh you can see a
very detailed view of uh the integration
and the connection. Another cool feature
that I really like uh about uh ice panel
is this idea of uh not just designing in
a vacuum uh but also integrate this
design this live design and interactive
design uh with the rest of your system.
So everyone is using at least one tool
uh that uh wants to use in order to uh
share information inside organization.
So as you can see there are multiple uh
integration that we can have uh like I
don't know notion atlashian uh miro
shareepoint etc. But in this case uh
what I want to show you is this
integration. So this panel generates a
link uh and then if I copy this link I
go to notion and go back into my page
where I have a bunch of information
related to uh my system uh and I have uh
let's say all the different
documentation that I've created. I can
paste here. It's an embed. And then at
this stage I have ice panel that is
loading inside uh notion. Here we are.
And obviously I can expand it and I can
navigate through it. So we were at the
at the containers uh level. uh but if
for instance I want to go back in the
orders manager manager like we were
before we can drill down and while I'm
updating this diagram it will update uh
with me so that I think is a great
feature uh that uh helps to keep
everything in sync because I have all
the uh same experience that I have in
ice panel inside uh my documentations
and the diagram is always up to date. So
this is definitely uh a wellthought
process uh that was integrated uh uh by
Icepanner. So kudos to the team. But let
me ask you a question. What's the most
horrendous diagram you ever seen in your
career? If you like me, you are in the
trenches for a while. Probably you have
some horror stories that you would like
to share. And to be honest, I would like
to hear from you what are those? because
I believe that community is also this
idea of sharing not only success but
also failures because we can learn from
that and on the other hand I would like
to know a great story where
communication saved the day and uh
thanks to that you were able to deliver
your project properly and if you find
this approach useful where I take
concrete examples on designing
architecture and the reasoning behind
that leave a comment below because maybe
you're interested in different domain
like I don't know fintech or media
entertainment wherever and I can share
different stories about them because I
had the pleasure to work with quite few
companies in those industries as well.
