A sequence diagram from a user story, in order

A sequence diagram from a user story is a translation, and the translation has an order. Start with one story sentence, list the actors that sentence actually names, list the messages in the order they happen, and only then write the Mermaid. The picture is the last step. If you open with sequenceDiagram and invent a service the story never mentioned, you have drawn a design you wish you had, which is a different document.

I use this order because user stories are already about someone wanting something from someone else. That is a conversation. A flowchart would hide the speakers. The generic syntax lesson, arrows and participants and the rest, lives in the sequence diagram tutorial. Stay here until the story has been pulled apart. The diagram is what you build after the lists exist on the page.

Start from one sentence

Take a single story, the kind that fits in a ticket title plus one line. "As a signed-out user who forgot their password, I want a reset link by email so I can choose a new password and sign in." That sentence is enough. A paragraph of acceptance criteria can sit beside it, and you will raid that paragraph for branches, but the sentence picks the cast.

Write the sentence at the top of the file and leave it there. I have deleted the sentence after the diagram looked finished, then failed to explain a branch in review because the reason lived only in my head. The sentence is the spec the arrows have to satisfy. If a message does not serve that sentence, cut the message. If the sentence needs a message you cannot name, the story is incomplete and the diagram should wait.

Two stories on one diagram is how you get a chart nobody can narrate. Invite a teammate, reset a password, and charge a card are three conversations. Draw one. Link the others in the prose when the reader needs them. The examples of sequence diagrams are useful once you want to compare finished pictures. They are a bad place to start if you have not listed your own messages yet.

List the actors the story actually has

Read the sentence and underline the parties. In the password story I see the user, the product they are talking to, the email that has to arrive, and the account record that must change. I name them User, App, Mailer, and Account store. I do not add a queue, a fraud vendor, or an identity provider unless the story or the acceptance criteria mentioned them. Extra lifelines feel thorough. They are fiction until a ticket says otherwise.

Order the list left to right in the order the reader should meet them. The user is on the left because the story starts with them. The account store is on the right because it is the thing that gets written at the end. Mermaid keeps the order of your participant lines. If you let the first message invent the cast, a service you mention late jumps to the edge and the eye reads the story backwards. I still do this when I am rushing. The fix is boring: declare every participant before the first arrow.

Aliases keep the ids stable while the labels stay human. participant Store as Account store means the arrows say Store and the picture says "Account store." Renaming the label later does not force you to edit every message. Spaces in a bare participant name are how a line stops being a participant. Use the alias.

A story that says "the system" is hiding the cast. Split "the system" into the parts that send different messages, and stop splitting when two boxes would only ever talk to the same neighbor with the same words. I would rather have four lifelines I can point at in review than eight that exist because a template had eight.

List the messages before any arrow

Write a numbered list in the ticket, above the fence. Each line is who, to whom, and the shortest verb that is still true. For the password story the list is:

1. User asks App for a reset.
2. App asks Account store whether the account is there.
3. If it is, App asks Mailer to send the link, and Mailer delivers that link to the user.
4. User submits a new password to App.
5. App tells Account store to save it, and Account store confirms.
6. App tells the user they can sign in.
7. If the account is missing, App still shows the same notice, and it does not send mail.

That last line is the branch. Stories often hide the unhappy path inside "so I can sign in," as if the happy path were the whole requirement. Security people will ask what you do when the email matches nothing. Answer it in the list, or the diagram will grow the answer during a review you could have finished offline.

Keep the verbs short. "POST /password-resets with a 204 and a constant body" is a note under the diagram, or a line in the API doc. On the arrow, "Ask for a reset" is enough. Long messages push the lifelines apart until the picture is a scrollbar. I learned this by pasting a log line into an arrow and watching the preview become a single row of text with a tiny head.

Solid arrows for requests, dotted arrows for replies. Pick that habit once. When every arrow is solid, a reply looks like new work and the reviewer has to guess which line is the answer. The sequence diagram syntax page is the reference for those arrow forms. You need it when the list is done, not before.

Write the password reset

The list becomes the diagram with almost no new thinking. alt is the "if the account is there" line. else is the notice that leaks nothing. Each of those blocks ends with its own end. An opt covers the extra ask I would only add if the story included it: sign out other sessions after the password changes. I am including it here because acceptance criteria often sneak that in, and the diagram should show it as optional rather than as a step that always runs.

sequenceDiagram
  actor User
  participant App
  participant Mail as Mailer
  participant Store as Account store
  User->>App: Ask for a reset
  App->>Store: Look up the account
  alt Account exists
    Store-->>App: Found
    App->>Mail: Send the reset link
    Mail-->>User: Deliver the link
    User->>App: Submit a new password
    App->>Store: Save the password
    Store-->>App: Saved
    App-->>User: You can sign in
  else No matching account
    Store-->>App: Missing
    App-->>User: Show the same notice
  end
  opt Story also says sign out other sessions
    App->>Store: Drop other sessions
    Store-->>App: Dropped
  end

Read it against the sentence. The user asked for a link, the link arrives only inside the account-exists branch, the new password is saved, and the missing-account branch does not call Mailer. That last detail is the one a paragraph will smear. "We always respond the same way" can be misread as "we always send mail." The empty mail lane on the else branch is the correction.

The opt sits outside the alt on purpose. Signing out other sessions only makes sense after a real password change, so if your criteria say that, move the opt inside the first branch, above the final reply, and give it its own end before the branch's end. I have shipped the opt in the wrong place and then argued that the diagram "implied" the nesting. It did not. Nesting is the indentation plus the closers. Implication is how bugs get a legend.

If the story includes "let them request the link again," that is a loop, and it wants its own end too. I am leaving the resend off this picture so the branch stays readable. A retry loop is a whole topic of its own. Get the story's main conversation on the page first.

The same method on a refund story

Second sentence, so the method is not a one-off for passwords. "As a support agent, I want to refund an order under our limit so the customer is paid back without waiting for finance."

Actors: Agent, App, Ledger, Customer. Messages: the agent asks for the refund, the app reads the order, the amount is either under the limit or not. Under the limit, the app tells the ledger to refund and tells the customer. Over the limit, the app parks the request for finance and tells the agent. Nobody added a tax service, because the story did not.

sequenceDiagram
  actor Agent
  participant App
  participant Ledger
  participant Customer
  Agent->>App: Request a refund
  App->>Ledger: Read the order total
  Ledger-->>App: Total
  alt Under the limit
    App->>Ledger: Refund the order
    Ledger-->>App: Refunded
    App-->>Customer: Confirm the refund
    App-->>Agent: Done
  else Over the limit
    App->>Ledger: Park for finance
    Ledger-->>App: Parked
    App-->>Agent: Waiting on finance
  end

The customer appears only on the under-limit path. That is what the story said: the customer is paid back without waiting. The over-limit path talks to the agent, not to a made-up approval service. If finance is a person who must click, add them as a participant when a second story describes that click. Do not sneak them onto this chart because the lane looked empty.

I put both replies to the agent and the customer as separate arrows. Combining them into "notify everyone" is how the customer starts receiving the finance-wait message. Separate arrows are slightly more typing. They are also the difference between a policy and a shrug.

What you still have to decide

The story will not choose your error text, your token lifetime, or your rate limit. Those belong in the paragraph under the fence. The diagram's job is the order and the branch. I write one sentence under the password chart: the notice for a missing account uses the same words as the notice for a real one. That sentence is the control. The arrows only show that mail stays quiet.

Acceptance criteria that contradict the sentence need a human, not a cleverer diagram. "Always email so we do not leak accounts" and "never email when the account is missing" cannot both be arrows. I stop drawing and put the contradiction in the ticket. A diagram that picks a side silently is how the loser of the argument discovers the decision in production.

Protocols are the same method with a stiffer cast. The OAuth sequence template is a user story that the industry already wrote: the user wants to sign in, the client wants a token, the authorization server wants consent. Read it as lists of actors and messages, then look at the picture. Copying it into a password-reset ticket will not help. The cast is different. The habit of listing messages first is the part worth copying.

Use cases are adjacent and easy to confuse with this work. A use case names the goal. A sequence shows the messages that reach the goal. The use case diagram examples are the goal layer. Come back to the message list when someone asks "then what calls what?"

Ways this draft goes wrong

The first failure is a participant named for a team, "Backend," that performs every step. You have drawn one person talking to a blob. Split the blob at the boundary where a message could fail independently. Mail can fail while the account store is fine. Those are different lanes, and the story already separated them when it said "by email."

The second failure is an else with no alt open, or an alt that never closes. The preview stops at that line and the rest of the story vanishes. Each block takes its own end. I count the openers and the closers before I trust a render. Indentation is for me. The closers are for the parser.

The third failure is teaching the tool inside the message text. "App->>Store: lookup (this is a SELECT)" helps nobody in a design review and risks a label the renderer has to guess at. Keep parentheses out of the arrow text unless you quote a label that truly needs them. Put the SQL in the doc, or in a link to the query, if the query is the point.

The fourth failure is letting a generator add color and a cache. Pasting the story sentence into the AI sequence generator is a fair way to get a first legal file. Free accounts get 5 AI uses in total, and the same panel can edit or fix a diagram you already have. Read the result against your actor list. Delete every lifeline the story did not name. I treat the generated chart as a draft of syntax, and the numbered list as the source of truth. When they disagree, the list wins.

The free sequence diagram maker notes are about the tool around the text. The sequence alt patterns go deeper on branches than this page should. If your story is mostly "if this, else that," read that next, after your message list exists. A catalogue of branch shapes will not extract actors from a sentence. You still have to do that part.

Check the story by reading the lanes

Narrate the diagram from the left without looking at the list. If you stumble, a message is out of order or a reply is drawn as a new request. I do this out loud. It feels odd in an office and it catches the arrow I reversed while renaming a participant.

Then narrate only the else branch. People check the happy path, declare victory, and leave the else as two lines they never said aloud. The password chart's else branch is the product decision a security review will quote. If you cannot say it in one breath, the branch is doing too much and wants its own story.

Questions that start with "what if they click twice" are new stories. Add them when the ticket asks, as an opt or a second diagram. Stuffing every what-if into the first chart is how a reset flow becomes unreadable and still misses the case that matters. One story, one conversation, a list you can diff.

Open the editor and paste the password chart, or paste your own sentence into a blank sequence and apply the same lists. The editor does not require an account, and the preview updates while you fix a missing end. When the lanes match the sentence, put the fence in the ticket under the story text. The sentence stays. The picture is how the next reader checks that you meant it.