Recently, while looking for a better way of doing things (I'm always looking) I came across a video on StoryQ called The Frustrated Architect. This video did a perfect job of explaining where I was at in my career and led me to Simon Brown's blog and book. I recommend the book, the blog and the video but today I'm going to talk about the C4 model that Simon proposes.

Getting Started with C4

If I give you (or anyone on your team) a blank whiteboard and ask you to draw the architecture of your solution, how well do you think you'd do? Would the rest of your team draw the same thing you'd draw? If you get together as a group and discuss things will that result in a clearer vision of the architecture or just lead to a lot of discussion?

There are a number of issues with the blank canvas you face when it comes time to communicate your design. It's hard to know where to start. It's hard to know what belongs on the diagram and what doesn't. Solution Architecture is often targeted at a number of different stakeholder groups, all of whom will be interested in different information.

The C4 model goes a long way to solving the blank canvas problem by introducing a common set of abstractions used to model with and a collection of diagrams to explore that model. It's a toolbox that allows a person (or team) various well-defined layers of abstraction to develop and communicate the static structure of a solution.

So what's in the toolbox? Firstly the abstractions:

  • A software system is made up of one or more containers,
  • each of which contains one or more components,
  • which in turn are implemented by one or more classes.

We can expose the relationships between these things with a set of diagrams composed at 4 different levels of abstraction:

  • Context: Shows keys systems, the dependencies between them and the actors that access them.
  • Container: Shows the high-level technology choices, how systems are decomposed in to containers and how those containers communicate.
  • Component: Shows the internal structure of a container and how it is decomposed into collaborating components.
  • Class: a typical UML class diagram showing the internal structure of a component. This is usually only needed for complex components.

Note that each of these diagram types is named with a C and there are 4 of them, hence the name C4. Typically you won't have 4 diagrams. You will likely have one high-level Context diagram, a couple of Container diagrams (might just be one depending on the complexity of the system being drawn), several component diagrams (one for each container) and (maybe) one or two class diagrams. There is no hard and fast rule to this.

One of the advantages to this approach is that it provides a natural narrative for exploring a solution architecture. You start at the highest level (what is the system and how does it provide value to the business) and drill into the details. Once a reader has used these details to build up a simple mental model they have the context required to hang other (useful but often tangential) information off of. It also prompts questions at the right level. i.e. If the Customer system goes down, how will our our system behave? How many public users will we have and what will they do if the system is unavailable? What communication mechanism is used between the Application Server and the CRM system? And so on.

I've now worked on a number of projects where the very first thing I do is draw up a Context diagram and start taking it to meetings and show it to everyone. It's is ALWAYS wrong and this is a good thing. It's a good thing because people will inevitably point out where it's wrong. I come back from every meeting in the first week or two with a diagram covered in annotations. I update the diagram and bring the next version with me to the next meeting. After a few iterations of this, the annotations start to grow fewer and fewer as everyone starts to settle on the vision of the solution architecture.

There are a few things worth noting about this approach. Firstly, there ends up being many different versions of the diagram. As such, you should put a prominent version number or change log on the diagram somewhere. Although you should take the diagram everywhere and show it to everyone, resist the urge to give it to other people until it settles down.

Secondly, try to not rearrange everything. That is, if your system context diagram has the CRM system in the top left, don't arbitrarily move it to the bottom right from one version of the diagram to the next. It might seem obvious but it's a mistake I've made in the past so I wanted to mention it. The System Context diagram (indeed any diagram) is a communication tool. When you show it to someone they build up a mental model of where everything is in their heads. When you show them the next version, you want to evolve that mental model into the new form. If everything is in a different place you will shatter the mental model and force the reader to recreate it. This takes the focus away from the changes (the thing you're really interested in) and frustrates the reader.

OK so how do you get started. Find a whiteboard right now and follow these steps:

  1. Write the name of your system in the middle. Under that write a sentence or two about what it does. Draw a box around it.
  2. Across the top of the whiteboard write a list of the user groups that interact with your system. Under each group write a list of what that group uses your system for. Draw a box around each user group and then draw a line from each box to your system. If you don't know the user groups start with Internal, External and Admin. Do try to get the list of what the user does with your system though. This can be garnered at a high level from functional requirements.
  3. Across the bottom of your whiteboard write a list of the other systems that your system depends on. Below each one write a sentence or two about its responsibilities are. Draw a box around each one and connect them to your system. Make sure these lines have arrows. I like to have the arrow pointing towards the system which is being used and away from the system responsible for the connection. I tend to find that annotating these lines with "why" is a good idea too.
  4. Add to the list of other systems, those which depend on your system to do their job. Don't forget the arrows and the annotations.
  5. Take a photo, that's your first Context diagram. Show it to people. Maybe start it in collaboration with the rest of your team.

Hopefully that gives you enough to get started. If you don't have a whiteboard lying around that you can leave the diagram on then you'll need to redraw it every time (not necessarily a bad thing). Alternatively you can draw it in Visio. Just remember that it doesn't need to be perfect straight away. It's going to change (a lot) so don't invest too much time in it up front.

Next time I'll talk about avoiding Visio.

Posted by: Mike Minutillo
Last revised: 29 Jan, 2015 03:38 AM History


No comments yet. Be the first!

No new comments are allowed on this post.