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.