Architecture diagrams come in two broad flavours:

• Standardised / formally defined – C4, Archimate, TOGAF, UML….
• Bespoke / less formal – purpose-specific diagrams created in Visio, diagrams.net, Lucidchart, PowerPoint (😱)…

I’ve heard many arguments about which style is better:

“standardised diagrams are too restrictive and take too long”

“bespoke diagrams are just lazy, and unmaintainable”

So let’s have a proper look at the benefits of each style:

Standardised

• Usually presents a single level of abstraction. This can have the effect of forcing the diagram to be more precise and comprehensive. For example, if you want to really capture exactly what the interaction is between system components, a UML sequence diagram is hard to beat.
• Less ambiguity. This is often one of the specific goals of any standard. The standard ensures that necessary information and context is included, and the consistent visual language means you can understand what the diagram is telling you without studying the key.
• Automatable. A well defined diagram standard can be more easily generated by a computer, so it supports diagrams as code solutions such as Structurizr, PlantUML, and Mermaid which enable source control for diagrams – super helpful for seeing how designs evolved over time, checking who made the changes, and tying diagrams to code releases. These types of diagram can also be created from architecture repository tools like Ardoq, BlueDolphin and Abacus, or generated from more “live” systems such as software catalogs like Backstage, or monitoring tools like New Relic.

Bespoke

• Ability to tailor the diagram. Without the constraints of a rigid standard, the author (artist?) can design the diagram to specifically meet its intended purposes or audiences.
• Can tell a story. Less formal diagrams can help to convey a concept more effectively. Too much uniformity means that the important things don’t jump out. For example, maybe I want to use sizes, colours, strokes, images, arrows, or shading to draw attention to the areas which are most important to the reader.
• Can create a more compelling and memorable mental model. Highly standardised diagrams can all start to look alike. They don’t stick in your memory. But a bespoke diagram, perhaps drawn on a whiteboard in a workshop, can become a kind of map for everyone involved; a visualisation of the solution that everyone understands. That’s why if you draw such a whiteboard diagram in a workshop (which I frequently do) and write it up properly later, you should keep the layout the same.
  I know someone who buys books from Persephone, which come in a standard silver and white binding and look very smart on the bookshelf together. But, aside from the fact that I find it soulless to remove all the character and style of different book coverings, it makes it hard to find the one you want. Similarly, with too much uniformity in our work artefacts, it becomes very difficult scrolling through stuff on your laptop or drive to find that useful slide deck, document, or diagram you remember seeing – they all look identical at a glance.
• More control over what information is included, or omitted. Omitting information is key to simplification or abstraction. Standardised diagram models can sometimes constrain you to including too much or too little information. To give just one example of this, if the standard requires the software vendor and technology to be included for every component, the diagram can get very busy and visually overwhelming. And, as the diagram creator, you might not know (or care) what the technology or vendor is for this particular box in this particular diagram, so you may be tempted to work around the constraint by adding in a dummy value, or just guessing!

What I propose

So which should we create? My answer is: Both!

In general, I suggest:

• Standardised, formally defined diagrams are needed as an important reference for people learning, extending, or debugging the system. It’s best if these diagrams are automatically generated. The source of the diagram should be, in increasing order of preference:
  • Config or code in a source control system
  • Your architecture repository
  • Your CMDB or software catalog
  • Your live estate
  • All of the above, operating as a cohesive whole!

• Bespoke diagrams are needed in order to capture or convey a shared understanding, or tell a story. Examples are whiteboarded diagrams in a workshop, diagrams which back up decision making or support learning, or viewpoints which are tailored to specific audiences such as senior stakeholders. But although bespoke diagrams are much freer and informal, I propose some guidelines:
  • Use common agreed conventions. A standard key helps with this: For example, maybe new components are red, changed components are orange, unchanged components are white. We’re always aiming for these diagrams to be easily readable – ideally the message should be clear within a few seconds.
  • Make sure that the diagrams can be modified over time if necessary. Don’t just paste screenshots into documents – always link to the source. (The same goes for standardised diagrams)
  • Please don’t use PowerPoint for architecture diagrams. Seriously.

I’d like to focus on an interesting example of a bespoke diagram. An archetype which I came across a decade ago called city plans.

City plans

If anyone reading this knows of the origin of the software system “city plan” then please get in touch! I first came across it working with some of the amazing people at Sky Betting & Gaming.

A city plan is a diagram which maps out the entire landscape of the software systems we own. It helps people orientate themselves. It shows the overarching architecture design, or, if there isn’t one, it allows one to be designed. It gives people a sense of the overall scope of what we do. But… and this is the part which means that it falls into the “bespoke” category of diagram – it spans different levels of abstraction, and it can’t easily be automated because it needs to be carefully curated for maximum readability by omitting things, styling or annotating elements in various ways, and positioning things in a carefully chosen layout in much the same way as a real-life city plan lays out neighbourhoods and streets.

Examples of city plans

I created the following diagrams to try to convey the difference between standardised diagrams (in this case, created using the C4 model), and a bespoke city plan created in a less formal style in order to be more visually compelling and easily readable.

To be clear, I believe that both are necessary as they fulfil difference purposes.

I’ve created C4 diagrams at levels 1, 2 and 3, and then an example of a city plan which includes some aspects of all of those levels.

C4 diagrams

The following C4 diagrams show some of the systems, containers, and components for a typical eCommerce company’s software systems.

Level 1: Systems

Level 2: Containers

Level 3: Components

City plan

The following city plan is intended to provide a single view of the entire landscape which helps people orientate themselves and understand the full scope and “architectural layout”.

Key things to notice:

• The city plan contains a lot, but isn’t visually overwhelming.
• The city plan includes essentially the full breadth of the architecture.
• The city plan goes into slightly more detail (i.e. lower abstraction) only where necessary for the reader to gain an understanding of what’s going on.
• A number of visual techniques are used to include additional information, but again these are only used where it’s of particular importance, for example:
  • The Personalisation Service has a small database symbol. That tells the reader that it uses a private database, and that the database is important enough that it’s been specifically called out.
  • Different arrow colours show whether traffic is standard HTTPS, web sockets, or Kafka.
  • Details of all the Kafka topics are not shown, but two have been specifically included, which tells the reader that they’re important.
  • Pink PCI labels are used to flag up systems that handle card data.
  • The colour coding for new and existing components tells the story that the React Native UI is being retired in favour of a Swift iOS app.
  • The diagram is carefully laid out according to domains, with the customer at the top, and foundational or platform systems at the bottom.

These visual techniques are just examples – you can decide what’s important to get across to the reader, and the best way of showing it. But the key point is that the city plan is an example of a bespoke, relatively informal, diagram the main purpose of which is to get across the main things someone might want to know about the overall architecture.

Using a city plan to convey overall architectural design structure

One final thought on city plans: Sometimes it’s helpful to convey something about the high level structure of our architecture. Sometimes people are completely unaware of the big picture design, and might build things which contravene its principles without even knowing.

I once created the following city plan for a company not just to show the overall system landscape, but to visually explain something important about the layered architecture that we wanted to adopt, namely:

• The red and blue layers contained the Experience Domains – systems specific to a customer experience. Components in the red layer ran on customer devices (typically React.js components). Systems in the blue layer ran server-side and were tightly coupled to their red-layer counterpart – a BFF pattern.
• The next layer contained the Business Domains; shared services and data which the Experience Domains used to support their particular customer use cases.
• The outer, grey, layer was for externally provided systems.

This design was important because it governed interdependencies.

Note 1: This city plan was printed out on an enormous printer and put on the wall in the office kitchen/breakout area. People would study it and have conversations about it. Sometimes they’d annotate it with questions or corrections. It created engagement with architecture.

Note 2: Although the dynamic circular look of this diagram was nice, and it made it clear that the customer was central to everything we did, it did also prove to be a pain to update. My apologies to the people who continued to maintain it – I promise I’ll stick to rectangles from now on. 😅

Summary

• We need both formal/standardised diagrams (preferably aut0-generated from source) and less formal bespoke diagrams that tell stories and convey messages.
• City plans are a great technique for helping people to understand and form a mental model of the overall architecture.