skip to content

Why are typical "boxes and lines" architecture diagrams ambiguous, and what concrete rules make a diagram self-explanatory to someone who was not in the room when it was drawn?

level: middleimportance: must knowfreq 58%

answer

  1. Box type + line meaning are undefined
  2. Arrow = call or data? pick one, state it
  3. Key/legend on every diagram
  4. One abstraction level per diagram
  5. Title + date + status; label intent + protocol

basics

~20 s

Because nothing says what a box or a line means: a box could be a service, a class, or a team; a line could be an HTTP call, a dependency, or data ownership. Fix it with titles, typed/labelled boxes, directed labelled arrows, a key, and one abstraction level.

solid answer

~50 s

An unlabelled box-and-line drawing carries meaning only in the head of the person who drew it. The reader cannot tell the *type* of an element (process? library? database? team?), the *meaning* of a line (synchronous call, async event, data flow, build-time dependency), the *direction* of the interaction versus the direction of data, or which *level of abstraction* is in play — and mixed levels are the most common defect. Practical rules: give the diagram a title stating what it shows and its abstraction level, plus a date/version; give every element a name, a type, and a one-line responsibility, and add its technology where it matters; make every line an explicit arrow labelled with intent and protocol ("Sends order-placed events via [AMQP]"); avoid bidirectional arrows; include a key/legend explaining every shape, colour, line style, and acronym; keep one level per diagram; and prefer several small readable diagrams over one wall-sized one.

code

text · 9 lines
text
BAD:   [Orders] ------- [Payments]

GOOD:  [Orders API]                       [Payments API]
       [Container: Java service]  --->    [Container: Go service]
       label: "Requests card authorisation from [JSON/HTTPS, sync]"

       [Orders API]  - - ->  [Broker: Kafka]
       label: "Publishes order-placed events to [Avro/Kafka, async]"
       (key: solid = synchronous call, dashed = asynchronous message)

go deeper

for a junior

Name the two big ambiguities (what a box is, what a line means) and the fixes: label everything, add arrows with direction, add a key.

for a middle

Give the full checklist — title, level, date, typed elements with responsibilities, intent+protocol on arrows, sync vs async, legend — and name mixed abstraction levels as the top defect.

for a senior

Weigh cost vs value, distinguish disposable sketches from maintained documentation, and cover accessibility, drift, and the 'hand it to a stranger' validation test.

for a principal

Set a house notation and a minimum bar (which diagrams are maintained, where they live, who reviews them), and treat diagram drift as a documentation-quality metric rather than a personal style preference.

## What "ambiguous" actually means here A diagram is a communication artefact. It is ambiguous when two competent readers can derive two different, incompatible mental models from it. Typical ad-hoc drawings are ambiguous on at least five axes: 1. **Element type.** A rectangle labelled `Payments` might be a deployed service, a code module, a database schema, a third-party SaaS, or the team that owns it. Different readers pick different answers and then argue about a decision that was never made. 2. **Line semantics.** A line between two boxes could mean: makes a synchronous HTTP request; publishes an event that the other consumes; shares a database; depends on at compile time; is deployed together with; or simply "is related to". Each has completely different operational and coupling consequences. 3. **Direction.** Is the arrow the direction of the *call* or the direction of the *data*? For a read, those are opposite. A double-headed arrow usually means the author didn't decide. 4. **Abstraction level.** The single most common defect: one diagram contains a user, three microservices, an nginx instance, a Kafka topic, a database table, and a utility class. There is no consistent zoom level, so nothing on it can be trusted as complete. 5. **Scope and time.** Is this the current system, the target state, or an option under discussion? Undated diagrams silently become fiction. Secondary ambiguities: unexplained colours ("why is that one orange?"), unexplained shapes (cylinder = database? queue?), unexpanded acronyms, dotted vs solid lines with no key, and implied but undrawn elements ("obviously everything goes through the gateway"). ## The checklist that removes ambiguity **Diagram-level** - **Title**: what it shows *and* its abstraction level, e.g. "Container diagram — Order Management System". - **Date / version / status** (current | proposed) and an owner. - **A key/legend** on *every* diagram, explaining each shape, colour, border style, and line style actually used. If you cannot write the key, the diagram has no notation. - **One level of abstraction.** If you need another level, draw another diagram. - **Readable size.** Two focused diagrams beat one that needs zooming. **Element-level** - **Name** (what it is called in real life and in the repo/runtime). - **Type**, stated on the box ("[Container: Spring Boot service]", "[Person]", "[External system]"). - **One-line responsibility** so a stranger knows why it exists. - **Technology** where it changes the conversation (language/runtime/store/protocol). **Relationship-level** - **Explicit direction** — a single-headed arrow, and state whether it means "calls" or "sends data to"; keep that convention consistent and put it in the key. - **Intent label** — "Reads customer profiles from", "Publishes order-placed events to". - **Technology/protocol** — `[JSON/HTTPS]`, `[gRPC]`, `[AMQP]`, `[JDBC]`. - **Synchronicity** — distinguish sync request/response from async messaging (commonly dashed for async), declared in the key. - **Avoid bidirectional arrows**: draw two arrows if both directions genuinely exist and matter. ## Trade-offs and edge cases - **Cost vs. value.** Fully labelling everything is slower and can crowd the page. Mitigation: cut breadth (fewer elements per diagram) rather than cutting labels; move detail into supporting text. - **Whiteboard sketches** are fine ambiguous — they are conversation, not documentation. The rules apply to diagrams that outlive the conversation (repo, wiki, ADR, review pack). - **Notation snobbery.** Insisting on strict UML often kills adoption; a consistent house notation with a key beats a formally perfect diagram nobody draws. C4 explicitly takes this position. - **Colour** must never be the *only* carrier of meaning (accessibility, black-and-white printing, screenshots). - **Drift** is the deepest ambiguity: a beautifully labelled diagram that is 18 months stale misleads more effectively than a vague one. Version it with the code and review it in pull requests. ## A useful test Hand the diagram to an engineer from another team, say nothing, and ask them to explain it back. Every question they ask is a missing label. Simon Brown's phrasing of the goal: the diagram should stand alone without the author narrating it.

  • Is a bidirectional arrow ever acceptable?
    Only when the key defines it precisely (e.g. "request/response over one connection") and both directions carry the same meaning. Otherwise draw two arrows, because the two directions usually differ in protocol, initiator, and failure mode — and the initiator is exactly what determines coupling.
  • How do you stop labelled diagrams from going stale?
    Store them as text next to the code (Structurizr DSL, PlantUML, Mermaid), render in CI, review changes in the same pull request as the code, and delete diagrams nobody maintains rather than leaving misleading ones. Where possible, generate low-level views from the code instead of hand-drawing them.
  • Your team pushes back that full labelling is too slow. What do you do?
    Keep the non-negotiables — title, level, key, directed and labelled arrows — and reduce scope instead: fewer elements per diagram, and only Context + Container maintained long term. Sketches on a whiteboard stay unregulated; only diagrams that outlive the meeting get the checklist.

An unlabelled architecture diagram is a map with no legend, no scale, and no compass: the roads might be rivers, and north might be anywhere. The map only works because the person who drew it is standing next to you.

saying these in an interview costs you the question

  • "Everyone here knows what the boxes mean" — the diagram's audience includes future joiners and other teams
  • Using colour alone to encode meaning, with no key
  • Mixing users, services, queues, tables, and classes on one page
  • Double-headed unlabelled arrows
  • No date or status, so readers cannot tell current from proposed
  • Believing strict UML is the only alternative to ambiguity — a consistent house notation with a key also works

context

resolving links…