Sequence Diagrams: How to Visualize Flows, APIs, and User Journeys

What Is a Sequence Diagram?

A sequence diagram shows how objects or services interact with each other over time. Unlike a flowchart — which maps the path of a process — a sequence diagram maps the conversation: who sends a message, who receives it, and what happens next.

They're the go-to diagram for:

• Documenting API request/response cycles
• Illustrating login and authentication flows
• Explaining microservice communication
• Onboarding engineers to unfamiliar codebases
• Debugging by mapping out what should happen versus what does

The Core Building Blocks

A sequence diagram has three basic elements:

| Element | What It Represents | |---|---| | Participant | An actor, service, or component (drawn as a box at the top) | | Lifeline | The dashed vertical line showing a participant's timeline | | Message | An arrow from one lifeline to another, labeled with the action |

Messages flow left to right and top to bottom — time moves downward. That's it. Once you understand those three pieces, you can read any sequence diagram.

Synchronous vs. Asynchronous Messages

• Solid arrowhead → Synchronous call. The sender waits for a response before continuing.
• Open arrowhead ⇒ Asynchronous message. The sender fires and moves on.
• Dashed arrow ← Return message. Often drawn as a reply to a synchronous call.

Activation Boxes

A thin rectangle on a lifeline — called an activation box — shows the period during which a participant is actively doing work. It helps you visualize processing time and overlapping activity.

A Practical Example: User Login

Here's a simple login flow with three participants: Browser, API Server, and Auth Service.

Browser → API Server : POST /login {email, password}
API Server → Auth Service : verifyCredentials(email, password)
Auth Service → API Server : {valid: true, userId: 42}
API Server → API Server : generate JWT
API Server → Browser : 200 OK {token: "..."}

As a sequence diagram, this becomes a clear picture where:

1. The Browser sends a login request
2. The API Server delegates credential verification
3. The Auth Service confirms the user
4. The API Server generates and returns a token

Without the diagram, this flow lives scattered across four different files or explained in a long paragraph that's hard to skim.

When to Use a Sequence Diagram (and When Not To)

Use sequence diagrams when:

• You need to document communication between two or more systems or services
• You're explaining a feature to engineers who didn't build it
• Something is going wrong and you want to map out the exact sequence of calls
• You're designing a new API and need to validate the interaction model before writing code

Don't reach for sequence diagrams when:

• You're mapping a single system's internal logic — a flowchart is simpler
• You need to show the overall structure of a system — use a system architecture diagram
• The flow has only one participant — a basic numbered list does the job

Sequence Diagrams in CodePic

CodePic's hand-drawn aesthetic makes sequence diagrams easier to share and discuss — they feel like a whiteboard sketch rather than a sterile formal doc, which encourages feedback instead of sign-off anxiety.

Here's how to build one:

1. Open a blank canvas or start from a sequence diagram template
2. Add participants — create a box at the top for each actor (Browser, API, Database, etc.)
3. Draw lifelines — extend vertical dashed lines downward from each participant
4. Add messages — draw horizontal arrows between lifelines and label them with the action
5. Add activation boxes — optionally, mark the active processing period with a thin rectangle
6. Group with frames — use a rectangle frame with an alt or loop label for conditional or repeated flows

Tips for Clean Diagrams

• Keep participant names short. "Auth Service" beats "Authentication and Authorization Microservice"
• Label every arrow. Unlabeled arrows are confusing — even "request" or "response" is better than nothing
• Use return arrows sparingly. Only draw a dashed return arrow if the return value is meaningful (a token, a status code, an ID)
• Order participants by flow. Put the initiating actor on the far left. Let the arrows read mostly left-to-right

From Diagram to Documentation

A sequence diagram is most useful when it lives next to the code. Some teams embed the image in their README or in the PR description when they introduce a new endpoint. Others keep a /docs/diagrams/ folder and update it during code review.

Either way, the sequence diagram becomes the fastest way to answer the question: "What happens when X calls Y?"

Export your CodePic diagram as a PNG or SVG and drop it wherever your team actually looks — the wiki, the PR, the design doc. The hand-drawn style makes it instantly recognizable and easy to iterate on.

Sequence diagrams are one of those tools that seem optional until you're three hours into a debugging session and realize you've been mentally simulating something that would take two minutes to draw. Start simple: three participants, five messages. That alone is usually enough to find the gap.