Sequence Diagram Example: Mapping a Login Flow

A login button looks simple. You tap it, you're in. But behind that tap, four different things are talking to each other in a strict order: your phone, the app's server, an auth service, and a database. Get that order wrong in your code and you ship a bug. Get it wrong in a meeting and three engineers spend twenty minutes talking past each other.

A sequence diagram fixes the second problem. It's the diagram that shows who talks to whom, in what order, over time. Below is a real worked example — a user logging in — plus the handful of rules you actually need to read and draw one.

What a sequence diagram actually shows

A flowchart answers "what happens next?" A swimlane diagram answers "who owns which step?" A sequence diagram answers a narrower, more technical question: what messages get passed between participants, and in what order?

That word participants is the whole idea. Each participant — a person, an app, a service, a database — gets a box at the top and a dashed vertical line dropping down from it. That line is called a lifeline, and it represents time flowing downward. Earlier messages sit near the top; later ones sit lower. There's no "go back up" — time only moves one way.

So a sequence diagram has two axes with fixed meanings:

• Left to right = the participants (who's involved)
• Top to bottom = time (what happens first, second, third)

Once you internalize those two axes, the rest is just arrows.

A worked sequence diagram example: user login

Let's map a standard email-and-password login. Four participants, left to right:

User → Web App → Auth Service → Database

Here's the sequence, message by message, top to bottom:

1. User → Web App: submit(email, password) — the user fills the form and hits Login.
2. Web App → Auth Service: verify(email, password) — the app hands the credentials to the service that knows how to check them.
3. Auth Service → Database: findUser(email) — the service asks the database for the matching account.
4. Database → Auth Service: return userRecord — the database answers with the stored record (including the hashed password).
5. Auth Service → Auth Service: comparePasswordHash() — a self-message: the service calls a function on itself, no other participant involved.
6. Auth Service → Web App: return token — credentials check out, so it returns a session token.
7. Web App → User: showDashboard() — the app renders the logged-in screen.

Read it like a script for a play. Each line is one character speaking to another, in order. If you handed this to a new engineer, they'd understand the login flow in thirty seconds — no code, no guessing.

The five symbols you need

You don't need the full UML spec. Five things cover ~90% of real diagrams:

• Lifeline — the dashed line under each participant. Time runs down it.
• Solid arrow (→) — a message or call from one participant to another. Label it with the action: verify(email, password).
• Dashed arrow (⇠) — a return: the reply travelling back. In the example, the token and userRecord arrows are returns. Many diagrams skip these for obvious replies to cut clutter — that's allowed.
• Activation bar — the thin rectangle drawn on a lifeline while that participant is busy handling a call. It shows how long something is "active." The Auth Service's bar stays open from step 2 all the way to step 6, because it's orchestrating everything in between.
• Self-message — an arrow that loops from a participant back to itself, like comparePasswordHash(). Use it for internal work that's worth naming.

Handling the "what if it's wrong?" case

Real flows have branches. What if the password doesn't match? You don't draw a second whole diagram — you use a combined fragment, a labelled box around the messages it affects.

The common ones:

• alt — alternatives, i.e. an if/else. Draw one box split by a dashed line: the top half is "password valid → return token," the bottom half is "invalid → return 401 error." Both paths live in one frame.
• opt — an optional block that only runs if a condition holds (e.g. "if 'remember me' is checked, store a long-lived cookie").
• loop — a repeated block (e.g. "for each item in cart, check stock").

For our login, wrapping steps 5–7 in an alt frame turns a happy-path sketch into a diagram that documents the failure case too. That's usually the version worth keeping.

Three mistakes that make sequence diagrams unreadable

I've watched good diagrams collapse under these:

1. Too many participants. If you have nine boxes across the top, the arrows turn into spaghetti. Group related services or split into two diagrams — one per scenario. Five or six participants is a comfortable ceiling.
2. Vague arrow labels. data tells the reader nothing. findUser(email) tells them the call and its argument. Label arrows like function calls, not like nouns.
3. Mixing time and logic. A sequence diagram is not a flowchart. If you find yourself wanting decision diamonds and "go back to step 2" loops, you either want a flowchart instead, or you need an alt/loop fragment. Don't bend one diagram type to do the other's job.

When to reach for a sequence diagram (and when not to)

Reach for one when order and interaction are the hard part: API request/response flows, authentication, payment handshakes, message queues, microservices calling each other, or onboarding a teammate to "how does checkout actually work?" Anything where the bug hides in who calls whom, when.

Skip it when there's only one actor doing a linear list of steps — a plain flowchart or numbered list is clearer and cheaper. The sequence diagram earns its keep precisely when multiple participants are involved.

Draw the login example in seconds

You don't have to place every lifeline and arrow by hand. Describe the flow in plain English — "user logs in: app verifies credentials with an auth service, which checks the database, then returns a token" — and Ridvay turns it into a proper sequence diagram with lifelines, messages, and returns laid out for you. Then you drag, relabel, or add an alt block to fit your real system.

Start from the exact example in this post and edit from there:

Generate this login sequence diagram in Ridvay →

Map the order once, and the next person to touch that code won't have to guess it.