The Complete Guide to Sequence Diagrams (with Examples)

Sequence diagrams are one of the most powerful tools in a developer's communication toolkit. They show how objects or services interact over time, making them ideal for documenting API flows, authentication handshakes, and complex business processes.

What Is a Sequence Diagram?

A sequence diagram is a type of UML interaction diagram that shows how processes operate with one another and in what order. It depicts objects or actors as vertical lifelines, and messages between them as horizontal arrows. Time flows from top to bottom.

Key Elements

• Actors / Participants: The entities involved in the interaction (users, services, databases).
• Lifelines: Vertical dashed lines representing the existence of a participant over time.
• Messages: Horizontal arrows showing communication — synchronous (solid) or asynchronous (dashed).
• Activation bars: Thin rectangles on lifelines showing when a participant is active.
• Alt/Opt/Loop fragments: Boxes that represent conditional logic, optional steps, or loops.

Example: User Login Flow

Here's a typical sequence diagram for a user login flow. The user submits credentials, the frontend calls the auth service, which validates against the database, generates a JWT, and returns it.

User -> Frontend: Enter credentials
Frontend -> AuthService: POST /login {email, password}
AuthService -> Database: SELECT user WHERE email=?
Database --> AuthService: User record
AuthService -> AuthService: Validate password, generate JWT
AuthService --> Frontend: 200 OK {token}
Frontend --> User: Redirect to dashboard

Best Practices

• Keep it focused: One diagram per use case or flow. Don't cram everything into one diagram.
• Name participants clearly: Use role names (AuthService) not generic names (Service1).
• Show error paths: Include alt fragments for error cases — they're often more important than the happy path.
• Label messages precisely: Include HTTP methods, event names, or function signatures.
• Read top to bottom: Ensure the time ordering is logical and easy to follow.

Generating Sequence Diagrams with AI

With ArchitectAI, you can describe any interaction flow in plain English and get a sequence diagram in seconds. Just type something like "Show the OAuth2 authorization code flow between a mobile app, auth server, and resource server" and the AI handles the rest — including proper arrow types, activation bars, and layout.