Sequence diagrams

What a sequence diagram is

A UML sequence diagram plots one exchange against the clock: it shows which object triggers which behaviour in which other object, and in what order those triggers land. The key classes involved in a scenario are laid out across the top, each with a lifeline dropping down the page; time is measured vertically, downward; each arrow between lifelines is an event — an interaction that moves control or information from one object to another; and the narrow vertical rectangles drawn on a lifeline show the periods the object spends actively processing.

The most useful one-line characterisation of it is that a sequence diagram is a shorthand version of a use case. The use case is the prose; the sequence diagram is the same story rewritten so that the participants and the ordering are unambiguous. It carries less detail than the use case narrative and more precision, which is exactly the trade you want when the question you are trying to answer is who has to talk to whom, and in what order.

Building one from a use case

The construction is mechanical, and being able to describe the procedure is worth marks in itself. First, read the use case and mark every point where information is exchanged — each of those is an event. Second, decide which object generates each event and which object recognises it; that assignment turns a list of events into arrows with two ends. Third, order the arrows by time and draw them down the page. Fourth, review: every event should trace back to a sentence in the use case, and every object should have a reason to be there.

Because a sequence diagram is per-scenario, not per-use-case, a use case with a primary scenario and three exceptions may need more than one. Draw the primary path first. The exception paths are usually where the interesting design questions live — what happens when the locker does not answer — but they are unreadable until the happy path is on paper.

Collating the events gives you the interfaces

Once a sequence diagram is complete, every event that crosses into an object is one of that object's input events and every event leaving it is one of its output events. Collating those two lists per object is the payoff, because that pair of lists is a first draft of the object's interface: the messages it must be prepared to receive become operations it has to offer, and the messages it sends become the collaborators it has to know about.

That second half is where the diagram starts doing design work whether you intended it or not. Every arrow you draw is a statement that one object knows about another, and knowing about another object is precisely what coupling measures. A sequence diagram with arrows from every lifeline to every other lifeline is telling you, before a line of code exists, that the design will be expensive to change. Redrawing it so that one object mediates — so that the arrows form a spine rather than a mesh — is a design decision taken at the cheapest possible moment.

Worked example — Collect a reserved tool

A BorrowBox member walks to the locker bank and scans the QR token on their phone. Four participants matter: the Member, the App on the phone, the ReservationService in the cloud, and the LockerController, which is a third-party device on the street. Six events, in order: the member scans the token into the app; the app asks the service to verify it; the service, satisfied that the hold has not expired, tells the controller to open bay 7; the controller reports the door opened; the service issues a receipt; the app shows it to the member.

Collate the events for the LockerController and you get an interface with one input (openDoor(bay)) and two outputs (doorOpened, doorClosed). That is a very small interface for a device the team does not own and cannot debug, which is exactly the property you want — and you can see it is small only because the diagram is drawn. Notice also what this diagram cannot tell you: it says nothing about whether the tool copy is allowed to move from Reserved to CheckedOut right now, because that is a fact about one object over its whole life, not about one ordered exchange. That question needs the next lesson's notation.