The C4 model for visualising software architecture

Simon Brown, 'The C4 model for visualising software architecture'. (yes, the title has a typo).

I've found this book almost accidentally. Admittedly I was partially familiar with C4 model before reading this book thanks to some online resources and helpful conversations that happened at work. I wasn't sure what to expect from it and was a little bit afraid it will not add much.

My fears were mostly unfounded. While there's literally nothing revolutionary in the book, at least if you're somewhat familiar with the subject and not looking for alternative to diagram heavy paradigm you're stuck in at work, it actually helps to streamline your approach to working with C4 diagrams and there's a number of examples illustrating what can go wrong and what designer should be aiming for. It's also relatively short read.

Overall verdict: worth checking.

 

 

 

---

Personal notes:

• Chapter 3. We have a failure to communicate - author assesses issues that arose around communication of software systems; competing standards, failing practices, all the known problems around UML etc. Author draws from his experience and illustrates a number of issues in how freestyle (lines and boxes) diagrams look. What is common point with other sources is that inexperienced 'engineers' tend to focus on boxes, while the more interesting part is lines connecting them. But there are others: too generic pictures, too atechnical perspectives, different perspectives (like functional and infrastructural etc) on one diagram, inconsistent color coding and level of details, random elements that creep into overall not bad designs, too much stuff  etc., Simon concludes that these issues are exacerbated when instead of one diagram, you get a set. Canary test for diagrams is to give it to read to someone unfamiliar with context. Probably wise. It is interesting to review this chapter carefully - while I avoided some of the errors, I was not so safe from some others and the learnings I should take into account.
  
• Chapter 4. A shared vocabulary - Simon starts with setting up some basic vocabulary that should be well understood throughout the team and is used in his C4 model. In essence: system, container, component, code - examples, distinctions etc. He also stresses that the goal here is mapping static structure. Important assumption to make early on. There's also short yet interesting section on modules and subsystems clarifying why they are not part of vocabulary.
  
• Chapter 5. The C4 model - This is building on previous chapter - having set the vocabulary, Simon goes briefly through  the concept of C4 model and it four diagrams (system, container, component, code) and their relationship. 
• Chapter 6. Level 1: System Context diagram - some details, although this is quite simple.
• Chapter 7. Level 2: Container diagram -  the thing worth stressing is that this already is 'technology focused'. Meaning each container should have technology marked. Actors should be named and briefly described. Protocols should be stated. Potentially ports as well (IMHO if non-standard).
• Chapter 8. Level 3: Component diagram - now the part that really is interesting. Important of course is that you're not intended to make this diagram for all containers - maybe none, maybe for interesting containers. Components can link to other components, something I might not have been very consistent about. Now another interesting thing to take into account is that we don't have to include ALL components - some can bring little to the story yet clutter the diagram a lot. Another thing is that shared component deployed independently should be on the diagram multiple times, as applicable. Of note is also that library is not a component but rather a way to deliver component. Finally, it's probably good idea to draw boundaries of container on the component diagram (users are probably outside of it as are other containers).
• Chapter 9. Level 4: Code-level diagram - less interesting chapter. It can basically be UML class diagram. However point is that you're supposed to tell a story, not blindingly map code structure to diagram - as such auto generating it from code base might lead to diagram not being very useful. I guess some manual fine-tuning a diagram out of auto-generated one can be an option.
• Chapter 10. Notation - some key ideas: title, legend, balance between shapes and simplicity, annotations, color (but colorblindness), borders, consistent size or meaningful size, consistent directions of lines and their style. Thing that stands out as simple yet important is the recommendation for connection naming - to incorporate names of beginning/end into line description and use preposition at the end. Should be useful and I'm pretty sure I've seen it before. 
• Chapter 11. Diagrams must reflect reality - there are some somewhat interesting points on model-code gap - and I think this is one of these terms worth keeping at the back of the head. Apparently it comes from the 'Just Enough Software Architecture' book (which might be in shipping or not - at this point I lost track). Architecturally-evident coding style is also borrowed from that book and this idea is worth checking against the codebase I work with. Again - diagram should not only reflect design choices but also choices of tech! I also like that Simon resolves diagram ambiguity by thinking with "how would you code it?" question. Simple yet powerful.
• Chapter 12. Deployment diagrams - This is extension of C4 model beyond - well C4 diagrams. Deployment is important extension of the toolset. The basic idea is that you can take container diagram and provide additional information through outer boundaries marking additional informatiom. Fair enough. You can also have deployment diagrams for different environments - like local dev environment all production. You can also add a host of additional information that you intentionally omit on container diagram - like DNS, firewall or additional k9s config. If you want to use proprietary cloud related icons, remember they are subservient to your system.
• Chapter 13. Other diagrams - there are some comparisons between C4 and other models - nothing particularly noteworthy IMO. But the general sentiment that the more exhaustive given diagramming approach is, the more confusing - on average - it is to developers, which in turn defeats the purpose. I can believe that. There's also second extension of C4 model briefly noted - System Landscape diagram. Basically multi-system System diagram. Simon also mentions in different contexts some other diagrams that he uses - which make them good supplement to C4 model (I think) - so UML Activity diagram, flowchart, DDD Domain model, UML collaboration (or UML sequence).