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.
Top comments (2)
I would recommend sticking with UML in C4 for the following reason: if you have multiple architect each rolling their own style, that is called confusion. Basic UML is mainly lines and boxes. The conventions allow for more detail as needed, but it is not necessary. I would give C4 a thumbs up. Tiered approach makes sense and stops at a level not too detailed. The concept that I taught at my previous company was to model to the component level for architecture leaving the internal to software development. They pickup from there only modeling when complexity or the need for communication dictates.
In principle I agree, but the real-world tells a different story - the small set of common abstractions provide a way for teams to communicate clearly without agreeing upon a standard visual notation (whether that's UML or something else). YMMV, of course.