Traditional views of software architecture often conjure up images of huge UML (Unified Modeling Language) models that attempt to capture every last drop of detail. Unfortunately, modelling and UML became coupled to the "big design up front" practices of the pre-agile era, and all of this has been thrown away by teams in recent years. In my travels around the world, the percentage of software development teams I meet where nobody on the team even knows UML is increasing.

The common advice from many people these days is to "just use boxes and lines on a whiteboard" as a way to communicate ideas. I have gigabytes of photos of such diagrams from my software architecture katas over the years, and I can say with some degree of confidence that, as an industry, we've lost the ability to communicate software architecture. I've seen every possible diagram you can imagine; from collections of illegible randomly coloured boxes and lines through to diagrams that literally tell you nothing about the solution. Teams that can't communicate software architecture won't be able to create that starting point and direction.

The C4 model for visualising software architecture

My solution is an abstraction-first approach to communicating software architecture that I call the C4 model - Context, Containers, Components, and Code. It's essentially about creating a set of hierarchical, zoomable maps to describe a software system, based upon abstractions that reflect how software architects and developers think about and build software. The small set of abstractions and diagram types makes the C4 model easy to learn and use.

For any given software system, you create a System Context diagram that describes how the system fits into the world around it. You then zoom in to the system boundary to show the containers inside it - not Docker; a container is a deployable, runnable thing, like a single-page application running in a web browser, a server-side web application, a microservice, a database schema, etc. These top two levels are often sufficient for many teams. If useful though, you can then zoom further into a container to show the components inside it. Finally, and again optionally, you can zoom into each component to show the code level elements (classes, interfaces, functions, objects, etc) it's composed of. The C4 model is notation independent, and although I tend to use a simple "boxes and lines" notation, you can certainly use UML or ArchiMate.

Although primarily aimed at software architects and developers, the C4 model provides a way for software development teams to efficiently and effectively communicate their software architecture, at different levels of detail, telling different stories to different types of audience, when doing up front design or retrospectively documenting an existing codebase.

You can find more information, example diagrams, a diagram review checklist, and links to tooling options at the C4 model website. I'd recommend taking a look if your team struggles to communicate software architecture, and the diagrams on your whiteboards/wiki pages don't make much sense.

Summary

Good software architecture diagrams assist with communication (both inside and outside of the software development/product team), onboarding of new staff, risk identification, threat modelling, etc. Good software architecture diagrams help to align everybody's understanding of the software being built, helping to make the team more efficient.