Drawing good architecture diagrams

Summary

Good architecture diagrams make complex systems understandable to humans, reveal security issues and enable productive discussion. The NCSC blog sets out practical guidance: choose the right level of detail (lens/layer), split large systems into manageable chunks, keep diagrams simple and maintained in a single shared source, use logical groupings and plain language, and complement diagrams with short descriptions. Examples of poor diagrams illustrate common pitfalls such as ambiguity, excessive detail and confusing visual styles.

Key Points

Diagrams should show the big picture at a glance: components, zones and data flows.
Pick the appropriate lens and layer for your audience — conceptual for newcomers, detailed for implementers.
Chunk large systems into an overview plus focused views to avoid overload.
Keep diagrams in a single, shared repository and maintain them as the system evolves.
Simplicity wins: avoid unnecessary detail (e.g. IPs, serial numbers) on overview diagrams.
Use logical grouping (zones, functions) to help comprehension; be cautious with colour for accessibility.
Stick to plain English; if specialised terms are needed, add concise explanations.
Complement images with short, clear descriptions to reduce ambiguity and support critique.
Build diagrams collaboratively where possible — it surfaces assumptions and creates shared understanding.

Content summary

The post explains why architecture diagrams matter for security and system understanding. It describes the challenge of complexity and why human-centred diagrams (words and pictures) are necessary to spot weaknesses and communicate design. An example diagram of a support-ticket system demonstrates an effective high-level view and how it can seed deeper diagrams. The article explains lenses (different stakeholder views), layers (conceptual vs technical) and chunking strategies for large systems. Practical tips cover storage, maintenance, simplicity, splitting views, grouping, plain language and adding brief textual descriptions. Two poor example diagrams highlight common mistakes: ambiguity and visual clutter.

Context and relevance

Organisations building or securing systems should treat diagrams as living documentation. As systems evolve, stale diagrams become misleading and dangerous. This guidance aligns with ongoing trends emphasising secure-by-design thinking, cross-team communication and documentation-as-code practices. Clear diagrams reduce onboarding time, aid threat-modelling and make it easier to spot and fix security issues early.

Why should I read this?

Quick and useful — this is the kind of practical checklist you can apply today. If you sketch system diagrams, these tips will stop you creating anything that needs a cryptographer to decode. Save yourself time, reduce mistakes and make your systems harder to attack.

Author style

Punchy: clear, actionable advice from an experienced security architect. If you care about building or defending systems, these guidelines are worth following — they cut through noise and make diagrams actually work for people.