Sequence Diagram

A sequence diagram shows how objects interact with each other over time by exchanging messages in a specific order. It captures the dynamic behavior of a system for a particular scenario—typically one path through a use case. The vertical axis represents time (flowing downward), and the horizontal axis shows the participating objects. By reading a sequence diagram top to bottom, you understand exactly what happens, in what order, and between which objects when a specific system function is triggered.

Core Notation Elements

Lifeline: A vertical dashed line extending downward from each participating object. The object is shown at the top as a rectangle with its name and class (e.g., :OrderController or customer:User). The lifeline represents the object's existence over time.

Activation Bar: A thin rectangle on a lifeline showing when the object is actively processing (executing a method). The top of the bar marks when control is received; the bottom marks when control returns.

Messages: Horizontal arrows between lifelines representing communication:

• Synchronous message (solid arrow →): The sender waits for a response before continuing
• Asynchronous message (open arrow →): The sender continues without waiting
• Return message (dashed arrow - - →): Response to a synchronous call
• Self-message (loop arrow): An object calling its own method

Combined Fragments: Frames that enclose portions of the diagram to show control logic:

• alt: Alternative paths (if-else)
• loop: Repeated execution
• opt: Optional execution (if without else)
• par: Parallel execution

Real-World Example: User Login Sequence

This diagram tells a complete story: the client sends credentials to the controller, which delegates to the auth service. The auth service looks up the user in the database, verifies the password (self-message), generates a token, stores the session in cache, and returns the token through the chain.

Combined Fragments Example: Payment with Retry

This shows a payment retry loop with up to 3 attempts, using alt to show the two possible outcomes of each attempt.

When to Use Sequence Diagrams

Use case realization: Showing exactly how a use case is implemented through object interactions. Each use case typically has one or more sequence diagrams showing main success and exception scenarios.

API design: Documenting the expected interaction pattern for API consumers—which endpoints to call in what order.

Debugging complex interactions: When a bug involves multiple components, drawing the sequence helps identify where the breakdown occurs.

Design discussions: Exploring alternative designs by sketching different interaction patterns and comparing their tradeoffs.

Protocol documentation: Defining communication protocols between distributed systems.

Sequence Diagram vs. Other Interaction Diagrams

Communication Diagram: Shows the same interactions but emphasizes the structural relationships between objects rather than the time ordering. Objects are positioned spatially, and messages are numbered to indicate sequence. Better for showing which objects collaborate; worse for showing timing.

Timing Diagram: Shows state changes along a precise time axis, used for real-time systems where exact timing matters (signal processing, hardware interactions).

Best Practices

Focus each diagram on one scenario (one path through a use case). Show only the objects relevant to that scenario. Keep diagrams readable—if a sequence requires more than 15-20 messages, consider splitting into sub-sequences. Include return values when they are architecturally significant. Use combined fragments sparingly—complex nesting becomes unreadable. Name messages with method signatures when designing code, or with descriptive labels when communicating with non-technical stakeholders.