Most teams have no standard for architecture diagrams. Someone opens a drawing tool, produces boxes and arrows, and the result is understood by the person who drew it and nobody else. The problem is rarely artistic skill. It is that three separate decisions — what level of abstraction, which notation, which tool — get made implicitly and inconsistently, and that a diagram mixing all of them is unreadable.

This guide separates those decisions, then applies them to the case that exposes weak diagrams fastest: a hybrid architecture where some workloads run in a cloud and some stay in your own data centre.

Decision 1: pick a level of abstraction

The single most common defect is one diagram trying to show everything: business context, deployment topology, and class names in one picture. Fix that first, and the rest becomes easy.

The C4 model, created by Simon Brown, exists for exactly this. It is deliberately “notation independent” and “tooling independent,” and organises diagrams into four hierarchical levels you can zoom through [1]:

LevelShowsAudience
1 — System ContextYour system as one box, its users, and the systems it talks toAnyone, including non-technical stakeholders
2 — ContainerSeparately deployable units: apps, APIs, databases, queuesArchitects, developers, operations
3 — ComponentThe major building blocks inside one containerDevelopers of that container
4 — CodeClasses and their relationshipsRarely worth drawing by hand

C4 also defines three supplementary diagram types that matter more in practice than Level 4: system landscape (several systems and how they relate), dynamic (a specific sequence of interactions), and deployment (how containers map onto infrastructure) [1].

For most purposes, Level 1 and Level 2 are the whole job. Level 4 is generated by an IDE if you ever need it. If you draw only two diagrams for a system, draw a context diagram and a container diagram.

“Container” here predates and does not mean Docker. It means a separately runnable, separately deployable thing — a web app, a Lambda function, a database, a message broker. A container may or may not be containerised.

Decision 2: pick a notation

Notation is not the same as level. Three options are worth knowing, and they are not interchangeable.

C4 as informal notation. Boxes with a name, a technology, and a one-line description; labelled arrows describing the interaction and its protocol; a legend. Deliberately not a formal language. Fast, and understood without training. This is the right default for most teams.

UML is a formal specification maintained by the OMG. For architecture work, only two of its thirteen diagram types are usually relevant: the deployment diagram and the sequence diagram . UML’s precision is valuable where a diagram is a contract — regulated environments, safety cases, formal design reviews. See UML overview .

ArchiMate , from The Open Group, models the enterprise: business processes, applications, and technology as connected layers [2]. It answers “which business capability does this system support,” which C4 and UML cannot. It is heavier, needs training, and is the right choice mainly if your organisation already does enterprise architecture.

Whichever you choose, three rules do more for legibility than notation ever will:

  1. Every diagram gets a title, and states its level.
  2. Every diagram gets a legend — do not rely on colour meaning something the reader has to guess.
  3. Every arrow is labelled with what flows and how (HTTPS/JSON, JDBC, S3 event). An unlabelled arrow carries no information beyond “these touch.”

Decision 3: pick a tool

Tools fall into two families, and the difference matters more than any feature comparison.

Drawing tools

  • draw.io / diagrams.net — free, runs in a browser or desktop, stores diagrams as XML that can live in git, and ships the official cloud icon sets. The pragmatic default.
  • Excalidraw — deliberately sketchy. Excellent for whiteboarding and for diagrams you want to signal are provisional.
  • Visio, Lucidchart, Miro — common in enterprises, usually because they are already licensed.

Diagrams-as-code

The diagram is a text file, rendered by a tool, reviewed in a pull request, and versioned with the system it describes.

  • Mermaid — renders from fenced code blocks directly in GitHub, GitLab, and many documentation systems. Lowest friction of any option: no tool to install, no image to regenerate.
  • Structurizr DSL — from the author of C4. You describe the model once — systems, containers, components, relationships — and generate every C4 view from it. This is the only approach that structurally prevents your context and container diagrams from disagreeing with each other.
  • PlantUML — broad UML coverage from text, with a C4 extension.
  • Diagrams (mingrammer) — Python that emits cloud architecture diagrams using official provider icons. Good when the diagram should be generated from real infrastructure data.

Use official vendor icons. All three major providers publish authoritative icon sets, and using them makes a diagram immediately legible to anyone who knows that platform: AWS Architecture Icons [3], Azure architecture icons [4], and Google Cloud icons [5]. Hand-drawn approximations of a service logo are worse than a plain labelled box.

The honest recommendation: draw.io for anything you will draw once, diagrams-as-code for anything that must stay true. A diagram that is not versioned next to the code will be wrong within two release cycles, and a confidently wrong diagram is more expensive than none.

Drawing a hybrid architecture

A hybrid diagram has one job an all-cloud diagram does not: it must make boundaries explicit. Nobody adopts a hybrid architecture for elegance — it is adopted because a constraint forbids the simpler thing. If the diagram does not show the constraint, it does not explain the design.

Four things to make visible:

1. The trust boundary. Draw an explicit boundary around each environment — your data centre, each cloud region — and label it with who operates it. Vendor conventions already support this: AWS reference architectures enclose resources in a labelled region boundary, and inside it VPC and subnet boundaries. Reuse that convention rather than inventing one.

2. Where data rests versus where it transits. This is the distinction a hybrid design usually exists to satisfy. A regulator or contract rarely says “no cloud”; it says where data may be stored, and sometimes separately where it may be processed. A diagram that shows a database icon on-premises but does not show that a copy transits a cloud service during processing is hiding the compliance question. Annotate data flows with classification — public, internal, personal, regulated.

3. The link between environments, and its properties. Site-to-site VPN, a dedicated interconnect, or a public API endpoint are different in latency, bandwidth, and cost. Label it. If the design depends on a private circuit that does not exist yet, that belongs on the diagram.

4. The direction of initiation. “On-prem calls cloud” and “cloud calls on-prem” have completely different firewall and security consequences. An undirected line hides this. Many hybrid designs work precisely because all connections are outbound from the private environment.

A useful habit is to draw the constraint first: put the thing that cannot move — the regulated dataset, the mainframe, the licensed appliance — in the middle of the page, then build outwards. The resulting picture tends to explain itself, and it makes the reasoning in on-premise vs cloud AI visible rather than implied.

Common failure modes

  • No level. Load balancers and business capabilities in one picture.
  • Unlabelled arrows. The reader cannot tell a synchronous HTTP call from a nightly batch copy.
  • Logo soup. Thirty service icons, no boundaries, no flow. Impressive, unreadable.
  • Colour as hidden meaning. Colour is a legend entry or it is decoration.
  • Drift. The diagram describes the system as designed two years ago. Versioning it with the code is the only durable fix.
  • One diagram for every audience. A board-level context diagram and an operational deployment diagram are different artefacts. Draw both; do not average them.

Further reading

Sources

  1. Brown, S. “The C4 model for visualising software architecture.” https://c4model.com/
  2. The Open Group. “ArchiMate Overview.” https://www.opengroup.org/archimate-forum/archimate-overview
  3. Amazon Web Services. “AWS Architecture Icons.” https://aws.amazon.com/architecture/icons/
  4. Microsoft. “Azure architecture icons.” https://learn.microsoft.com/en-us/azure/architecture/icons/
  5. Google Cloud. “Google Cloud icons and sample diagrams.” https://cloud.google.com/icons
  6. Structurizr. “Structurizr DSL documentation.” https://docs.structurizr.com/dsl
  7. Mermaid. “Mermaid documentation.” https://mermaid.js.org/
  8. PlantUML. https://plantuml.com/
  9. Diagrams (mingrammer). “Diagram as Code.” https://diagrams.mingrammer.com/
  10. draw.io. https://www.drawio.com/