Arrow Semantics

A box-and-line drawing is ambiguous in a specific and consequential way. A line between two boxes can mean calls, sends events to, reads from, depends on at startup, replicates to, or "a person exports a spreadsheet once a month". The author knows which; the page does not say.

This is not a matter of neatness. Each of those meanings implies a different failure mode, and failure modes are why people read architecture diagrams in the first place. A synchronous call transmits the callee's latency and availability to the caller. An event does not. A nightly export fails silently for a week.

Why it matters

Diagrams are read most carefully in two situations: during an incident and during a security or compliance review. Both readers want the same three facts — what talks to what, in which direction, and what happens when one side stops — and both are usually reading without the author present.

An ambiguous diagram costs each of those readers a question. During an incident the question cannot always be asked, because the person who drew it is asleep, and the responder makes an assumption instead.

Implementation patterns

• Declare the arrow convention in a legend on the image: do arrows follow calls or data? These are frequently opposite, as when a service polls another and the data travels back.
• Mark synchronous versus asynchronous on every edge. If you annotate one thing, annotate this: it is what determines coupling of latency and availability.
• Distinguish hard from degradable dependencies, for example solid versus dashed, so a reader can see which failures are fatal without reading a paragraph.
• Add protocol and rough volume where they are load-bearing: "gRPC, 2k rps" or "S3, 4 TB/day" tells a reader more than any label.
• Shade what you do not own. Six of your services and four third parties drawn identically hides the only distinction an incident cares about: which of these can you fix.
• Keep the legend inside the exported image, because diagrams get pasted into chat and tickets and arrive without the page they came from.

Industry example

The C4 model's insistence that every element and relationship carry a description, and that each diagram state its notation, exists for this reason; its author has argued since 2011 that unlabelled boxes and lines are the most common defect in software architecture diagrams. Threat-modelling practice makes the same demand from a different direction: a data-flow diagram without trust boundaries and directions cannot produce findings.

Failure scenarios

• The assumed queue. A reader sees a line, assumes decoupling, and is surprised during an incident when a downstream failure propagates upstream in milliseconds.
• Reversed arrows. Half the diagram follows calls, half follows data, because two authors used different conventions and neither wrote one down.
• The invisible third party. An external dependency drawn like an internal service, so the responder spends twenty minutes looking for a fault they do not own.
• A legend in a separate document, which is to say no legend.

Trade-offs

Annotation costs drawing time and visual density, and an over-annotated diagram is unreadable in its own way. The discipline is to annotate the load-bearing edges and leave the rest plain: if every line carries four labels, the diagram has become a table and should probably be one. There is also maintenance: the more the diagram asserts, the more of it can become wrong, which is an argument for pairing this with a date and a generation source.

When not to use it

On a whiteboard mid-discussion, none of this applies. Exploratory drawing is for thinking and is disposable by design. The rule attaches at publication: the moment a diagram is pasted into a document, a ticket, a runbook or a review pack, it is being read as a specification and must say what its lines mean.

Interview question

Q: You are handed an architecture diagram during an incident. What do you look for first, and what do you do if the diagram does not tell you?

What a strong answer covers: identifying synchronous edges on the path to the failing component, because those transmit failure · finding which boxes are external and therefore not yours to fix · checking whether any line is a queue, which changes both the failure mode and the recovery · falling back to traces or service telemetry to reconstruct the real call graph when the diagram is silent · and the follow-up action of annotating the diagram from what you learned, so the next responder does not repeat the work.

Quick check

Quiz: Which single annotation adds the most value to an architecture diagram? Synchronous or asynchronous, because it determines whether the caller inherits the callee's latency and availability.

Flashcard: Why must the legend be inside the image? — Diagrams are pasted into chat, tickets and decks, and arrive stripped of everything around them.