Sequence Diagrams

What are Sequence Diagrams?

Marmaid's Sequence diagrams are interaction diagrams that depict how processes interact with one another in a time-ordered sequence. They are widely used in system design, workflow analysis, and documenting user interactions. Each participant or actor is represented, and the sequence of messages exchanged between them is visualized to provide insights into the flow of information.

Sequence diagrams are particularly useful for:

  • Visualizing the flow of messages in a system.

  • Clarifying system requirements and interactions.

  • Documenting complex workflows.

  • Debugging and optimizing processes.

Creating Your First Sequence Diagram

  1. From the Code IDE, click Apps and Agents from the left-hand panel.

  2. Select Mermaid. Paradime will automatically start a new Mermaid project.

  3. In the terminal that appears, use the arrow keys to select "Sequence Diagram."

  4. A new sequenceDiagram.mmd file will be created in your editor with this starter template:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!
  1. Click the eye icon (👁️) in the top right corner of your Mermaid file to preview the diagram.

  2. Edit and update your .mmd file as needed—the preview will update automatically.

Diagram Syntax Guide

Basic Syntax

Define participants and the interactions between them:

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!

Participants

Participants can be implicitly created or explicitly defined:

sequenceDiagram
    participant Alice
    participant Bob
    Bob->>Alice: Hi Alice
    Alice->>Bob: Hi Bob

Participants represent entities that interact within the sequence. They can include:

  • Users

  • Systems or subsystems

  • External services

  • Devices

Actor Symbols

Actors can be specified explicitly to use the actor symbol:

sequenceDiagram
    actor Alice
    actor Bob
    Alice->>Bob: Hi Bob
    Bob->>Alice: Hi Alice

Actors are visually distinct from participants to represent active agents more prominently.

Message Arrows

Sequence diagrams support various message types with different arrow styles:

  • -> : Solid line without arrow

  • --> : Dotted line without arrow

  • ->> : Solid line with arrowhead

  • -->> : Dotted line with arrowhead

  • -) : Solid line with open arrow (asynchronous)

  • --) : Dotted line with open arrow (asynchronous)

Example:

sequenceDiagram
    Alice->>John: Synchronous message
    John--)Alice: Asynchronous reply

Advanced Message Features

  • Activations: Highlight active participants during a message exchange:

    sequenceDiagram
        Alice->>+John: Hello John
        John-->>-Alice: Hi Alice
  • Stacked Activations: Multiple activations for the same participant:

    sequenceDiagram
        Alice->>+John: Hello John
        Alice->>+John: Can you hear me?
        John-->>-Alice: Yes, loud and clear!

Notes

Add notes for additional context:

sequenceDiagram
    Alice->John: Hello John
    Note over Alice,John: A typical interaction

Conditional and Loop Blocks

  • Loops: Repeated interactions:

    sequenceDiagram
        Alice->John: Hello
        loop Every minute
            John-->Alice: Responding
        end
  • Conditionals: Alternate paths:

    sequenceDiagram
        Alice->>Bob: Request data
        alt Data available
            Bob-->>Alice: Sending data
        else Data unavailable
            Bob-->>Alice: No data found
        end

Parallel and Critical Regions

  • Parallel Actions: Show simultaneous actions:

    sequenceDiagram
        par Alice to Bob
            Alice->>Bob: Start task
        and Alice to John
            Alice->>John: Start another task
        end
  • Critical Sections: Represent mandatory sequences:

    sequenceDiagram
        critical Establish connection
            Service->>Database: Connect
        option Timeout
            Service->Service: Retry
        end

Data Team Examples

ETL Workflow

sequenceDiagram
    participant ETL as ETL Pipeline
    participant DB as Database
    participant Report as Reporting Tool

    ETL->>DB: Load transformed data
    DB->>Report: Fetch latest data
    Report->>DB: Validate data
    DB-->>Report: Validation complete

System Monitoring

sequenceDiagram
    participant User
    participant API
    participant Monitor

    User->>API: Submit request
    API->>Monitor: Log activity
    Monitor-->>API: Acknowledge
    API-->>User: Return response

Best Practices

  1. Use clear labels: Ensure participants and messages are descriptive and unambiguous.

  2. Keep diagrams concise: Avoid overloading with unnecessary details.

  3. Group participants logically: Arrange participants in a meaningful order.

  4. Use notes for clarity: Add notes to explain complex interactions.

  5. Regular updates: Keep diagrams up-to-date to reflect current workflows.

Advanced Features

Styling

Customize sequence diagrams with CSS for a polished appearance:

.actor {
  stroke: #333;
  fill: #f3f3f3;
}
.messageLine0 {
  stroke: #00aaff;
}
.note {
  fill: #ffeeba;
  stroke: #333;
}

Sequence Numbers

Show sequence numbers for message arrows:

sequenceDiagram
    autonumber
    Alice->>John: Step 1
    John->>Bob: Step 2
    Bob-->>Alice: Step 3

Highlighting Regions

Highlight specific interactions with colored backgrounds:

sequenceDiagram
    participant Alice
    participant John

    rect rgba(191, 223, 255, 0.5)
    Alice->>John: Important step
    John-->>Alice: Acknowledgment
    end

Additional Resources

For more syntax options and advanced features, visit the official Mermaid documentation.

Last updated

Was this helpful?