What is a sequence diagram?
A sequence diagram is a UML behavioural diagram that shows how a set of participants interact over time to execute a specific scenario. The two axes encode different information: the horizontal axis identifies who the participants are (lifelines), and the vertical axis represents time flowing downward. Messages between participants are drawn as horizontal arrows, ordered top-to-bottom in the sequence they occur.
Sequence diagrams are defined in UML 2.5.1 (ISO/IEC 19505) and are one of the most widely used diagrams in software engineering because they directly model an interface or protocol — you can read a sequence diagram and derive an API contract from it.
UML sequence diagram notation reference
Every element in a UML sequence diagram has a precise graphical encoding. flow-chart.io generates each of these as a typed, editable object — not a freehand shape.
| Element | Symbol | Description |
|---|---|---|
| Lifeline | [ Name ] - - - - | A named box (participant) at the top with a vertical dashed line extending downward for the duration of the interaction. Represents any participant: service, user, database, or object instance. |
| Activation bar | █ (narrow rect on lifeline) | A narrow filled rectangle on a lifeline indicating the period during which the participant is actively executing — i.e., processing a synchronous call. Begins when a synchronous message arrives; ends when the return message is sent. |
| Synchronous message | ──────► | Solid line with a filled (solid) arrowhead. The sender suspends execution and waits for the callee to return. Used for standard method calls and blocking HTTP requests. |
| Asynchronous message | ──────> | Solid line with an open (stick) arrowhead. The sender does not wait for a reply — it continues execution immediately. Used for event publication, message-queue sends, and fire-and-forget operations. |
| Return message | - - - -> | Dashed line with an open arrowhead. Represents the reply from a called participant back to the caller. Label with the return value, HTTP status code, or response payload. |
| Self-message | ↩ (loop on same lifeline) | An arrow that originates and terminates on the same lifeline, indicating an internal method call or recursive invocation within a single participant. |
| alt fragment | [alt] frame | Combined fragment modelling mutually exclusive alternatives (equivalent to if/else). Each operand is separated by a dashed line and labelled with a guard condition in square brackets. Only the operand whose guard is true executes. |
| opt fragment | [opt] frame | Combined fragment modelling an optional single path. The enclosed interaction executes only if the guard condition is true. Equivalent to an if without an else branch. |
| loop fragment | [loop] frame | Combined fragment modelling repetition. The enclosed interaction executes repeatedly while the guard condition is true. The guard may also specify a minimum and maximum iteration count: loop(1,5). |
| par fragment | [par] frame | Combined fragment modelling concurrent execution. Each operand executes simultaneously, in any interleaved order. Used for parallel API calls or concurrent threads. |
| break fragment | [break] frame | Combined fragment modelling an exception or abort. If the guard is true, the enclosed interaction executes and the enclosing interaction terminates immediately — the surrounding flow does not continue. |
Real-world use cases for sequence diagrams
Sequence diagrams are most valuable when the interface between components — not the internal logic of any one component — is what needs to be designed, reviewed, or documented.
| System / Context | Process | Why a sequence diagram |
|---|---|---|
| REST API design | Endpoint contract review before implementation | Forces explicit agreement on request payloads, response codes, and error paths before a single line of code is written. |
| Microservices architecture | Inter-service call chains during a business operation | Makes latency, coupling, and synchronous bottlenecks visible at design time — before they become production incidents. |
| Authentication flows | OAuth 2.0 / OIDC token exchange, session management, MFA challenge | Security reviewers can audit the exact message order and confirm tokens never travel over unintended paths. |
| E-commerce checkout | Cart → payment processor → inventory → fulfilment → notification | Shows exactly which service owns each step and where compensating transactions are needed if a step fails. |
| WebSocket / real-time | Connection handshake, message protocol, reconnect logic | Async messages and par fragments make concurrent event streams legible in a way that prose cannot. |
| Database transactions | Multi-step write with rollback on failure | alt and break fragments model the happy path and all rollback branches in a single diagram. |
| Third-party integrations | Webhook delivery, retry logic, idempotency key handling | External systems appear as lifelines; the diagram doubles as the integration contract you share with the third party. |
| Incident post-mortems | Reconstructing the message sequence that led to a failure | Translating a log timeline into a sequence diagram reveals the exact ordering of events and the participant that broke the chain. |
Example: OAuth 2.0 authorisation code flow
This table shows the message sequence for the OAuth 2.0 authorisation code grant. Each row is one message in the sequence, ordered top-to-bottom as they occur in time.
| From | To | Message | Type |
|---|---|---|---|
| Browser | Client App | GET /login | sync |
| Client App | Browser | 302 Redirect → Auth Server /authorize?client_id&state&code_challenge | return |
| Browser | Auth Server | GET /authorize (user logs in, consents) | sync |
| Auth Server | Browser | 302 Redirect → /callback?code&state | return |
| Browser | Client App | GET /callback?code&state | sync |
| Client App | Auth Server | POST /token {code, code_verifier, client_id} | sync |
| Auth Server | Client App | 200 OK {access_token, refresh_token, id_token} | return |
| Client App | Resource API | GET /resource Authorization: Bearer access_token | sync |
| Resource API | Client App | 200 OK {resource data} | return |
Use this prompt in flow-chart.io to generate the above sequence diagram:
OAuth 2.0 authorisation code flow with PKCE: Browser navigates to /login on the Client App. Client App redirects Browser to the Auth Server /authorize endpoint with client_id, state, and code_challenge. Auth Server redirects Browser back to Client App /callback with an authorisation code and state. Client App exchanges the code and code_verifier for tokens via POST /token to Auth Server. Auth Server returns access_token, refresh_token, and id_token. Client App calls Resource API with Bearer access_token. Resource API returns 200 OK with resource data. Add an alt fragment: if the token request fails, Auth Server returns 400 Bad Request and Client App redirects Browser back to /login. Show as a UML sequence diagram.
How the AI sequence diagram generator works
- Participant extraction. The prompt is analysed to identify all participants — services, users, databases, external systems. Each becomes a lifeline in the diagram, ordered left-to-right to minimise crossing arrows.
- Message classification. Each message is classified as synchronous (blocking call), asynchronous (fire-and-forget), or return. The arrow style and arrowhead shape are set accordingly to UML 2.5.1 notation.
- Fragment detection. Conditional language ("if", "on failure", "while", "in parallel") is mapped to the appropriate combined fragment operator — alt, break, loop, or par — with guard conditions extracted from the prompt text.
- Layout pass. Lifelines are positioned left-to-right, messages are stacked top-to-bottom chronologically, and activation bars are sized to span the correct duration. The layout minimises arrow crossings and ensures readable vertical spacing between messages.
Because the output is a typed scene graph — not a rendered image — every element remains interactively editable after generation.
Sequence diagram best practices
- Keep each diagram to one scenario. A single sequence diagram should represent one use case, one API endpoint, or one failure mode — not an entire system. Split complex flows into multiple focused diagrams.
- Use alt fragments for conditional paths rather than separate diagrams. Keeping the happy path and the error path in one diagram shows the reader exactly which messages are shared and which diverge.
- Activate the activation bar for the full duration of synchronous calls. The bar should start when the synchronous message arrives and end when the return message is sent — this makes the blocking period visually explicit.
- Use asynchronous message arrows (open arrowhead) for event-driven, message-queue, and fire-and-forget interactions. Using a synchronous arrow for a Kafka publish or an SNS notification misrepresents the coupling.
- Label return messages with the return value or HTTP status code. A return arrow labelled
200 OK {token}is more useful than one labelled "response". - Name lifelines consistently with your codebase — use the actual service or class name, not an informal description. This makes the diagram immediately usable as a code review reference.
- Show only the messages that matter to the reader. Internal implementation details — private method calls, internal data transformations — should be omitted unless the diagram's purpose is to explain internal behaviour.
Frequently asked questions
- What is a sequence diagram?
- A sequence diagram is a UML behavioural diagram that shows how a set of participants (lifelines) interact over time to execute a specific scenario. Participants are represented as vertical dashed lines with a named box at the top. Messages between participants are shown as horizontal arrows in chronological order from top to bottom. Sequence diagrams are defined in UML 2.5.1 (ISO/IEC 19505) and are the most widely used diagram type for documenting API contracts, authentication flows, and inter-service communication.
- What UML notation does a sequence diagram use?
- UML 2.5.1 sequence diagrams use six core notational elements: (1) Lifeline — a named box with a vertical dashed line. (2) Activation bar — a narrow rectangle on a lifeline showing the active execution period. (3) Synchronous message — solid line with a filled arrowhead; sender waits for reply. (4) Asynchronous message — solid line with an open stick arrowhead; sender does not wait. (5) Return message — dashed line with an open arrowhead. (6) Combined fragment — a labelled frame (alt, opt, loop, par, break) enclosing interaction operands with guard conditions.
- What is the difference between a lifeline and an actor in a sequence diagram?
- A lifeline represents any participant in an interaction — a human user, a service, a database, or an object instance. An actor is a specific category that represents an entity outside the system boundary, typically shown with a stick-figure icon in use case diagrams. In a sequence diagram, actors and internal components are both represented as lifelines using the same dashed-line notation. The participant box may carry a stereotype such as «actor» or «database» to clarify the role.
- What are combined fragments and when should I use them?
- Combined fragments are labelled boxes that enclose part of a sequence to express conditional or repetitive behaviour. alt models alternatives (if/else — only the true operand executes). opt models an optional single path (if without else). loop models repetition (executes while guard is true). par models concurrent execution (operands run simultaneously). break models an exception or early exit (if guard is true, the fragment runs and the enclosing interaction terminates). Use combined fragments instead of drawing a separate sequence diagram for each alternative path — keeping related scenarios together makes the full behaviour visible in one diagram.
- When should I use a sequence diagram instead of an activity diagram?
- Use a sequence diagram when the important dimension is which participant does what and in what order — inter-object or inter-service communication is the focus. Sequence diagrams are ideal for API contracts, authentication flows, and event-driven architectures. Use an activity diagram when the focus is on the flow of control through a process, regardless of who does each step — activity diagrams model workflows and algorithm logic without emphasising participants. Rule of thumb: documenting how services talk to each other → sequence diagram; documenting the steps in a process → activity diagram.
- Is the generated sequence diagram editable, or is it a static image?
- Fully editable. flow-chart.io generates a typed scene graph, not a raster image. Every lifeline, activation bar, message arrow, and combined fragment is a named object you can double-click to rename, drag to reposition, or delete individually. You can add new participants, extend a loop fragment's guard condition, or reroute a message without starting over. Nothing is flattened to pixels until you explicitly export to PNG.
- What are best practices for drawing sequence diagrams?
- Seven key practices: (1) Keep diagrams scenario-focused — one diagram per use case or API endpoint. (2) Use alt fragments for conditional paths rather than separate diagrams. (3) Show only the messages that matter to the reader; omit internal implementation details. (4) Name lifelines consistently with your codebase. (5) Activate the activation bar for the full duration of synchronous calls. (6) Use asynchronous message arrows for event-driven and fire-and-forget interactions. (7) Label return messages with the return value or HTTP status code so the diagram doubles as an API contract.