L06 Mermaid Sequence

title: "Mermaid Sequence Diagrams — Showing Interactions" weight: 6 description: "Learn to create Mermaid sequence diagrams showing component interactions over time: participants, messages, activation boxes, notes, and loops for API and system documentation." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, diagrams] }

Mermaid sequence diagrams show interactions between components over time, making them ideal for documenting API calls, authentication flows, and message passing in distributed systems.

In this lesson, you will learn sequence diagram syntax, participant declaration, message types, activation boxes, notes, loops, and alternatives for rich interaction documentation.

What You'll Learn

You will master Mermaid sequence diagrams: declaring participants, sending messages, using activation boxes to show lifetimes, adding notes, creating loops and alternatives, and styling.

Why It Matters

Sequence diagrams are the best tool for documenting how components communicate. A sequence diagram of an OAuth flow shows exactly who talks to whom and in what order, eliminating ambiguity.

Real-World Use

Doda Browser's authentication documentation uses a sequence diagram showing the OAuth flow between browser, extension, and server. New developers understand the auth flow in 2 minutes instead of 30.

sequenceDiagram
    participant User
    participant Browser as Doda Browser
    participant Server as Auth Server
    User->>Browser: Open extension
    Browser->>Server: Request auth URL
    Server-->>Browser: Return auth URL
    Browser->>User: Show login page
    User->>Server: Enter credentials
    Server->>Server: Validate credentials
    Server-->>Browser: Return token
    Browser->>User: Show logged in state

def create_sequence_diagram(participants, messages):
    """Generate Mermaid sequence diagram syntax."""
    lines = ["sequenceDiagram"]
    for p in participants:
        lines.append(f"    participant {p['id']} as {p['label']}")
    for msg in messages:
        arrow = "->>" if msg["sync"] else "-->>"
        lines.append(f"    {msg['from']}{arrow}{msg['to']}: {msg['label']}")
    return "\n".join(lines)

diagram = create_sequence_diagram(
    [{"id": "C", "label": "Client"}, {"id": "S", "label": "Server"}],
    [{"from": "C", "to": "S", "label": "GET /api/data", "sync": True},
     {"from": "S", "to": "C", "label": "200 OK", "sync": False}]
)
print(diagram)

def add_activation_box(diagram_text, participant, start_line, end_line):
    """Conceptual demonstration of activation boxes."""
    lines = diagram_text.split("\n")
    insert = [
        f"    activate {participant}",
        f"    {participant}->>{participant}: Processing",
        f"    deactivate {participant}"
    ]
    result = lines[:start_line] + insert + lines[start_line:]
    return "\n".join(result)

diag = """sequenceDiagram
    participant Client
    participant Server"""
print(add_activation_box(diag, "Server", 3))

def add_loop_block(diagram_text, loop_label, content_lines):
    """Add a loop block to a sequence diagram."""
    block = f"    loop {loop_label}\n"
    for line in content_lines:
        block += f"    {line}\n"
    block += "    end"
    return diagram_text + "\n" + block

diag = "sequenceDiagram\n    C->>S: Request"
new_diag = add_loop_block(diag, "Retry up to 3 times",
                          ["C->>S: Retry request", "S-->>C: Retry response"])
print(new_diag)

Teacher Mindset

Think of sequence diagrams as comic strips for your code. Each panel shows a moment in time. The participants are characters. The messages are dialogue bubbles. A good sequence diagram tells a story: first this happens, then that happens, and here is how the characters respond. If the story is confusing, the implementation will be too.

Common Mistakes in Sequence Diagrams

1. Too Many Participants

Sequence diagrams with 8 or more participants become unreadable. Group related participants or split into multiple diagrams focusing on specific interactions.

2. No Activation Boxes

Without activation boxes, it is unclear how long each participant is active. Add activate and deactivate markers to show processing lifetimes.

3. Messages Without Clear Labels

"Send data" is vague. "POST /api/users with JSON body" is specific. Every message label should describe exactly what is sent.

4. Missing Error Paths

Sequence diagrams showing only the happy path miss crucial error scenarios. Include alt blocks for error conditions and retry loops.

5. Linear Diagrams Without Conditionals

Real interactions have conditions and loops. Use alt for alternatives, opt for optional steps, and loop for repetitions.

Practice Questions

1. What is the difference between solid and dotted arrows in sequence diagrams? Solid arrows (->>) represent synchronous calls where the sender waits for a response. Dotted arrows (-->>) represent asynchronous responses or callbacks.

2. How do you show conditional logic in sequence diagrams? Use alt keyword for alternative paths, opt for optional steps, and loop for repeated actions. Close each block with the end keyword.

3. What are activation boxes and when should you use them? Activation boxes show when a participant is actively processing. Use activate at the start of processing and deactivate when processing ends. They help readers understand timing.

4. How do you add notes to sequence diagrams? Use Note right of, Note left of, or Note over to add explanatory text. Notes should clarify what is happening without cluttering the message flow.

5. Challenge: Create a sequence diagram for an OAuth 2.0 authentication flow showing the resource owner, client application, authorization server, and resource server. Include success and error paths.

FAQ

Mini Project

Document an API endpoint from DodaZIP or Doda Browser using a sequence diagram. Include the client request, server validation, database interaction, and response. Use activation boxes, an alternative path for errors, and a loop for retry logic.

What's Next

Mermaid Class in the next lesson.