A reviewer looks at your architecture diagram and asks whether an arrow is a network call or a data flow, and whether it is synchronous. Why do most diagrams fail this question, and what must every box and line carry?

Why the question keeps coming up

Most diagrams are drawn to help the author think, and then published as though they were specifications. In the author's head each arrow already has a meaning; on the page it is a line, and a line can mean "calls", "sends events to", "reads from", "depends on at startup", "replicates to" or "a person sometimes exports a CSV to".

The reviewer's question is not pedantry. Every one of those meanings implies a different failure mode, and the failure modes are the reason anybody is reading the diagram.

What every line must say

• Direction of the call, not the direction of the data. These are frequently opposite: a service that polls another has an arrow towards the data source, and the data moves back. State which convention the diagram uses, in a legend.
• Synchronous or asynchronous, because this determines whether the caller's latency and availability are affected by the callee. This is the single highest-value annotation on any diagram.
• The protocol and roughly the volume, when either is load-bearing: "gRPC, 2k rps" tells a reader more than a labelled arrow ever will.
• What happens when it fails: a dashed line for a dependency that degrades gracefully against a solid one that does not is a convention teams adopt in an afternoon and use for years.

What every box must say

Who owns it, and whether it is yours. A diagram with your six services and four third parties drawn identically hides the only distinction that matters during an incident: which of these can you fix. Shade or group anything outside your control.

Why this matters more than diagram beauty

A diagram is read most carefully during an incident and during a security review, and both readers are looking for the same thing: what talks to what, in which direction, and what happens when one of them stops. A beautiful diagram that does not answer those questions costs the reader the time it takes to ask, and they ask the author, who may not be available.

Common weak answers

• "The details are in the code." Then the diagram's function is to tell the reader where in the code to look, which it cannot do if it does not distinguish a queue from a call.
• "We'll keep a separate legend document." A legend that is not on the page is not a legend. Put it in the corner of the image, where it survives being pasted into a chat channel.