System Sequence Diagram (SSD): Guide With Examples
November 11, 2026 · 12 min read
System Sequence Diagram (SSD): What It Is, With Examples
A system sequence diagram (SSD) shows one use-case scenario as a short exchange between outside actors and your system, which appears as a single black box. Time runs down the page, and every solid arrow from an actor into the system is a system event it must handle. It tells you what the system does, not how.
What Is a System Sequence Diagram?
An SSD takes one path through one use case and asks a narrow question: what does the actor tell the system, and what does the system send back? The actor sits on the left. The whole system sits on the right as one lifeline, usually labelled just System. Nothing inside it is shown.
The SSD is best known from Craig Larman's Applying UML and Patterns, which places SSDs in the requirements and analysis work of the Unified Process. You'll also see it spelled "systems sequence diagram". Both names mean the same artifact.
The notation is plain UML sequence-diagram notation. The UML specification defines sequence diagrams, but UML itself doesn't list the SSD as its own diagram type. What makes a diagram an SSD is the scope you choose, not new symbols.
System Sequence Diagram vs Sequence Diagram: What's the Difference?
A regular sequence diagram opens the box and shows the objects, services and databases that collaborate inside it. An SSD keeps the box shut. That one choice changes who draws it, when, and at what level of detail.
| System sequence diagram | Design-level sequence diagram | |
|---|---|---|
| Scope | The system boundary, seen from outside | Objects and components inside the system |
| Participants | Actors plus one System lifeline (and external systems) | Classes, services, databases, queues |
| Project phase | Requirements and analysis | Design and implementation |
| Message level | System events named by intent, such as enterItem | Method calls and API requests |
| Main readers | Analysts, testers, product owners | Developers |
Later, a design-level diagram picks up each system event from the SSD and shows how the objects inside the black box handle it.
Actors, the System Lifeline and System Events
Three building blocks cover almost every SSD you'll draw:
- Primary actor. The person or system that starts the use case, drawn on the left. In a shop checkout that's the Cashier.
- The System lifeline. One lifeline for the whole system under discussion. Secondary actors, such as a bank or a payment gateway, get their own lifelines to the right. They're black boxes too.
- System events. An input from an actor that the system must respond to. Name each one as a verb plus a noun at the level of intent, with parameters:
makePayment(amount), notclickPayButton.
Returns are dashed arrows carrying the information the actor needs, such as a running total. They're optional when nothing comes back, and they stay abstract: "total with taxes", not "green label on screen 3". Repetition goes in a loop frame and branches go in alt or opt frames, each with a guard condition.
Larman's own naming advice is a good test. enterItem(itemID, quantity) beats scan(itemID, quantity), because the event shouldn't care whether the item came from a scanner, a keyboard or a voice command.
How Do You Create a System Sequence Diagram From a Use Case?
You derive the diagram straight from the use-case text. Work through these steps:
- Pick one use case and one scenario. Start with the main success scenario.
- Read each step and mark the ones where an actor tells the system something.
- Name each marked step as a system event, verb plus noun, with the parameters it carries.
- Add a return for anything the actor needs to see or receive.
- Wrap repeated steps in
loopand conditional steps inaltoropt, each with a guard. - Check every event name and parameter against the project glossary.
Here's a short Process Sale scenario, written for this guide:
- Customer arrives at the checkout with goods.
- Cashier starts a new sale.
- Cashier enters an item ID and quantity.
- System records the item and shows its description and the running total. Steps 3 and 4 repeat until no items remain.
- Cashier ends the sale. System shows the total with taxes.
- Cashier tells the Customer the total and asks for payment.
- Customer pays, and the Cashier enters the amount tendered. System records the payment, shows the change due and prints a receipt.
Steps 1 and 6 happen between people, so they never reach the diagram. The rest map like this:
| Use-case step | System event | Return to the actor |
|---|---|---|
| 2 | makeNewSale() | none |
| 3 and 4 | enterItem(itemID, quantity) | description, running total |
| 5 | endSale() | total with taxes |
| 7 | makePayment(amount) | change due, receipt |
Before you draw anything, read the table back against the use case. Every system event should trace to a numbered step. No event should mention a screen, a button or a database table. If you catch yourself adding an arrow between two parts of the system, you've opened the box too early, and that detail belongs in the design.
Example 1: A POS Checkout SSD for Process Sale
Here's that mapping written as Mermaid text. Mermaid's actor keyword draws a stick figure and participant draws a box:
```mermaid
sequenceDiagram
actor Cashier
participant System
Cashier->>System: makeNewSale()
loop more items
Cashier->>System: enterItem(itemID, quantity)
System-->>Cashier: description, running total
end
Cashier->>System: endSale()
System-->>Cashier: total with taxes
Cashier->>System: makePayment(amount)
System-->>Cashier: change due, receipt
```
It renders as this diagram:
Read it top to bottom. The Cashier opens a sale, and the loop frame repeats enterItem once per item, with the running total coming back each time. endSale closes the list and returns the taxed total. makePayment finishes the scenario. Four system events, four operations the design must support, and not a single screen or button in sight.
Try it in the live editor below. Change the loop guard or add a return arrow, and the preview updates as you type:
Example 2: An ATM Cash Withdrawal SSD With a Bank Actor
The second example adds a secondary actor. The ATM can't approve a withdrawal itself, so it asks the Bank, which stays a black box on the far right. Two alt frames handle the branches:
```mermaid
sequenceDiagram
actor Customer
participant System as ATM System
participant Bank
Customer->>System: insertCard(cardNumber)
System-->>Customer: PIN prompt
Customer->>System: enterPIN(pin)
alt PIN invalid
System-->>Customer: error, retry prompt
else PIN valid
System-->>Customer: transaction menu
Customer->>System: requestWithdrawal(amount)
System->>Bank: authorizeWithdrawal(account, amount)
alt approved
Bank-->>System: approval code
System-->>Customer: cash, card, receipt
else declined
Bank-->>System: decline reason
System-->>Customer: declined message, card
end
end
```
Rendered, it looks like this:
The outer alt splits on the PIN check. Inside the valid branch, the withdrawal request triggers a call to the Bank, and a second alt covers approval and decline. Notice that the arrow from System to Bank is still at the level of intent. It doesn't say which network protocol or message format the bank uses, because that's a design decision.
What Comes After an SSD: System Operations and Contracts
Each system event becomes a system operation, a public entry point the design has to provide. For simple events the name and parameters are enough. For the tricky ones, Larman pairs the SSD with an operation contract that states what must be true before and after the operation runs:
Operation: enterItem(itemID, quantity)
Cross references: Process Sale
Preconditions: a sale is underway
Postconditions:
- a SalesLineItem was created and linked to the current Sale
- its quantity was set to the quantity parameter
- it was linked to the ProductDescription matching itemID
This contract describes state changes, not steps. It tells a tester exactly what to check after enterItem and tells a developer what the design has to achieve. The design-level sequence diagram then opens the black box and shows which objects make those postconditions true.
Keeping SSDs as Mermaid Text Next to the Use Case
A diagram drawn as text lives in the same Markdown file as the use case it describes. It diffs cleanly in Git, and GitHub renders Mermaid code blocks in Markdown files, issues and pull requests. We prefer keeping the SSD right under the use-case text so both change in the same pull request.
A booking spec might look like this. The opt frame marks a step the guest can skip, and Note labels the scenario:
### UC4: Book a Room
**Main success scenario:** the guest searches by date, picks a room,
optionally adds breakfast, then confirms and pays by card.
```mermaid
sequenceDiagram
actor Guest
participant System
participant Gateway as Payment Gateway
Note over Guest,System: UC4 Book a Room, main success scenario
Guest->>System: searchRooms(checkIn, checkOut)
System-->>Guest: available rooms, nightly rates
Guest->>System: selectRoom(roomID)
opt guest wants breakfast
Guest->>System: addBreakfast()
System-->>Guest: updated total
end
Guest->>System: confirmBooking(cardToken)
System->>Gateway: chargeCard(cardToken, total)
Gateway-->>System: payment reference
System-->>Guest: booking reference
```
The diagram part renders like this:
The Mermaid keywords that matter for SSDs are actor, participant, ->> for system events, -->> for returns, loop, alt with else, opt and Note. The Mermaid sequence diagram docs list every option, and our guide to Mermaid diagrams in Markdown covers the wider syntax. For laying out the rest of the spec, see writing documentation in Markdown, or start from one of these Markdown templates.
There's a limitation to accept. Mermaid has no way to underline a participant name, so the underlined instance style that older UML diagrams use for :System is out of reach. Its box keyword groups participants visually rather than drawing a formal UML boundary. You also can't nudge the layout by hand. If your course or client wants strict UML, you may still need a dedicated UML tool for the final deliverable. PlantUML is another text option, and our PlantUML sequence diagram syntax guide pairs each construct with its Mermaid equivalent.
When you need the diagram as an image for slides, the Mermaid editor gives you a live preview, theme selection and PNG or SVG export. For more ways to draw one, see our comparison of sequence diagram generator tools.
Frequently Asked Questions
A system sequence diagram turns one use-case scenario into a short list of system events. That list gives your design, your tests and your operation contracts a shared starting point. Keep the system as one black box, name events by intent, and use frames for loops and branches. Paste any Mermaid example above into the editor, and the preview draws the diagram on the right. Refine the events there before anyone writes code.