Sequence Diagrams
A sequence diagram is a UML interaction diagram: it models a scenario through the messages exchanged between participants, ordered in time. The participants line up across the top, a dashed lifeline drops from each, and the messages are horizontal arrows read from top to bottom, in the order the exchanges occur. The shape of the arrow carries the meaning: solid line with a filled head for a synchronous call that blocks the sender, solid line with an open head for an asynchronous send, dashed for a return. An alt fragment frames the branches, such as an authentication that succeeds or fails. The business analyst reaches for it to refine a use case into interaction detail and to validate the order of an exchange with stakeholders.
Goal
A sequence diagram specifies the behaviour of a scenario: who sends which message to whom, in what order and what comes back. It takes a single path through a use case and unfolds it participant by participant, from top to bottom in chronological order. Its value rests on two uses. It renders an interaction legible enough to be validated with stakeholders, who follow the chronology without mastering the notation in depth. And it specifies it precisely enough for a team to build against, every call named, every wait explicit, every branch guarded by its condition. The deliverable is a behavioural specification of one scenario, traced back to the use case it refines. It shows how participants interact over time; how they are structurally related belongs to the UML class diagram.
Usage
When to use it
- Refining a use case: turn the steps of a scenario into concrete messages between participants.
- Validating exchange logic with non-technical people: the chronological form follows without special background.
- Fixing the order and direction of calls in a complex sequence: an authentication handshake, a multi-system transaction, a callback notification.
- Specifying collaboration between components or interface elements: showing who calls whom and what comes back.
When not to use it
- Structure needed, not behaviour: for the relationships between entities, reach for the UML class diagram.
- A single linear flow, no branch or third-party system: the ceremony does not pay off, a use case in prose is enough.
- A business flow for a non-technical audience across roles: too technical here, reach for process modelling.
Description
A sequence diagram is an interaction diagram: it models the logic of a scenario through the messages exchanged between a set of participants, ordered in time. It answers a question of behaviour, who speaks to whom and in what order, where the UML activity diagram describes the flow of control inside a single system and the class diagram describes structure. BABOK ranks it among the techniques that refine a use case into interaction detail and sometimes calls it an event diagram.
Participants, lifelines and execution bars
A participant is a box at the top of the diagram, labelled name:Class, either part being omittable; an anonymous participant is written :Class. A participant that stands for a human role or an external system, the actor, may carry the stick figure. Each box owns a column. From its base descends the lifeline, a vertical dashed line running the whole time the participant exists in the scenario; time flows downward. On this line, the execution bar, a thin rectangle, marks the period during which the participant is handling an operation; nested bars show a call inside a call. A lifeline can end in a large cross, at the moment the participant is destroyed and ceases to exist.
The messages carry the meaning
The meaning is read in the shape of the arrow. A synchronous message, a call, is drawn as a solid line ending in a filled head: the sender blocks, it can do nothing until the reply comes back. An asynchronous message is drawn as a solid line ending in an open head, a thin point: the sender continues its own processing without waiting. The return message, the reply, is drawn as a dashed line ending in an open head, coming back to the caller; it reads in pairs with the synchronous call that triggered it. The costliest confusion turns on a detail: a return drawn as a solid line becomes an asynchronous message and the reverse. The asynchronous message and the return share the open head; only the line, solid or dashed, separates them.
Combined fragments: branch, repeat, parallelise
Control of the flow inside an interaction is drawn as a combined fragment, a frame around a region of the diagram, with an operator inscribed in the top-left corner. Four suffice at the conceptual level. alt sets up alternatives: two guarded operands, separated by a dashed horizontal line, the choice between two branches of the diagram, for instance a successful authentication against a failed one. opt sets up an optional fragment, which runs only if its guard is true. loop sets up a repetition, optionally bounded by loop(min,max) or by a guard. par sets up concurrent operands, run in parallel. The guard, a boolean in square brackets, states the condition under which a message or an operand fires. An alt with no guards is the classic trap: it shows that two outcomes exist without saying which occurs when.
Building the diagram
The diagram is built scenario by scenario. First pick a scenario, a single path through the use case, the main path or a specific alternate; one diagram models one scenario. Then identify the participants that exchange messages on that path, actors, interface components, services and systems, key objects, arranged left to right in the order of their first involvement, the initiator on the left. Draw the heads and the lifelines. Then walk the scenario in order, each interaction becoming an arrow from sender to receiver, going downward; choose the arrow type deliberately, synchronous for a blocking call, asynchronous for a send without waiting, dashed for a return. Add the execution bars on the receivers, nested for nested calls. Wrap branches in an alt or an opt, repetition in a loop, concurrency in a par and write the guards. Mark the useful lifecycle events, creation and destruction. Finally validate the result with stakeholders, then reconcile it with the original use case.
A first excess is to model too much: building a complete set of diagrams for every use case of a system costs dearly and gives nothing where the order of exchanges carries no risk. Model the scenarios where the sequence itself is the difficulty, an authentication handshake, a transaction that crosses several systems, a callback flow. The second is to pile everything into a single diagram, every alternate path included, up to an illegible tangle of fragments; one scenario per diagram, the significant alternatives in their own alt or their own diagram. One deeper trap remains: expecting the diagram to show how the participants are related. It shows the interaction over time; relationships live in a class or data model, the evolution of an object across all its scenarios in state modelling and the movement of data in a data flow diagram.
AI considerations
Two uses hold firmly. The first is the first draft from a narrative: a language model turns the written description of a use case, the customer submits a payment, the system authenticates, then debits, into a first list of participants and a first message sequence. The natural interface is text-to-diagram, the model writes PlantUML or Mermaid, an engine renders it, and the diff is reviewable. The second is reverse engineering: producing a candidate diagram from execution logs, a distributed trace or a code path, to document what the system actually does rather than what was specified. Added to these are the consistency chores: renaming a participant across a whole set of diagrams, checking that every synchronous call has its return, flagging fragments with no guard.
What cannot be delegated turns on meaning and risk. Whether a call should be synchronous or asynchronous is a design decision with real consequences, blocking, timeouts, coupling; the model guesses from the wording and gets it wrong with confidence. The choice of arrow belongs to the analyst. Then data sensitivity: a diagram of authentication or payment encodes where secrets, tokens and personal data travel; handing real logs to an external model can expose precisely that, and the model will not flag that a step reveals an identifier. The analyst judges what may be modelled and where. Finally granularity: a diagram rebuilt from traces is exhaustive and illegible, a validation diagram with stakeholders is coarse by design; knowing which reader the drawing is for is not a question the tool knows how to ask.
Examples
A customer settles a bill of CHF 1'250.00 in their e-banking; the payment requires strong customer authentication before the core banking system executes it. Four participants suffice to carry the scenario: the customer, the e-banking front end, the core banking system and the authentication service.
What the diagram makes visible is the order and the synchronous or asynchronous character of the exchange, brought together on one page. The thing a reader would miss without the drawing turns on a single message: the challenge issued to the customer, the push notification or the SMS code, is asynchronous. The system does not block the whole flow waiting for it on this out-of-band channel, whereas the calls between the bank's own systems are synchronous and blocking. The alt fragment carries the fork in outcome: on successful authentication, the validated token comes back and the payment is confirmed all the way to the customer; on failure, the refusal comes back along the same path, unwinding each blocking call.
| # | From → To | Message | Type |
|---|---|---|---|
| 1 | Customer → e-Banking | submit payment (IBAN, CHF 1'250.00) | synchronous |
| 2 | e-Banking → Core banking system | initiate payment | synchronous |
| 3 | Core banking system → Authentication service | request strong authentication | synchronous |
| 4 | Authentication service → Customer | push app or SMS code | asynchronous |
| alt [authentication succeeded] | |||
| 5 | Authentication service → Core banking system | token validated | return |
| 6 | Core banking system → e-Banking | payment confirmed | return |
| 7 | e-Banking → Customer | confirmation, payment ref. | return |
| alt [authentication failed] | |||
| 8 | Authentication service → Core banking system | authentication failure | return |
| 9 | Core banking system → e-Banking | payment failure | return |
| 10 | e-Banking → Customer | payment declined | return |
Visualisations
The geometry is the content. The type of a message is read in the shape of its arrow: filled head on a solid line for the synchronous call that blocks, open head on a solid line for the asynchronous send, open head on a dashed line for the return. The dashed lifeline marks existence over time, the execution bar the period of activity, and the alt frame with its guards partitions the outcomes. These distinctions live in the line and the position; the figure must therefore be a drawing, where each shape stays faithful to the notation.
Cost
| Phase | Level | Justification |
|---|---|---|
| Preparation | Medium | The scenario and its participants must be identified, usually from an existing use case: that is the raw material of the drawing. |
| Execution | Low | A scenario fits in one diagram, drawn in a single session. The cost rises with the number of guarded branches and participants, not with the size of the system. |
| Documentation | Medium | The diagram is updated when the scenario or the interaction changes, and its value rests on the traceability maintained back to the use case. |
Tooling
A whiteboard is enough for a first sketch: four participants and a dozen messages fit on a sheet. The general-purpose drawing tools, diagrams.net, Lucidchart or Visio, carry sound sequence stencils, with lifelines and arrowheads ready to hand, but their contribution stops at the drawing. Text-to-diagram, PlantUML or Mermaid, describes the sequence in a few lines of text that an engine turns into an image: the diagram is reviewed in a diff and versioned like code, which suits it when it evolves across releases. The UML modelling workbenches, Enterprise Architect or Visual Paradigm, hold the diagram as an object of the model, traced back to the use case it refines, and the tool flags a synchronous call with no return or a fragment with no guard.
Sources
- IIBA, A Guide to the Business Analysis Body of Knowledge (BABOK Guide) v3, §10.42 Sequence Diagrams: what a sequence diagram models, the refinement of a use case into one or more diagrams, the strengths and limitations and the list of elements at the conceptual level.
- OMG, Unified Modeling Language (UML), Version 2.5.1, the Interactions clause: the normative notation, dashed lifeline, execution specification, synchronous message with filled head, asynchronous with open head, dashed return and the combined fragments alt, opt, loop and par with their guards.