Sequence diagrams

What is a sequence diagram?

A sequence diagram shows the ordered exchange of messages between participants over time. Where an architecture diagram is a map, a sequence diagram is a timeline: it answers “for this specific operation — say, ‘run a candidate’s code’ — who calls whom, in what order, and how long does each step take?”

The grammar

Actor / lifeline

Each participant (a client, service, or datastore) gets a header and a vertical dashed lifeline running down the page — its existence over time.

Message

A horizontal arrow from one lifeline to another. Synchronous (solid) means the sender waits for a reply; asynchronous (dashed) means it doesn’t.

Return

A dashed arrow back to the caller carrying the response. Its latency counts toward the request total.

Activation bar

The thin rectangle on a lifeline showing when that participant is actively processing.

Frames: ALT, LOOP, OPT

Frames express control flow inside a sequence: ALT for branches (success vs. failure paths), LOOP for repetition (retry, batch), and OPT for an optional step. Skeema renders frames as labeled boxes with dashed separators between branches.

Latency & bottlenecks

Skeema estimates a latency for every message based on the receiving actor’s kind and keyword patterns — e.g. an external Stripe call ≈ 300 ms, a Postgres read ≈ 15 ms, a cache hit ≈ 3 ms. It then computes the total latency of the happy path (sum of synchronous hops and returns), highlights the critical path, and flags the slowest messages as bottlenecks. This turns a diagram into a back-of-the-envelope performance model.

When to use one

• •Designing or reviewing a specific operation (checkout, login, “place order”).
• •Estimating end-to-end latency before building.
• •Spotting chatty designs — too many synchronous hops in a row.
• •Documenting an API contract from the messages exchanged.