Sequence Diagrams: Mapping API and Authentication Flows

While Class Diagrams are fantastic for showing the static structure of a system (the nouns), they do a terrible job of showing how the system behaves over time. If you want to document the flow of an OAuth login or how three microservices coordinate to process an order, you need a Sequence Diagram.

Sequence diagrams are the most popular behavioral UML diagram. They map out the sequence of messages passed between objects, ordered chronologically from top to bottom.

The Key Elements of a Sequence Diagram

1. Actors and Lifelines

At the top of the diagram, you'll find the participants (objects, services, or human actors). Dropping straight down from each participant is a dashed vertical line called the Lifeline.

The lifeline represents the lifespan of the object during the interaction. Time flows downward along this line.

2. Messages (The Arrows)

Messages are horizontal arrows drawn between lifelines. They represent communication, function calls, or data transfers. There are three primary types of messages:

• Synchronous Message (Solid line, filled arrowhead): The sender waits for the receiver to process the message and return a response before continuing. (e.g., A standard REST API HTTP request).
• Asynchronous Message (Solid line, open arrowhead): The sender fires off the message and immediately continues its work without waiting for a reply. (e.g., Publishing an event to a Kafka topic).
• Return Message (Dashed line, open arrowhead): The response to a previous synchronous message.

3. Activation Boxes (Execution Occurrences)

When a message hits a lifeline, it usually triggers a thin, rectangular box that overlays the dashed line. This is the activation box. It indicates that the object is currently busy executing a process or waiting for a synchronous reply.

Handling Complex Logic (Fragments)

Code isn't just a straight line of execution; there are IF statements and loops. Sequence diagrams handle this using Combined Fragments (often drawn as a box enclosing a section of the interactions).

• alt (Alternative): Used for conditional logic (if/else). The box is divided into sections, one for each condition.
• opt (Option): Used for optional logic (an if statement with no else).
• loop (Loop): Indicates that the enclosed messages are repeated as long as a condition is met.
• par (Parallel): Indicates that the enclosed messages run concurrently.

A Classic Example: OAuth Login

If you've ever had to integrate "Login with Google", you know the flow can be confusing. A sequence diagram makes it crystal clear:

1. The User clicks "Login" on the Frontend Client.
2. The Frontend Client redirects the User to the Auth Server.
3. The Auth Server asks the User for credentials.
4. The User provides credentials.
5. The Auth Server redirects back to the Frontend Client with an Auth Code.
6. The Frontend Client sends the Auth Code to its Backend Server.
7. The Backend Server swaps the Code for a Token directly with the Auth Server.

Visualizing this exact flow with a Sequence Diagram instantly clarifies which server holds which secret, and where the browser redirects happen.

Ditch the Drag and Drop

Sequence diagrams are notorious for being frustrating to draw manually. If you add one new message in the middle, you have to manually drag every subsequent arrow and activation box further down the page to make room.

This is why writing diagrams as code (or using AI) is vastly superior for sequence diagrams. With AutoUML, you just describe the interaction:

User clicks login on Frontend. Frontend requests Auth from Google. Google returns Token to Frontend. Frontend sends Token to Backend API. Backend verifies Token.

AutoUML automatically aligns all the lifelines, calculates the activation box heights, and draws the arrows perfectly.