Reading and drawing a system diagram

Boxes, arrows and what they must say.

A diagram is the main way designers talk to each other, so it needs to be read and drawn carefully. A good one answers three questions at a glance: what are the parts, who talks to whom, and what travels along each connection. A bad one is a pile of unlabeled boxes where everyone sees something different.

Read it by following one request. A user's request enters a load balancer, which hands it to one of several API servers. The API checks the cache; if the data is missing it asks the database. Work that does not need to finish before replying, such as sending a confirmation email, is placed on a queue and handled later by a worker. The arrows have direction because it matters who initiates a call: the API calls the database, not the other way round.

Also look for what is missing. In the diagram above there is one database and one load balancer. Each is a single point of failure: if it dies, the whole system stops. A reader who sees that can ask the right question early, which is the real purpose of drawing.