Architecture Diagrams

Similarly to writing code, we want to do just enough design up front to validate our approach, but not so much there is no room for the design to evolve over time. If your role includes designing architectural solutions, you should aim to document the architecture enough so that it's a solid guide for teams implementing the design, but still leaves plenty of room for them to be creative and sculpt the final product.

Before we talk more about software architecture diagrams, it's important to understand how these diagrams should be used. They shouldn't be created in isolation and handed down to engineers to interpret and implement. If you're responsible for designing a software system, ensure you embed yourself closely with the team building that software system. Seek regular feedback from that team, as well as peers such as other architects, and ideally collaborately evolve the design with your colleagues.

My favourite way to model architecture is with the C4 model.

One of the best use cases for the C4 model is in your projects' README. Whenever someone wants to know about your project, they probably go to the README first. In each of the projects that my team owns, you will find a C4 model. Recently, the company went through a restructure, and some projects got reassigned to different teams. This required handover to another team, and the C4 model was the perfect piece of documentation to easily explain to another team how the system worked. The same can be said for new joiners, they can quickly and easily see exactly how a service operates by looking at the C4 model in the README.

The C4 model is also useful when creating ADRs, similarly to the prior chapter. When creating an ADR, you're essentially proposing the design of the system, so you can use the C4 model to quickly iterate through ideas for your architecture.

What Is The C4 Model?

The C4 model consists of four diagrams, with each part containing a different view of our architecture, and gradually increasing in detail as we move through the four parts.

The C4 model was created by Simon Brown as a consistent mechanism for teams to model their software architecture, and he described it as so:

"The C4 model was inspired by the Unified Modeling Language and the 4+1 model for software architecture. In summary, you can think of the C4 model as a simplified version of the underlying concepts, designed to (1) make it easier for software developers to describe and understand how a software system works and (2) to minimise the gap between the software architecture model/description and the source code."

As mentioned, there are four parts to a C4 diagram:

• System context diagram
• Container diagram
• Component diagram
• Code diagram

As you move through each part, we zoom in a little further in terms of detail, and the details provided get more and more technical. If the system context diagram is the 50,000 ft view, the code diagram is the microscopic view.

Lastly, there is no defined notation for creating C4 diagrams. There's no guide that says to use solid lines for X and dashed lines for Y, or use black to denote A and blue to denote B. The C4 model just lays out the framework for the details captured at each level. If you want to tweak it as you build your own diagrams go ahead, just remember to keep your notation consistent across the different parts.

What Does A C4 Diagram Look Like?

As mentioned, there are four C4 diagrams. I'm going to show you the system context diagram, as it's usually the most used one in my experience. Here's what it looks like:

          flowchart TD
            User["Premium Member
            [Person]
          
            A user of the website who has
            purchased a subscription"]

            LS["Listings Service
            [Software System]
          
            Serves web pages displaying title
            listings to the end user"]
          

            TS["Title Service
            [Software System]
          
            Provides an API to retrieve
            title information"]
          
            RS["Review Service
            [Software System]
          
            Provides an API to retrieve
            and submit reviews"]
          
            SS["Search Service
            [Software System]
          
            Provides an API to search
            for titles"]

            User-- "Views titles, searches titles\nand reviews titles using" -->LS

            LS-- "Retrieves title information from" -->TS
            LS-- "Retrieves from and submits reviews to" -->RS
            LS-- "Searches for titles using" -->SS

            classDef focusSystem fill:#1168bd,stroke:#0b4884,color:#ffffff
            classDef supportingSystem fill:#666,stroke:#0b4884,color:#ffffff
            classDef person fill:#08427b,stroke:#052e56,color:#ffffff

            class User person
            class LS focusSystem
            class TS,RS,SS supportingSystem
        

This diagram was created using diagrams as code.

This is an example for a fictional streaming company's architecture, focussing on the listing service and what interactions it has. It shows who uses the system, and what dependencies it has.

Learn To Create C4 Diagrams

This is just one of the four C4 diagrams.

The diagram above was created using a tool called MermaidJS. It allows you to easily create a variety of diagrams in Markdown-like markup, and quickly convert into a rendered diagram wherever you need it.

Mermaid allows us to quickly iterate over any diagram simply by changing some simple definitions. In days of old, before I started using Mermaid, a part of me would be disheartened when I had to change a diagram I'd made using a UI-based tool. Not because I wasn't open to change, but because changing that diagram was painstakingly painful. Having to move all the boxes, redraw lines etc. could take several hours if the change was significant.

Want to learn more? I cover how to create C4 diagrams, along with a number of other use cases and diagrams, in my book: Creating Software Using Modern Diagramming Techniques, published via The Pragmatic Programmers.