Whimsical LogoWhimsical LogoWhimsical Logo

Brand
Get all logo versions.
Download
TemplatesDiagramsSequence Diagram example

UML Sequence Diagram

A UML sequence diagram shows one interaction over time: the objects involved as vertical lifelines, the messages between them as arrows, reading top to bottom. This template is a worked example, a task runner's run() call across six lifelines, with synchronous calls, returns, guard conditions, an exception, and the retry that recovers from it. Trace it once, then map your own calls the same way.

Use this template
A UML sequence diagram of a run() call: six lifelines, guards, an exception, and a retry.

What's included

  • Six lifelines. main.py as the actor, then Runner, Workflow, ThreadPoolExecutor, Task, and the Callable it runs.
  • The full message notation. Solid arrows for synchronous calls, dashed for returns, activation bars showing who holds control.
  • Guard conditions in brackets. '[for each layer: dep failed] mark SKIPPED' and '[artifacts_dir set]' show conditional logic inline.
  • An error path that recovers. Attempt 1 raises an exception, a retry delay self-message sleeps, attempt 2 returns a result.
  • A built-in legend. The board states its own notation, so readers don't need the spec open in another tab.

Why draw a sequence diagram?

  • Time becomes visible. Code shows what can happen; the diagram shows what happens in order, which is where race conditions hide.
  • Error paths get designed, not discovered. Drawing the exception arrow forces the question that's easiest to postpone: then what?
  • The cheapest design review. Walking six lifelines takes minutes; walking the same logic in a debugger takes an afternoon.
  • API conversations need it. Who calls whom, with what, and what comes back is exactly what a sequence diagram says.
  • Onboarding to async code. Executors, futures, and callbacks confuse on paper less than they confuse in code.

How to use this template

  1. Pick one scenario. A sequence diagram covers a single path, like one task failing once and succeeding on retry; draw other paths separately.
  2. Lay out the lifelines. Left to right in calling order: the entry point first, the deepest dependency last.
  3. Draw the happy-path calls. Solid arrows down the page in time order, with activation bars while each object works.
  4. Add the returns. Dashed arrows back, labelled with what actually comes back: layers, results, futures.
  5. Mark guards and loops. Square brackets for conditions; a self-message works for retries and internal steps.
  6. Draw the failure. Add the exception arrow and what handles it; if the diagram has no error path, it isn't finished.
Map your call flow

Sequence diagram vs activity diagram

Both are UML behavior diagrams; they answer different questions. The sequence diagram answers 'who talks to whom, in what order?': lifelines, messages, returns, one concrete scenario at a time. The activity diagram answers 'what happens next?': actions, decisions, and merges flowing like a flowchart, indifferent to which object acts. Designing an API call chain or debugging async behavior wants a sequence diagram; mapping an approval process or an algorithm wants an activity diagram.

Frequently asked questions

  • A sequence diagram is the UML diagram that shows how objects interact in one scenario, ordered by time. Each participant gets a vertical lifeline; messages between them are horizontal arrows, solid for calls and dashed for returns, read top to bottom. Activation bars on the lifelines show who's doing work. It's the standard way to design and document call flows, APIs, and async interactions.

  • Guard conditions go in square brackets on the message, like this template's '[for each layer: dep failed] mark SKIPPED'; the message only fires when the guard is true. Full UML adds combined fragments, boxes labelled alt for if/else, opt for a single optional block, and loop for repetition. For simple cases, a guarded self-message reads more clearly than a fragment box, which is how this board draws its retry.

  • As a return message that carries the bad news: in this template, attempt 1's func(*args) comes back as a dashed 'raise Exception' arrow, the Task self-messages a retry delay and sleep, and attempt 2 succeeds. The activation bars make the stack visible while it happens. The error path deserves the most care; it's often the reason you're drawing the diagram in the first place.

  • A system sequence diagram treats the whole system as one black-box lifeline and shows only the messages between actors and that box; it belongs to requirements analysis. A full sequence diagram, like this template, opens the box: every internal object gets its own lifeline, and you see the runner delegate to the workflow, the executor, and the task. SSD first to agree what the system does, then this to design how.

  • A sequence diagram is object-centric: who sends what to whom, in time order, for one scenario. An activity diagram is workflow-centric: the steps and decisions of a process, closer to a flowchart, without caring which object does each step. Use a sequence diagram to design how code or services talk; use an activity diagram to map a business process or an algorithm's control flow.

Similar templates

Diagrams

Restaurant UML Use Case Diagram

A restaurant UML use case diagram: actors connected to use cases, with associations and extend links.

Diagrams
Diagrams

Class Diagram

A worked UML class diagram of a task runner, from attributes to relationships.

Diagrams
Diagrams

Activity Diagram

A worked UML activity diagram of order fulfillment: swimlanes, a stock decision, and a parallel fork.

Diagrams
Diagrams

State Diagram

A UML state diagram of an order lifecycle: states from Draft to Delivered, with labeled transitions.

Diagrams
Diagrams

Architecture Diagram

A layered reference architecture: clients, edge, services, data, plus async and third-party.

Diagrams
Diagrams

Plot diagram

The Freytag arc: tension rising to a climax across three acts, then falling to resolution.

Diagrams