A user types an email and password and presses Log in. Four parts of the system take turns: the browser, the web application, a separate authentication service and the user database. This page shows that conversation as a UML sequence diagram, with the happy path and the failed-login path side by side in one alt fragment.
Read it top to bottom: time flows downward, and each arrow is one message.
1. The Diagram
The browser sends POST /login with the email and password over HTTPS. The web app becomes active (the tall bar on its lifeline).
The web app does not check passwords itself; it calls authenticate() on the auth service.
The auth service loads the user row by email and gets back the stored password hash.
It verifies the password against the hash with a slow hash such as Argon2id. This is a self call, so the arrow loops back to the same lifeline.
The alt box splits the story. Valid: the auth service returns a session token and the web app answers 302 with an HttpOnly, Secure session cookie.
Invalid: the auth service bumps failed_attempts, returns 401, and the web app shows one generic message. It never says whether the email or the password was wrong, so attackers cannot probe for accounts.
2. How to Read It
A solid line with a filled arrowhead is a synchronous call: the sender waits. A dashed line with an open arrowhead is the reply. Colours on this site are only emphasis: green for the success branch, red for the error branch; UML itself has no colours.
3. Variant: Login with MFA and Lockout
Adding multi-factor authentication turns one round trip into two. After the password check, the auth service replies mfa_required with a challenge id; the browser then posts the six-digit TOTP code. Only a valid code produces the session cookie. After five wrong codes the account is locked for 15 minutes (HTTP 423 Locked). The user DB is left out here to keep the diagram focused; leaving out detail that does not matter to the reader is normal and good practice.
4. Pros and Cons
Pros
Shows ordering exactly: who calls whom, and when.
Makes the error branch visible next to the happy path, so it gets reviewed.
Maps almost one-to-one to code and to API traces, so developers trust it.
Great for security reviews: you can see where the secret travels and where it is checked.
Easy to keep as text in Mermaid or PlantUML and diff in pull requests.
Cons
Gets wide and tall fast; more than about six lifelines or two nested fragments becomes hard to read.
Shows one scenario, not every possible path.
Says nothing about deployment, timeouts or retries unless you add notes.
Hand-drawn versions go stale as soon as the API changes.
5. When to Use It
Use it when
You are designing or reviewing an API call chain or protocol.
You need to explain an incident: what was called, in what order.
The order of steps matters for correctness or security (login, payment, OAuth).
Skip it when
You want the full lifecycle of one object: use a state machine.
You want the static structure of the code: use a class diagram.
The flow is a business process with people and many decisions: use an activity diagram.
6. As Diagrams-as-Code
The main diagram written for Mermaid:
sequenceDiagram
participant B as Browser
participant W as WebApp
participant A as AuthService
participant D as UserDB
B->>W: POST /login {email, password}
activate W
W->>A: authenticate(email, password)
A->>D: find user by email
D-->>A: user row (pw_hash)
A->>A: verify Argon2id hash
alt password valid
A-->>W: ok(userId, sessionToken)
W-->>B: 302 + Set-Cookie sid (HttpOnly)
else invalid password or unknown email
A->>D: increment failed_attempts
D-->>A: ok
A-->>W: 401 invalid credentials
W-->>B: 401 + generic error message
end
deactivate W
Paste it into any Markdown viewer that renders Mermaid (GitHub, GitLab, Obsidian). PlantUML uses almost the same arrows inside @startuml ... @enduml.
7. Related
UML Sequence Diagrams — full notation reference for lifelines, messages and fragments