How is a sequence diagram different from a flowchart?

A flowchart describes the order of steps in a process and is indifferent to who participates. A sequence diagram describes message exchange between several objects in one interaction and focuses on who says what to whom. Use sequence diagrams for cross-module calls and interface design, and flowcharts for business process.

Should every call show a return arrow?

For synchronous calls, returns can be omitted when no ambiguity results, which keeps the diagram tidy. Asynchronous messages and any call where the returned value matters must show it, otherwise the data flow is unclear.

How detailed should a sequence diagram be?

Detailed enough that a reviewer can judge the implementation approach from it. External interfaces, database operations, and cache access deserve detail; trivial internal helper calls can be merged into one step.

How do I show parallel processing?

Wrap messages issued simultaneously in a parallel fragment, or draw several asynchronous arrows side by side. If the flow must wait for all of them, add a join annotation stating that.

How to Draw a Sequence Diagram: Participants, Messages and Lifelines

Once a task passes through three or four modules, a flowchart stops being enough — it can express order but not who sent what to whom. A sequence diagram fills exactly that gap: participants across the top, time running down, and every arrow an explicit call.

List participants before ordering anything

A participant is anything that actively sends or receives messages: a user, a browser page, a gateway, a business service, a database, a third-party API. The test for inclusion is whether it both receives and sends — passive data objects do not deserve their own column.

Order participants left to right by call flow, with callees to the right
Participants of the same kind may sit side by side, such as multiple downstream services
Use the real module names from the system, not vague labels like "backend"
Keep it to six or eight participants; beyond that, split the diagram

Draw synchronous, asynchronous and returns differently

A filled arrowhead means a synchronous call: the caller waits. An open arrowhead means an asynchronous message: the sender moves on without waiting. A dashed arrow is a return. Keeping these distinct is what makes the diagram truthful — in particular, who is blocking whom determines what actually drives response time.

Synchronous calls use solid arrows with filled heads; simple calls may omit the return
Asynchronous messages use open arrowheads and must show what happens next
Returns are dashed and state what comes back
Only draw activation bars where strict correspondence matters; they add clutter fast

Document failures, timeouts and retries

A sequence diagram showing only the happy path has little value in review, because in engineering the interesting behaviour is always the exception. Timeout values, retry counts, and the fallback route are the highest-value content on the page.

Annotate timing constraints such as "5s timeout" near the relevant arrow
Show retry count and backoff strategy, not just "retry on failure"
Draw the degradation path as its own chain with its trigger condition
Mark idempotency points so repeated calls cannot corrupt data

Use fragments for conditions and loops

When an interaction contains conditional execution, looping, or two alternative approaches, wrap the relevant messages in a labelled box — a fragment. It communicates structure far better than a paragraph of text beside the arrows.

Conditional branches go in an alt fragment with condition and outcome in separate sections
Optional execution goes in an opt fragment containing only the conditional messages
Loops go in a loop fragment with the condition in the title
Fragments may nest, but more than two levels means the diagram should be split

Layout and reading order

Sequence diagrams carry a lot of information, so layout has to keep vertical order and horizontal ownership simultaneously clear. Align the participant headers, run a dashed lifeline down the page, and order messages strictly by time — do those three and misreading becomes unlikely.

Lifelines in light dashed strokes so they do not compete visually
Keep back-and-forth messages between the same pair compact
Number important messages so reviews can proceed line by line
Caption the diagram with the scenario, such as "successful checkout, main path"

Frequently asked questions

How is a sequence diagram different from a flowchart?: A flowchart describes the order of steps in a process and is indifferent to who participates. A sequence diagram describes message exchange between several objects in one interaction and focuses on who says what to whom. Use sequence diagrams for cross-module calls and interface design, and flowcharts for business process.
Should every call show a return arrow?: For synchronous calls, returns can be omitted when no ambiguity results, which keeps the diagram tidy. Asynchronous messages and any call where the returned value matters must show it, otherwise the data flow is unclear.
How detailed should a sequence diagram be?: Detailed enough that a reviewer can judge the implementation approach from it. External interfaces, database operations, and cache access deserve detail; trivial internal helper calls can be merged into one step.
How do I show parallel processing?: Wrap messages issued simultaneously in a parallel fragment, or draw several asynchronous arrows side by side. If the flow must wait for all of them, add a join annotation stating that.