Diagramming Event-Driven Systems

Make the broker the centre

In an event-driven design the interesting part is what flows through the middle. Put the topics or queues in the centre of the diagram, producers on the left and consumers on the right. Name each topic after what happened, such as order created, so the diagram reads like a list of facts.

Show who knows about whom

The great virtue of events is that a producer does not know its consumers, so do not draw arrows from producer to consumer. Draw an arrow into the topic and an arrow out of it. If a reader can add a consumer without redrawing the producer, your diagram matches your architecture.

Draw the unhappy paths

Retries, dead letter queues and replay tools are where event systems actually live. Add them explicitly: a dashed arrow from the consumer back to the queue for retries, a separate dead letter queue and an alert. The dead letter template does this in six nodes and is a good starting point to copy.

Record ordering and delivery guarantees

Annotate the topic with its partitioning key and delivery guarantee, for example ordered per order id, at least once. Those two facts determine whether consumers need to deduplicate and whether they can rely on sequence, and they are the details people forget until production.

Keep one diagram per business flow

A single picture of every topic and consumer in a company turns into a hairball. Draw one diagram per business flow, such as placing an order, and link them by the topics they share. Each page then answers one question, and a new teammate can follow a single event from cause to every effect without untangling unrelated traffic.

Try it with a template

• Pub/Sub Fan-Out
• Saga Orchestration
• Transactional Outbox
• Dead Letter Queue