Drawing good architecture diagrams

To secure a system, you first have to understand it. Good architecture diagrams are key to this. Unfortunately, the quality of them varies. So, in this blog post I want to give you some tips, and point to a few potential pitfalls, that will help you draw better diagrams.

When done well, an architecture diagram can highlight obvious, as well as more subtle errors in your design. A good diagram enables you to more easily convey your design to others, and it provides a focus for your creative, as well as your technical thinking.

Computer systems can be complicated things to create. They're pieced together by system designers from a bewildering array technological building blocks. Each building block must be configured to work with the other blocks in the system. And there will often be a choice of blocks available for any given role.

To make matters more difficult, system design is not simply a fire and forget process. The properties of the blocks change over time. Maintainers introduce new features and updates. The environment that these blocks are being placed into also evolves. It’s a moving target.

The system designer's goal is to combine these building blocks in the most appropriate way, fulfilling the needs of the system efficiently and securely.

Our first task as systems architects, is to understand the properties of these blocks. This helps us to make informed decisions on how best to piece them together.

Complexity, and the misunderstanding which it causes, can hide security issues. This is what happens if we try to work and think like computers. We end up unable to see and communicate problems which should be obvious.

We need to clearly understand a system in order to explore how it can be attacked and protected. To do this, we must describe our systems in a way which makes sense to human beings. That means using words and pictures.

If we don’t do a good job at this human level, we are making life very difficult for ourselves. This is where architecture diagrams come in.

Though there are many ways to create them, a good architecture diagram should give us a clear overview of a system. At a single glance, we can see which building blocks are being used, how they interlink and how data flows between them.

Diagrams help with a variety of situations. Getting a new joiner up to speed, or creating a common understanding of a system. A diagram can be used as a basis for critiquing a system design, opening up conversation and creative thinking. It can also help us to think about attack surfaces and cyber security risks.

When you look at an architecture diagram, you can quickly conclude its effectiveness. If you find it complicated and confusing, either the system is too complicated, or the diagram needs improvement. It's not you, the viewer, who has failed.

It's difficult to create a diagram with out context. So, the one below describes a hypothetical scenario.

Context: A company runs a system to help answer online support questions. Customers submit questions through an online website. Internal staff then use an internal system to manage and answer them using a ticketing system.

This diagram is not perfect. You will have your own interpretation of what a good diagram may look like, based on your background. Sales staff will wonder what a 'DMZ' is, but network engineers will want to see more detail about how it's implemented.

The key point here is: this diagram is a starting point. It helps us understand the 'gist' of how the system is laid out. It contains quite a lot of information, while still remaining approachable. Further diagrams and documentation can help us drill in, to understand more of the details.

From this diagram, you may deduce the following:

• There are a number of different users of the system. Public users, corporate users and system administrators. There is also some context as to how these users may interact with the system.
• The system is made up of 5 core zones. Public Zone, DMZ, Private Zone, a Remote Access Zone and Management zone.
• We know that there are functions that happen in each zone, but the details are not included. These are areas where supplementary diagrams and documentation would help.

Applying lenses, layers and chunks

It's possible to look at the architecture of a system through a number of different lenses. Your 'go to' lens will depend on your job, project role and area of expertise. Whatever your specialisation, you'll want to see relevant information and this will inform the diagram's creation.

We also need to think about the different layers of a system. Over time, technology gets built on top of other technology. When you describe a system in a picture, you have to choose which layer to draw.

At one end of the spectrum, we can depict a high level, conceptual representation of a system. This would help anyone develop a general understanding of the design, but it's not so good for the people buying components, and then installing them.

At the other end of the spectrum, we could draw out the low level technical details of an implementation. For a network engineer, you can label network interfaces with addressing information. Software developers may want to see detail of classes and data models. This would be great for people building the system, but it adds unnecessary complexity for anyone trying to grasp the bigger picture.

Even with a lens and a focus, some systems remain too big for a single diagram. When this happens, consider chunking your diagrams up into different parts.

Start with a basic high level concept diagram which provides a summary. Then create separate diagrams that use different lenses to zoom into the various parts of your system.

Your system design should be documented, not locked in your head. If an architecture design exists only in your head, you are a blocker to everyone who wants to learn how things work.

Similarly, if the design exists in the heads of a group of people, the picture will be different for each one of them.

Don't let either of these scenarios happen. Instead, write it down in a shared place, so everyone who needs to, can understand your system. These simple guidelines will help you produce good diagrams and use them well.

• Use a single source. If diagrams are dotted around different places, it's hard to know where to go for an authoritative source. Agree on a common style and format. Store and edit from a central repository.
• Maintain your diagrams. Over time, systems change and evolve. Make sure your design diagrams are kept up to date. If they aren't, people will loose confidence and your diagrams will become redundant.
• Simple is best. A bad architect makes a system sound complicated and unapproachable. A good architect makes technical complexity simple and easy to understand. When creating diagrams, try and avoid unnecessary complexity. IP addresses and serial numbers are unnecessary for someone looking for an overview.
• Split your diagrams. There is often a tendency to squash too much information into one diagram. The result is a less effective picture for everyone. Consider creating different views of your system, that users can navigate through. Start with a simple overview, that leads on to different lenses, layers and chunks. People can then pick and choose which to view.
• Create logical grouping. You may find that parts of your system are related, or similar in some way. For example, a set of components interlink to achieve a common objective. This can be used to form a natural grouping of components. This helps the viewer to comprehend and identify parts of your diagram. You could do this using virtual lines and tags. You could use colour to indicate logical associations, but colourblind users may find this problematic.
• Don't increase the language barrier. The language used in the technology profession is bad enough, without inventing more. Try and stick to simple, common and well understood language, as much as possible. Otherwise, you are alienating anyone outside your ecosystem. If you must use specialised terms, accompany them with a plain English description.
• Complement with descriptions. 'A picture is worth a thousand words'. Sometimes though, you may still need to complement diagrams with written descriptions. Consider the effectiveness of these descriptions. Try and keep them as short and concise as possible, while avoiding too many acronyms and jargon terms.

Presenting an architecture in person

In group situations, it's good to draw out an architecture diagram together. Building the picture together, as a story, is often helpful for people. Digital pen technologies make it possible to do this remotely.

Some bad examples might help to clarify the kind of things to avoid.

Diagram 1 - Confusing & Vague

In this diagram, you may get a rough high level idea of what could be happening, but it opens up more questions than it answers.

It's unclear what the different diagram elements are, not to mention how and why they connect to each other. The central block is labelled 'CSMZ', but this is ambiguous project-specific terminology. The phrase 'WAN' could also have different interpretations.

Diagram 2 - Confusing & Complicated

This diagram is very complicated, but also vague.

There are many lines of different colours, which are difficult to follow. Diagram components are connected together, but it is difficult to understand what they do, and why they connect.

The next time you're creating an architecture diagram, think carefully how easy it would be for someone else to understand. Who will be looking at it, and why? Would you need to explain your diagram, or does it make intuitive sense?

Similarly, if you're struggling to comprehend a diagram, you should challenge it. How could you improve it? Doing so will make a big difference to the next person who reads it.

Complexity makes security difficult. Good architecture diagrams will help to clarify your design for everyone involved. This means the systems you build will be harder to compromise.

Toby W
Senior Security Architect, NCSC