LESSON 3.3

Sequence diagrams

A sequence diagram shows which objects talk, in which order, and what each call returns. It turns vague flow descriptions into testable contracts.

6 min read

A sequence diagram adds time to a class diagram. It shows which objects participate in a use case, in what order they communicate, and what each call returns. It is the cheapest way to find circular dependencies before writing any code.

Reading a sequence diagram

Each vertical line is an object (called a lifeline). Each horizontal arrow is a method call. The arrow label is the method name and arguments. The return arrow (often dashed) carries the return value.

Reading downward gives the time order. A method body spans the rectangle (activation) on its lifeline. Arrows that go both ways (call then return) describe synchronous calls. In an async system, the return never arrives — or arrives on a different lifeline.

The booking use case

Requirement: A customer books a ticket. The system checks availability, charges the card, then confirms the booking.

Lifelines: Customer, BookingService, SeatInventory, PaymentGateway.

Customer → BookingService.book(seatId, card)
BookingService → SeatInventory.reserve(seatId) → returns true
BookingService → PaymentGateway.charge(card, amount) → returns receipt
BookingService creates a Booking(seatId, receipt) and returns it to Customer

This reveals three things:

BookingService depends on both SeatInventory and PaymentGateway.
If reserve returns false, charge must not be called — BookingService must branch.
PaymentGateway.charge needs an amount. Where does the amount come from? The diagram forces you to answer.

Laying out the diagram…

BookingService orchestrates the booking. Each arrow in the sequence diagram is a dependency here.

In code

What a sequence diagram reveals

After drawing the diagram, ask:

Circular dependency? If A calls B which calls A, you have a cycle. Break it with an event or an intermediate object.
Missing data? If a call needs data that no previous step produced, the diagram is incomplete.
Branching? If a call can fail, the diagram needs an alternate path. Missing alternate paths become missing error-handling code.

Where you have already seen it

Postman visualizations of API chains are informal sequence diagrams. OpenAPI links capture the same idea for REST APIs. Java's CompletableFuture.thenCompose chains are a sequence diagram expressed in code. Actor frameworks (Akka, Erlang) use explicit lifelines and message passing as their core abstraction.

Quick check

The booking sequence shows that SeatInventory.reserve returns null on failure. What must BookingService do before calling PaymentGateway.charge?

Try it

Ticket Booking LLD

Draw the sequence for booking, cancellation and refund before implementing any of the three.

Check your understanding

1.A sequence diagram shows that PlaceOrder sends a message to PaymentGateway which sends a message to FraudCheck. What does this tell you about PaymentGateway?
2.A message from OrderService to Inventory has a return value 'reserved: bool'. What does the sequence diagram tell you to add to Inventory?
3.Why draw a sequence diagram before writing the method?

Practice it

Ticket Booking LLDReserve seats with expiring holds and reconcile payment without overselling.Parking Lot LLDModel spots, tickets, and pricing with clear responsibilities and safe allocation.

Your notes

1 class SeatInventory { 2 #seats = new Map(); 3 add(id, price) { this.#seats.set(id, { id, price, reserved: false }); } 4 reserve(id) { 5 const seat = this.#seats.get(id); 6 if (!seat || seat.reserved) return null; 7 seat.reserved = true; 8 return seat; 9 } 10 } 11 class PaymentGateway { 12 charge(card, amount) { 13 if (!card) throw new Error("Card required"); 14 return { receipt: `R-${Date.now()}`, amount }; 15 } 16 } 17 class BookingService { 18 #inventory; #gateway; 19 constructor(inventory, gateway) { 20 this.#inventory = inventory; 21 this.#gateway = gateway; 22 } 23 book(seatId, card) { 24 const seat = this.#inventory.reserve(seatId); 25 if (!seat) return { ok: false, reason: "unavailable" }; 26 const payment = this.#gateway.charge(card, seat.price); 27 return { ok: true, seat: seat.id, receipt: payment.receipt }; 28 } 29 } 30 const inv = new SeatInventory(); 31 inv.add("A1", 50); 32 const svc = new BookingService(inv, new PaymentGateway()); 33 const result = svc.book("A1", "4111111111111111"); 34 console.assert(result.ok); 35 console.log(result);

1 public class Example { 2 static final class SeatInventory { 3 record Seat(String id, double price, boolean reserved) { 4 Seat reserve() { return new Seat(id, price, true); } 5 } 6 private final java.util.Map<String,Seat> seats = new java.util.HashMap<>(); 7 void add(String id, double price) { seats.put(id, new Seat(id, price, false)); } 8 Seat reserve(String id) { 9 var seat = seats.get(id); 10 if (seat == null || seat.reserved()) return null; 11 var reserved = seat.reserve(); seats.put(id, reserved); return reserved; 12 } 13 } 14 static final class PaymentGateway { 15 record Receipt(String id, double amount) {} 16 Receipt charge(String card, double amount) { 17 if (card == null) throw new IllegalArgumentException("Card required"); 18 return new Receipt("R-" + System.currentTimeMillis(), amount); 19 } 20 } 21 record BookingResult(boolean ok, String seat, String receipt) {} 22 static final class BookingService { 23 private final SeatInventory inventory; 24 private final PaymentGateway gateway; 25 BookingService(SeatInventory i, PaymentGateway g) { inventory=i; gateway=g; } 26 BookingResult book(String seatId, String card) { 27 var seat = inventory.reserve(seatId); 28 if (seat == null) return new BookingResult(false, null, null); 29 var payment = gateway.charge(card, seat.price()); 30 return new BookingResult(true, seat.id(), payment.id()); 31 } 32 } 33 public static void main(String[] args) { 34 var inv = new SeatInventory(); inv.add("A1", 50); 35 var svc = new BookingService(inv, new PaymentGateway()); 36 var result = svc.book("A1", "4111"); 37 if (!result.ok()) throw new AssertionError(); 38 System.out.println(result); 39 } 40 }