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