Sequence Diagram Generator

Sequence diagrams: the UML view of when things happen

A sequence diagram is one of the thirteen UML diagram types and the one most engineers actually reach for in everyday work. Where a class diagram answers "what is in the system" and a state diagram answers "what can happen to one object", a sequence diagram answers "who talks to whom, in what order, and what comes back". The notation was unified between 1994 and 1997 by Grady Booch, James Rumbaugh, and Ivar Jacobson at Rational Software — the so-called "Three Amigos" — and standardised in UML 1.0 in 1997; the current version is UML 2.5.1, ratified by the OMG in 2017.

The diagram is read top-to-bottom (time flows down) and left-to-right (each participant has a vertical lifeline). Every interaction — every request, response, callback, retry — becomes a horizontal arrow between two lifelines, time-ordered automatically by its vertical position.

Anatomy of a sequence diagram

• Participants — boxes at the top representing systems, services, or roles. Drawn as a stick figure when the participant is a human actor.
• Lifelines — vertical dashed lines descending from each participant; they represent the existence of that object over time.
• Messages — horizontal arrows between lifelines. A solid line with a filled arrowhead is a synchronous call; a dashed line is a return; an open arrowhead is an asynchronous message.
• Activation bars — thin rectangles on the lifeline showing the period during which that participant is actively processing.
• Notes — rectangles with a folded corner used to annotate a region of the diagram.
• Combined fragments — boxes labelled loop, alt, opt, par, critical that wrap several messages and assign them control-flow semantics.

Mermaid sequenceDiagram syntax

Mermaid models sequence diagrams with a tiny line-based grammar:

sequenceDiagram
  actor User
  participant Browser
  participant AuthServer
  participant API

  User->>Browser: click Login
  Browser->>AuthServer: GET /authorize
  AuthServer-->>Browser: 302 login form
  User->>Browser: submit credentials
  Browser->>AuthServer: POST /token
  AuthServer-->>Browser: access_token
  Browser->>API: GET /me  (Bearer …)
  API-->>Browser: 200 user JSON
  Note over Browser,API: token cached for 1h

Arrow flavours: ->> solid synchronous, -->> dashed return, -) open async, -x lost message. Fragments wrap with loop / end, alt / else / end, opt / end, par / and / end.

When sequence diagrams pay for themselves

• Documenting a protocol — OAuth handshake, payment 3-D Secure, websocket upgrade, SAML round-trip.
• Debugging race conditions — drawing the actual order of events forces you to discover the missing happens-before edge.
• Onboarding a new engineer — one diagram of "what happens when a user clicks checkout" replaces an hour of voice explanation.
• Designing async flows — visualising queue producers, consumers, and acknowledgements before writing code.

Alternatives and companion diagrams

PlantUML offers richer fragment syntax and is the de facto standard in many Java shops. WebSequenceDiagrams popularised the text-to-image workflow before Mermaid existed. draw.io and Lucidchart cover the WYSIWYG audience. Within UML, the state diagram models what one object can do, the activity diagram models a workflow, and the communication (collaboration) diagram is an alternative view of the same interaction with spatial layout instead of temporal.

FAQ

Can I show the payload of a message? Yes — put it in a Note over A,B: { id: 42 } next to the arrow, or after a colon as A->>B: POST /users { name }. For long JSON, a side note is more readable.

Can a sequence diagram run left-to-right? No — UML sequence diagrams are always vertical (time flows downward). If you need a horizontal-looking interaction view, use a communication diagram instead.

My diagram has 25 participants and is unreadable. What do I do? Break it into multiple diagrams by use case (one per scenario) and link them in your docs. A single sequence diagram should fit one screen with eight or fewer lifelines.

How do I show parallel calls? Wrap them in a par fragment with branches separated by and.

Do sequence diagrams replace logs or traces? No — they are design artefacts. For runtime, distributed tracing tools (Jaeger, Honeycomb, OpenTelemetry) produce sequence-style views from real spans.