Sequence diagrams

A sequence diagram shows the messages that pass between parts of a system during one interaction, in the order they happen. A message might be an HTTP request, a database query or the reply to either. Each part gets a vertical line, and time runs down each line. Each arrow is one message, and only the arrows order events on different lines.

A drawing of boxes and arrows can show that an API talks to a database and to an email provider. A sequence diagram shows which call comes first, which part sits waiting while another works, and what each side knows when a reply never comes back. You reach for one when that order is the question. You might be designing a request that crosses several services, working out why a page is slow, or deciding what should happen if a service never answers.

The cost is that the arrows draw one path through the interaction. Steps that happen only sometimes, repeat or fail need a frame around them or a diagram of their own, and a drawing that tries to hold every case soon gets too crowded to read. It also says nothing about how the system is built or how one record changes over many runs. Drawing systems and processes matches those questions to the diagrams that answer them.

Every example here follows one invented repair service. Mina books a dishwasher repair in her browser. A Repair API stores the booking in a PostgreSQL database, Repair DB. A notification worker, a separate process running in the background, later emails her through an external email provider. Up to the design readings near the end, each section changes one thing about that booking.

Lifelines and messages

Each part of the system in a sequence diagram is a participant, drawn as a named box at the top. A lifeline is the dashed line running down from that box. A message is an arrow from the sender’s lifeline to the receiver’s, labelled with what is asked or answered.

Read the four messages of Mina’s booking from top to bottom.

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    participant DB as Repair DB
    UI->>API: POST /repairs
    API->>DB: INSERT repair request
    DB-->>API: COMMIT ok
    API-->>UI: 201 Created: R17

The API can’t answer the browser until the database has answered the API. Reading down the page gives you that order without reading any code. Left to right carries no meaning. Put whoever starts the interaction on the left, so requests travel right and replies come back left.

Most figures keep their text form, in Mermaid, under Mermaid source, closed until you want to copy it. Figure 1’s source reads like this: each participant line declares a lifeline, as gives the name shown in its box, and the order of those lines sets the order from left to right. ->> draws a call and -->> its reply. Writing a diagram as text says more about the format.

Label each arrow with the operation and the data that matters, such as POST /repairs or 201 Created: R17. A label like “data” or “response” hides whether the database is being asked to read, write or confirm something.

A lifeline stands for a role, not a machine. “Repair API” means whichever copy of the API handles the request, and one lifeline is enough while the story doesn’t depend on which copy that is.

When it does, give each copy its own lifeline. Two workers that claim the same job, or two API instances that both accept a cancellation, need a lifeline each, or the race has nowhere to appear.

Replies and activation bars

Calls are the solid arrows in the booking: the sender asks, then waits for the answer. The dotted arrows are the replies. Between sending a call and getting its reply, the caller does nothing else for that request. An activation bar is a narrow bar on a lifeline that shows when that participant is handling a call.

The next animation adds activation bars to the booking, plus a hatched bar for waiting. The hatched bar is this article’s addition, not standard notation. It darkens the longer the wait goes on. The word under each name says what that participant is doing. Watch the browser’s bar while the database works. Then set the database to 3 s and watch again.

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    participant DB as Repair DB
    UI->>+API: POST /repairs
    API->>+DB: INSERT repair request
    DB-->>-API: COMMIT ok
    API-->>-UI: 201 Created: R17

The browser waits for the whole chain. With a 3-second database write it waits a little over 3 seconds, and the API waits almost as long inside it. The API’s wait is nested inside the browser’s, so each extra second in the database is an extra second for Mina.

The diagram didn’t get taller. Vertical distance shows order, not elapsed time, so a 5 ms write and a 3-second write draw the same picture. When the question is how long something took, write the times in a note, a box of text attached to a lifeline, or draw a timeline.

UML, the standard notation these diagrams come from, calls an activation bar an execution specification. Mermaid and PlantUML draw one kind of bar wherever you ask for it, so they can’t tell working from waiting.

Not every diagram needs the bars or every reply. Draw a reply when it carries data or a decision, such as 201 Created: R17 or a 422. A bare “OK” that only closes the call can go, as long as nothing in the design hangs on that reply failing to arrive. Draw activation bars when who is blocked is the question, as in this section, and leave them off when it isn’t. Most diagrams later in this article leave them off.

Synchronous and asynchronous messages

Every call so far has been a synchronous message: the sender waits for the reply. UML draws it with a filled arrowhead. An asynchronous message is one the sender doesn’t wait for. It has an open arrowhead, and the sender carries straight on.

The two words describe the sender, not the protocol. A browser’s await fetch(...) is a synchronous message in a diagram, because the code stops until the reply comes, even though JavaScript calls the style asynchronous. An HTTP request whose response nobody reads is an asynchronous message, even though HTTP is a request and response protocol. Label each arrow by what its sender does next.

Suppose the API also sends Mina’s confirmation email before it answers her. The email provider takes 2.5 seconds to reply, an invented figure. Watch the API wait for the provider first. Then switch the API to Doesn’t wait and see when the browser gets its 201 Created.

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    participant Provider as Email provider
    UI->>API: POST /repairs
    API-)Provider: POST /emails
    API-->>UI: 201 Created: R17
    Provider-->>API: 202 Accepted
    Note over API: Nobody is waiting for this reply

When the API waits, Mina waits too, for more than 2.5 seconds. If the provider were down, her booking would hang or fail, even though the database had already stored it.

When the API doesn’t wait, the browser gets its 201 Created in about 70 ms. The provider’s 202 Accepted comes back 2.5 seconds later to an API that has moved on. Nothing is waiting for it. Had that reply been an error, nothing would have handled it. The email would never have been sent, and nobody would know.

Neither version suits a booking. The first makes Mina wait for an email. The second ignores any error the provider sends back. The repair service moves the email out of the request instead.

Background workers and the transactional outbox

The API now records the email as work to do instead of sending it. It writes notification job J9 to Repair DB in the same transaction as the booking. A separate process, the notification worker, picks the job up later and calls the provider.

The animation adds the worker and the provider as two more lifelines. Watch when the browser gets R17 compared with when the email goes out.

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    participant DB as Repair DB
    participant Worker as Notification worker
    participant Provider as Email provider
    UI->>API: POST /repairs
    API->>DB: INSERT request + job J9
    DB-->>API: COMMIT ok
    API-->>UI: 201 Created: R17
    Note over Worker: Next poll, 0.7 s later
    Worker->>DB: Claim a job for 5 min
    DB-->>Worker: Job J9
    Worker->>Provider: POST /emails
    Provider-->>Worker: 202 Accepted
    Worker->>DB: Mark J9 sent
    DB-->>Worker: OK

The browser has R17 after about 70 ms. The worker claims J9 on its next poll, 0.7 seconds later, and the email goes out after that.

To claim J9, the worker marks it as taken for five minutes. Any lock the database holds on the job ends when the claim commits, long before the email goes out, so this lease is what keeps other workers off J9 while this one works. If the worker dies, the lease runs out and J9 comes free again.

The table that holds J9 is a transactional outbox: a table where a service writes the work it wants done, in the same database transaction as the change that caused it. The booking and the job are committed together, or neither is. So there’s never a booking without its email job, or an email job for a booking that failed.

The notification worker is a background worker: it runs outside any request, so nobody waits for it. It polls, asking the database for the next job about once a second, and the database never calls it.

Moving the email out of the request doesn’t remove its failures. It moves them to the worker, where nobody is waiting to notice. A provider that is down, a reply that never comes and a worker that crashes after the email went out each need a drawing of their own. The companion article, Failure, asynchrony and races in sequence diagrams, draws them.

Actors, notes, boxes and short-lived participants

An actor is a participant that is a person. UML and Mermaid draw it as a stick figure. Use one when the interaction starts with someone’s action, such as Mina submitting the booking form.

A self-message is an arrow from a lifeline back to itself. It shows a step a participant takes on its own, such as the API checking a postcode. Draw one only when the reader needs that step.

A note holds anything that isn’t a message: a timeout, a wait, an assumption. Mermaid places a note over one participant or across two, or to the left of or right of one.

Some participants exist for only part of an interaction. Mermaid writes create participant on the line before the message that creates one, and destroy on the line before the message that ends it. Only a message’s receiver can be created. Either end of a message can be destroyed, which is why the listing destroys the quote renderer on the line before its reply, the last message it sends.

sequenceDiagram
    actor Mina
    participant UI as Browser
    participant API as Repair API
    Mina->>UI: Submit the booking form
    UI->>API: POST /repairs
    API->>API: Check postcode
    create participant Quote as Quote renderer
    API->>Quote: Render quote for R17
    destroy Quote
    Quote-->>API: quote.pdf
    API-->>UI: 201 Created: R17
    Note right of API: The renderer exists only for this request

A participant can also carry a symbol that says what it is. PlantUML has keywords for database, queue, boundary, control, entity and collections, and Mermaid 11.11 and later sets them with participant Q@{ "type" : "queue" }. A symbol only helps the reader recognise the participant. Like the queue shape in the whiteboard shape vocabulary, it says nothing about how a queue delivers.

A box groups participants: by service, by owner, or by which side of a trust boundary they sit on. Mermaid writes box LightBlue Our systems before the participants and end after them. PlantUML writes box "Our systems" #LightBlue and end box. A boundary can mean ownership, execution location or trust, so write which one you mean, as the layout article advises for any boundary. Trust boundaries reads a design with boxes drawn this way.

Flows with no caller

Some flows start with no caller in the diagram. The worker’s poll starts with a timer, and a bounce report arrives from another company’s system. Three drawings fit, depending on how much the trigger matters.

When the trigger is incidental, as the worker’s poll timer is, put a note on the lifeline, such as “Poll timer fires”, and start from there. In Mermaid, activate after the note starts the worker’s bar without a message.

When the trigger comes from outside what you are drawing and its sender doesn’t matter, draw a found message: one that arrives from a sender the diagram doesn’t show. UML starts its arrow from a filled circle, and PlantUML writes [-> Worker : Poll timer fires. Mermaid has no form for it, so use a note or a participant that stands for the outside world.

When the timer’s own behaviour is part of the question, because it can be cancelled, rescheduled or fire late, give the clock a lifeline of its own, a scheduler. Its messages are then ordinary arrows that can be drawn, counted and lost like any other.

How much to draw

Each diagram should answer one question. “What does Mina wait for?” and “What happens to the email when the provider is down?” are two questions. They share the API and the database, and little else. A diagram that tries to answer both ends up too crowded to answer either.

Choosing what to draw

Choose the question first, then draw only the lifelines and messages that change its answer. A gateway that forwards every request unchanged, a token check that always passes, logging, a cache that only saves time and a client library’s internal retries can all stay off the page. A question about gateway timeouts needs the gateway.

A message broker between two services is the same choice. Give the queue a lifeline when its acknowledgement, its keeping of messages or its redelivery affects the answer. Otherwise draw one asynchronous arrow from sender to consumer and name the queue in its label, such as Send J9 (email queue). Don’t draw both for the same hop, or the reader will count two messages.

Keep to one level of detail. Lifelines can be services, or they can be objects inside one service, but a diagram that mixes the two says little about either. Take the participants’ names from the architecture diagram at that level, so the two views can be read together. A diagram with a lifeline per class goes stale fastest, because every refactor changes it. Generate it from the code or don’t draw it. C4, a set of zoom levels for architecture diagrams, makes the same point about its code level, as the architecture article explains.

Draw the happy path first, the run where everything works, then one diagram for each failure that matters. The alternative is one diagram with an alt frame, a box whose sections hold alternative paths, around every failure. Combined fragments explains frames. The companion takes the first approach: each failure has its own figure.

Sketch in the order the reader will read. Place the participants first, from whoever starts the interaction on the left. Then draw the main path, with every reply that carries something. Add the frames and notes for variations last. The companion’s failure walk then tests the finished happy path.

Figure 5 shows the same facts twice. Start with Everything in one, then switch to the two focused diagrams.

The single diagram has seven lifelines, an alt frame for a bad token and thirteen messages on the valid path. It holds two jobs with different timing, a request and a worker’s poll, so neither stands out. Each focused diagram fits a phone screen and answers its own question. A ref frame, which stands for another diagram, joins them. The gateway and the auth service dropped out because neither question depends on them.

Lifeline order, labels and numbering

Order the lifelines so that most arrows travel between neighbours. An arrow that skips over lifelines crosses their activation bars and is hard to follow. External systems usually go on the right, as the email provider does in the outbox diagram.

Keep labels short. In Mermaid a long label widens the whole diagram, and <br/> breaks a label or a note over two lines.

Number the steps when the diagram will be discussed: autonumber puts a number on every arrow, so a reviewer can say “step 7 has no timeout”. Add notes sparingly: a note on every arrow turns the diagram into prose. rect rgb(240, 240, 240) shades a region, such as one transaction, but never let colour carry meaning alone. The layout article covers the general principles for labels, colour and splitting that dense drawings share.

Ordering and gaps

Reading down a lifeline gives a firm order. So does each message: it is sent before it is received. Those two rules are all a sequence diagram promises. Two events on different lifelines that no chain of messages connects have no order between them, even though one is drawn higher on the page.

Take the outbox diagram. The API sends 201 Created after the commit, and the worker claims J9 after the commit too, but nothing links the two. Figure 6 redraws the start of Figure 4 with one change: the worker polls just after the commit instead of 0.7 seconds later. Watch when the browser gets R17. Then switch the poll back to 0.7 s later and watch which rows move.

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    participant DB as Repair DB
    participant Worker as Notification worker
    participant Provider as Email provider
    UI->>API: POST /repairs
    API->>DB: INSERT request + job J9
    DB-->>API: COMMIT ok
    Note over Worker: Polls just after the commit
    Worker->>DB: Claim a job for 5 min
    DB-->>Worker: Job J9
    API-->>UI: 201 Created: R17
    Worker->>Provider: POST /emails

With the early poll, the worker claims J9 before the browser has R17, and it could send the email before then too. Switching the poll moves only two things, the 201 and the worker’s poll, which trade rows. Every lifeline reads the same from top to bottom in both drawings, and every message is still sent before it is received.

The real timing differs between the two settings, but a sequence diagram doesn’t record timing, so the two drawings describe the same interaction. Figure 4 drew the 201 first, but nothing in the diagram promises that order. Here the order doesn’t matter, because R17 is stored from the commit onward: if the email reaches Mina before her browser shows R17, the booking it confirms already exists.

When a design does depend on one of these orders, the diagram needs a message that makes it so, or a note that admits nothing guarantees it. This is also why par exists: it says openly that the order between its sections is open. The rule is the one Leslie Lamport used for his space-time diagrams of distributed systems in 1978: one event comes before another only if the two are in order on one lifeline or a chain of messages leads from the first to the second.

As Figure 2 showed, a diagram has no scale, so a gap of two days looks the same as a gap of two milliseconds. Mark a long gap in words, such as a note across every lifeline: “Two days later”. Write deadlines and durations in notes too, such as “reply within 2 s”, rather than in UML’s formal duration constraints, which few readers know. When time in transit is itself the point, some tools can slant an arrow so that its arrival sits visibly lower than its sending.

Messages can also overtake each other: two sent in one order and delivered in the other. The companion’s Races and overtaking draws it.

Combined fragments

Some messages happen only sometimes, some repeat, and some run side by side. A combined fragment is a frame drawn around those messages that says which.

alt and opt

The first two kinds of frame choose which messages run. In the next animation the API checks Mina’s details before it stores anything, and a frame around the rest of the booking holds what happens in each case. Watch which part of the frame runs. Then set Details to Invalid.

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    participant DB as Repair DB
    UI->>API: POST /repairs
    alt details valid
        Note over API,DB: One transaction, ending at COMMIT
        opt new customer
            API->>DB: INSERT customer
            DB-->>API: OK
        end
        API->>DB: INSERT repair request
        DB-->>API: COMMIT ok
        API-->>UI: 201 Created: R17
    else details invalid
        API-->>UI: 422: postcode missing
    end

The tag in the frame’s top-left corner, alt, is the operator, which names the kind of frame. An alt frame holds alternatives. The dashed line divides it into sections, and the condition in square brackets at the top of each, such as [details valid], is that section’s guard. It says when the section runs.

At most one section of an alt runs, one whose guard is true. A guard of [else] is true when no other guard is. The section that doesn’t run stays on the page, faded here, because the frame describes both paths.

The valid section holds a smaller frame, an opt fragment. It has one section, which runs only if its guard is true. Here the guard is [new customer], and Mina is a returning customer, so the API skips the fragment and inserts only the repair request. Set Customer to New, and the API inserts a customer record first, in the same transaction as the request.

Write guards that the participant making the choice can check. The API can check “details valid” when the request arrives. It can’t check “email will arrive”, because nothing in the interaction has told it that yet.

loop

A loop fragment repeats the messages inside it while its guard holds. The diagram draws them once.

After booking, Mina’s page asks for the repair’s status every 2 seconds until a technician is scheduled. Watch the pass counter in the frame’s corner.

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    participant DB as Repair DB
    loop status not scheduled
        UI->>API: GET /repairs/R17
        API->>DB: SELECT status
        DB-->>API: status
        API-->>UI: 200: status
        Note over UI: Wait 2 s
    end

The same five steps run on every pass, and each pass adds about 2 seconds to the clock. The last wait is wasted. The page already has its answer, but the loop waits before it checks the guard again.

Now set Never. The guard never becomes false, and nothing in the frame sets a limit, so the page asks forever. Real code needs a cap, such as 30 attempts. A cap in the guard stops the endless loop, and a break stops the wasted wait. UML can write the cap in the tag, loop(1, 30) for at least once and at most 30 times. Mermaid has no bound syntax, so put the cap in the label.

Not every repetition needs a frame. The outbox diagram draws one pass of the worker’s poll. The polling repeats, but that is the worker’s business and not part of the booking, so a note such as “Polls about once a second” says it without a loop frame. Draw a loop when the repetition is part of the question, as Mina’s status checks are here.

par

A par fragment holds sections that run independently. Messages from different sections can interleave in any order. Within one section, the order still holds.

Once Mina has R17, the page loads the repair’s status and the free appointment slots together. Watch both requests leave before either reply returns. Then change which reply comes back first.

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    par repair status
        UI->>API: GET /repairs/R17
        API-->>UI: 200: received
    and free slots
        UI->>API: GET /slots?repair=R17
        API-->>UI: 200: three slots
    end
    Note over UI: Show the page once both replies are in

Either order is allowed, and one diagram covers both. par says only that neither section waits for the other. If one request needs the other’s reply, they aren’t parallel. Draw them in order.

Now set Status never arrives. The slots come back, but the status section never finishes. If the page shows nothing until both replies are in, Mina waits forever. Say in a note after the frame that the page needs both replies, as the figure does when both arrive, and give each request its own timeout.

break

A break fragment runs its messages in place of the rest of the enclosing fragment. Inside a loop, it leaves the loop. The polling loop can stop as soon as the status is scheduled, and the cap moves into the loop’s guard:

sequenceDiagram
    participant UI as Browser
    participant API as Repair API
    loop up to 30 times
        UI->>API: GET /repairs/R17
        API-->>UI: 200: status
        break status is scheduled
            Note over UI: Show the appointment
        end
        Note over UI: Wait 2 s
    end

Now the loop ends at the first reply that says scheduled, without waiting another 2 seconds, and it never runs more than 30 times. Outside a loop, break is a common way to draw a failure path that ends the interaction early.

critical

A critical fragment marks a region that other messages can’t interleave with. In UML, no other event on the lifelines it covers can fall between its first and last message. Service diagrams rarely need it, because few services handle one message at a time.

It is also the most misread operator. Engineers often draw it around a database transaction, but a transaction is about isolation and commit, and the fragment promises neither. Where you mean a transaction, a note says it more plainly, as the alt example did with “One transaction, ending at COMMIT”. Mermaid’s documentation gives critical a second reading, something that must happen, with option sections for when it fails. When you meet a critical frame with options, ask which reading its author meant.

ref

A ref fragment, which UML calls an interaction use, stands in for another sequence diagram. It is a frame tagged ref with the other diagram’s name inside, and it is the main way to split a diagram that has grown too big. The outbox diagram has two starting points, the browser’s request and the worker’s poll. Split it at the database, and the worker’s diagram can start with a ref to the booking, as Figure 5’s Email only does. Mermaid has no ref, so use a note across the lifelines instead:

sequenceDiagram
    participant DB as Repair DB
    participant Worker as Notification worker
    participant Provider as Email provider
    Note over DB,Worker: ref: Mina books a repair (writes job J9)
    Worker->>DB: Claim a job for 5 min
    DB-->>Worker: Job J9
    Worker->>Provider: POST /emails
    Provider-->>Worker: 202 Accepted

Rare operators and deep nesting

UML defines more operators than these: seq, strict, neg, assert, ignore and consider. They matter mostly in formal specifications. You may meet neg in a review, where it marks a sequence that must never happen.

Fragments also nest, and a few levels in they stop helping. When alt branches each hold a screenful of messages, or a loop sits inside a par inside an alt, the diagram holds several scenarios. Split it, as How much to draw describes. When the alts keep multiplying because one record can be in many conditions, the question has become which events each condition allows, and a state diagram answers it in one drawing.

Reading a design from its diagram

A sequence diagram is something you review: your own before you share it, someone else’s before you build from it. Four readings come up again and again, and each shows faster in the drawing than in the code. They leave the booking for a real protocol or another flow wherever that shows the shape better. The failure questions, which walk each arrow and ask what happens if it is lost, late or doubled, are gathered in the companion’s failure walk.

Round trips

A round trip is a message and the reply its sender waits for. Each one on the way to a result costs at least the network delay there and back, however fast the work at either end. Count the round trips before the result, and you have a floor on its latency that no server tuning removes.

Protocol specifications draw these ladders themselves. Figure 10 is the start of a TLS connection, the encryption under HTTPS, drawn after the ladders in the TLS 1.2 and TLS 1.3 specifications, with each one-way trip taking 25 ms. Play TLS 1.2, then switch to TLS 1.3 and compare the clock when the request leaves.

A full TLS 1.2 handshake needs two round trips before the browser can send its request, 100 ms here. TLS 1.3 needs one. The browser guesses which key exchange the server will accept and sends its share in the first message, so the server can finish its side in one reply. The request then travels with the browser’s Finished. The TCP connection underneath adds one more round trip before either. Resumed sessions, and TLS 1.2 with the False Start extension, can send sooner. The figure counts a first, full connection.

The labels follow the legend in RFC 8446, the TLS 1.3 specification. A + marks an extension carried in the message before it, and * a message that isn’t always sent. Braces mark messages encrypted with handshake keys, and square brackets messages encrypted with application keys. Every specification defines its own marks, so read a ladder’s legend before its arrows.

The same count works inside your own system. In Figure 2 the browser waited for the API, which waited for the database. That is a chain of round trips, each nested in the one above, and each adds its delay to Mina’s wait.

Fork and stair

A drawing also shows who holds the flow. Figure 11 draws a booking that needs a time slot, a part and a deposit, in two shapes. Start with Central, then switch to Delegated.

With central control, one lifeline sends every request and hears every reply, and the arrows fan out from it like a fork. With delegated control, each service does its part and hands the rest on, and the arrows step down and back like a stair. The IBM Rational Unified Process guidelines, which describe the two shapes, suggest the fork when the steps may change order or new steps are likely, because one place holds the order. The stair suits steps that are tightly bound and always run in the same order.

The stair has a cost the activation bars make visible. Every caller waits for everything below it, so Scheduling is held up by Billing, and a slow deposit holds three services. A failure at the bottom has to travel back up through every caller. When the steps talk through events rather than calls, the same two shapes are called orchestration and choreography, and the companion’s Failing part-way draws one.

Chatty calls

An interface is chatty when one result takes many small calls across the network, and a diagram shows two shapes of it. Figure 12 draws the first, a page that lists today’s repairs. The API reads them from the database, then needs each repair’s customer from another service. Play the default, then switch to one batched call.

A loop around a remote call on the request path is the shape to look for. The diagram draws the call once, so the loop’s guard is the only sign of how many times it runs. Here ten calls of 20 ms each, one after another, add 200 ms that one batched call cuts to 20. Inside a data layer the same shape is called the N+1 query problem, one query for the list and one per row, which The database work behind an application request follows through an ORM.

The second shape is a lifeline that every message passes through, such as a gateway or a central service that relays each call. It shows as a column with an arrow on almost every row. Every request then waits on it, and when it fails, it fails for everyone. That may be the right design, but the diagram should make it a visible decision rather than one the reader has to discover.

Trust boundaries

When boxes mark trust boundaries, the diagram answers which messages cross them. Figure 13 is Mina signing in to the repair app through a sign-in provider, using OpenID Connect, which runs on OAuth 2.0’s authorization code flow. Each party’s systems sit in a box of their own.

Follow what crosses into Mina’s device. The code returns to the app by way of her browser, in a redirect, so it can turn up in browser history, logs and anything else that sees the URL. The tokens travel straight from the provider to the app server and never enter her device. That is why the specification requires the code to expire shortly after it is issued, recommending ten minutes at most, and to be used only once.

The app server proves who it is with its client secret, but the secret says which app is asking, not which browser started the sign-in. So the current security guidance, RFC 9700, also ties the code to that browser with PKCE. The first redirect carries a code_challenge, a hash of a random value the app server keeps for this sign-in, and the token request must send the matching code_verifier. A code copied from a URL is useless without it.

Review a design this way by asking, for each arrow that crosses a box, what it carries and who could read or replay it. A diagram without boxes can’t answer the question at all.

Other dialects

You will read more of other people’s diagrams than you draw, and many don’t follow UML. A few dialects are common.

• Numbered collaboration diagrams lay the participants out like an architecture diagram and number the arrows to give the order. C4’s dynamic diagrams allow either this style or a sequence diagram and say the two show the same information. Read the numbers as the rows of a sequence diagram.
• Informal boxes and arrows in design documents often give arrowheads and dashes no fixed meaning. Take the meaning from the labels or a legend, and ask when neither says.
• Protocol ladders in RFCs have two or three vertical lines, arrows that may slant to show transit, and a legend of marks, like the one under Round trips.
• Swimlanes is what some diagramming tools call lifelines. In process maps a swimlane is a lane of responsibility, as Processes and swimlanes explains, so check which one a drawing means.

Text tools differ in a few marks too. Mermaid’s documentation describes its arrows by their shape and calls only -) and its dotted form --) asynchronous. Reading ->> as a call is the UML convention this article uses. The table gives the common marks in UML, Mermaid and PlantUML.

The same characters mean different things in the two tools. Mermaid’s -> is a line with no arrowhead and its ->> a call, while PlantUML’s -> is a call and its ->> an asynchronous message. Check which tool a listing is written for before reading its arrows.

Writing a diagram as text

Written as text, a diagram can live next to the code and change in the same review. Mermaid is the most widely rendered text form: GitHub and GitLab draw it from a fenced block, and the key under Figure 1 shows how to read it. Every listing in this article, including those under Mermaid source, is complete Mermaid and parses on Mermaid 11.4.1 and 12.2.0.

Mermaid can’t draw a ref frame, a found message, a delay marker or a slanted arrow. PlantUML can, with the marks in the table above. Each tool’s documentation is the reference for the rest, and Keeping diagrams useful helps choose a tool and pin its version.

A sequence diagram goes stale when a call is added or removed, a timeout or retry policy changes, or work moves between synchronous and asynchronous. Renaming a function doesn’t. Keep the source next to the code that implements the flow. When a reviewer doubts the diagram, compare it with a trace of the real flow, as the companion’s Drawing what happened describes.

Sources and further reading

• Mermaid, Sequence diagrams: every arrow, block and option, with the release that added each recent feature.
• PlantUML, Sequence diagram: arrows, found and lost messages, ref, delays, slanted arrows, participant symbols and box.
• Object Management Group, Unified Modeling Language 2.5.1, chapter 17, Interactions: the formal definitions of lifelines, messages, execution specifications, combined fragments, critical regions, loop bounds, found messages and interaction uses.
• Leslie Lamport, Time, Clocks, and the Ordering of Events in a Distributed System (1978): the space-time diagrams behind the ordering rule, for readers who want its formal version.
• IETF, RFC 8446, section 2, and RFC 5246, section 7.3: the TLS 1.3 and TLS 1.2 handshake ladders with their legends.
• IETF, RFC 6749, section 4.1: the OAuth 2.0 authorization code flow, with the code’s lifetime and single use in 4.1.2.
• IETF, RFC 9700 (BCP 240), section 2.1.1: the OAuth 2.0 security best current practice, which asks for PKCE (RFC 7636) on the authorization code flow.
• OpenID Foundation, OpenID Connect Core 1.0, section 3.1: signing in with the authorization code flow and the ID token.
• IBM Rational Unified Process, Guidelines: Sequence Diagram (an archived copy): centralised and decentralised control, the fork and the stair, and when each fits.
• C4 model, Dynamic diagram: collaboration and sequence styles for the same scenario.
• Chris Richardson, Pattern: Transactional outbox.
• On this site: Failure, asynchrony and races in sequence diagrams, the companion, for timeouts, retries, brokers, callbacks, races and the failure walk.
• On this site: States and lifecycles, for how one repair request’s status changes over time, and Processes and swimlanes, for who does which work.
• On this site: Keeping diagrams useful, for choosing a tool, pinning its version and reviewing a drawing when the system changes, and Layout, labels and five colours, for labels, boundaries and colour.