subroute.
Beginner16 min readUML & Diagramminglive prototype

Sequence Diagrams

A sequence diagram is the story of one request told top to bottom — who calls whom, in what order, and what comes back. Where a class diagram shows the pieces, a sequence diagram shows them talking.

The idea

What it is

A sequence diagram shows how a group of objects talk to each other to get one job done. You line the objects up across the top, drop a vertical line down from each, and then draw arrows between those lines — one arrow per message — reading from the top of the page to the bottom. The vertical position is the timeline: an arrow drawn higher up happens before an arrow drawn lower down. So the whole picture answers one question a class diagram can't: in what order do things happen?

Think of it like the transcript of a phone-call relay. Person A rings Person B and asks for something; B can't answer alone, so B rings C; C does the work and tells B; B finally tells A. If you wrote that conversation down line by line, top to bottom, you'd have a sequence diagram. The objects are the people, the arrows are the calls, and reading downward replays the conversation in the exact order it happened.

The one sentence to remember

A sequence diagram = participants across the top, a dashed lifeline dropping from each, and arrows between the lifelines read top-to-bottom as time. A class diagram shows what the pieces are; a sequence diagram shows the order they talk in.

Mechanics

How it works

Participants across the top, lifelines dropping down

Every object that takes part sits in a box along the top of the diagram. An object is written as :OrderService (a colon then the type) or order:OrderService (a name, colon, type). A plain stick-figure on the far left is an actor — usually a human user. From the bottom of each box, a thin dashed vertical line drops straight down: that's the lifeline, and it represents that object existing through time. Time always flows downward — the higher an arrow sits, the earlier it happens.

User :OrderUI :OrderService :Payment time ↓ checkout() placeOrder() charge() return return return
Time flows downward — the higher an arrow, the earlier it happens. A solid line + filled arrowhead is a call (checkout() → placeOrder() → charge()); a dashed line + open arrowhead is the reply travelling back. The orange bars show which object is busy handling work right now.

A message is an arrow from caller to callee

The heart of the diagram is the message: an arrow drawn from the lifeline of the object that makes the call to the lifeline of the object that receives it. The label on the arrow is the method being called, e.g. placeOrder(). Read every arrow the same way: left end is who's calling, the arrowhead points at who's being asked to do the work.

The activation bar — "this object is busy"

A thin tall rectangle sitting on top of a lifeline is an activation bar (also called an execution occurrence). It means this object is currently busy doing work — its method is running. The bar starts when a message arrives and ends when that method returns. Bars stack: while OrderService is busy and calls Payment, both bars are lit at once, because OrderService is waiting on Payment to finish.

Two line styles: the call and the return

There are two arrows you must tell apart, and the style of the line carries the meaning:

  • Synchronous call — a solid line with a filled (solid triangle) arrowhead. The caller asks and then waits for the answer before doing anything else. This is an ordinary method call.
  • Return — a dashed line with an open (thin, line) arrowhead, drawn back from callee to caller. It carries the result, e.g. ok or orderId. Returns are often left out to reduce clutter, but the dashed style always means coming back with an answer.

Solid vs dashed, in one breath

Solid line, filled head = a call going out (someone is asking for work). Dashed line, open head = a result coming back. If you only remember one thing about the arrows, remember solid goes, dashed returns.

A self-call: an object asks itself

Sometimes an object calls one of its own methods. You draw this as an arrow that leaves the lifeline and loops back to the same lifeline just below — a little hook shape. The activation bar gets slightly wider (nested) to show a method calling another method on the same object. Example: OrderService calls its own validate() before charging.

Combined fragments: if/else, optional, and loops

Real flows have choices and repetition. UML wraps a region of messages in a labelled box called a combined fragment to show this. The label in the top-left corner tells you how to read the box. The three you'll meet most:

  • `alt` — an if / else. The box is split by a dashed divider; the top half runs when the condition (the [guard]) is true, the bottom half otherwise. Example: [in stock] ship now, [else] back-order.
  • `opt` — optional. The messages inside run only if the guard is true, otherwise the whole box is skipped. Example: [customer opted in] send a marketing email.
  • `loop` — repeat. The messages inside run again and again while the guard holds. Example: loop [for each item] add the item to the basket.

Keep it to one scenario

A sequence diagram is at its best when it tells one clear story — the happy path of a single request. If you try to cram every branch, error, and retry into one diagram with stacks of alt boxes, it turns into spaghetti. Draw the main flow first; add a second small diagram for the tricky error case if you really need it.

Interactive prototype

See it. Build it. Break it.

A sandboxed, hands-on simulation — no setup, no install. Play with it as you read.

About this simulation

Watch one checkout request travel through five participants — User, :OrderUI, :OrderService, :Payment, :Database — one message at a time. Each participant has a dashed lifeline dropping down the page, and time flows downward. Click Next › to reveal the next arrow: a solid arrow for a call, a dashed arrow for a return. An activation bar lights up on whoever is currently busy. The single fixed-height note explains that one message — who calls whom, and why the line looks the way it does. Nothing scrolls away or grows the page.

Hands-on

Try these yourself

Open the prototype above, predict what happens, then verify.

try 01

Replay the request top to bottom

Open the prototype and click Next › repeatedly without reading the notes yet. Watch the arrows appear one by one, always lower than the last — that downward march is time. By the end you've watched a checkout travel User → :OrderUI → :OrderService → :Payment → :Database and the answers come back. Now click Start over and step through again, this time reading each note.

try 02

Tell a call from a return

Step to the charge() message: notice it's a solid arrow with a filled head pointing into :Payment — a call going out. Step once more to the ok arrow: it's dashed with an open head pointing back to :OrderService — a result coming home. Say it out loud: solid goes, dashed returns. That single habit lets you read any sequence diagram.

try 03

Watch the activation bars stack

Find the step where :OrderService has called :Payment. Both activation bars are lit at the same time. Ask yourself why — because :OrderService is waiting on :Payment to finish before it can continue. When :Payment returns, its bar ends but :OrderService's stays lit until it returns to :OrderUI. Stacked bars = somebody is blocked waiting on somebody else.

In practice

When to use it — and what trips people up

When to reach for a sequence diagram

Draw one whenever the interesting thing is the order of interactions, not the static shape: explaining how a feature works end to end, documenting an API call chain, debugging who calls whom in a tangled flow, or showing how several services collaborate to serve one request. If you ever catch yourself saying “first this happens, then that, then it calls...”, that sentence is a sequence diagram waiting to be drawn.

In interviews: structure and behaviour are a pair

Sequence diagrams shine when you're asked to explain a flow or an algorithm's interactions — a checkout, a login, a cache miss. Pair it with a class diagram: the class diagram is the structure (what the pieces are) and the sequence diagram is the behaviour over time (the order they talk in). Sketching both shows an interviewer you can reason about a design from both angles.

What it gives you

  • Makes the order of events obvious — you can literally read the flow top to bottom like a script.
  • Exposes chatty or tangled designs: too many arrows criss-crossing means too much coupling between objects.
  • Great teaching and review tool — a newcomer can follow one request through the whole system in seconds.
  • Pairs perfectly with a class diagram: structure plus behaviour gives a complete picture of a design.

Common mistakes

  • Shows behaviour, not structure — it won't tell you what classes exist or how they're related (that's a class diagram).
  • Covers one scenario at a time; capturing every branch and error needs alt/opt/loop boxes that quickly get busy.
  • Goes stale fast — the message order changes the moment the code does, so detailed diagrams need re-drawing.
  • Easy to overload — a diagram with twenty lifelines and a hundred arrows teaches nothing; keep it to the messages that matter.

Reference

Code & further reading

A minimal reference implementation and pointers worth bookmarking.

// This is the code the sequence diagram draws. Each call below is one
// arrow in the diagram, top to bottom. Returns are the dashed arrows.

class OrderUI {
  constructor(private service: OrderService) {}

  // User → :OrderUI  "checkout()"   (the actor's first message)
  checkout(cart: Cart): string {
    return this.service.placeOrder(cart);   // :OrderUI → :OrderService  "placeOrder()"
  }
}

class OrderService {
  constructor(private payment: Payment, private repo: OrderRepository) {}

  placeOrder(cart: Cart): string {
    this.validate(cart);                     // self-call: :OrderService → itself  "validate()"
    const ok = this.payment.charge(cart.total); // → :Payment  "charge()" ; dashed return "ok"
    if (ok) {
      return this.repo.save(cart);           // → :Database  "save()" ; dashed return "orderId"
    }
    throw new Error("payment failed");
  }

  private validate(cart: Cart): void { /* ... */ }
}

References & further reading

6 sources

Knowledge check

Did it land?

Quick questions, answers revealed on submit. Sign in to save your best score.

question 01 / 05

In a sequence diagram, what does the vertical position of an arrow tell you?

question 02 / 05

You see a dashed line with a thin open arrowhead pointing back from :Payment to :OrderService. What is it?

question 03 / 05

What does the thin tall rectangle (activation bar) sitting on a lifeline mean?

question 04 / 05

A flow needs to repeat a set of messages once for every item in a cart. Which combined fragment wraps those messages?

question 05 / 05

Your teammate wants to know what classes exist and how they're related (contains, inherits). Is a sequence diagram the right tool?

0/5 answered