T01: Participants and Messages

3.1.1 What Is a Sequence Diagram?

A sequence diagram models how system components interact over time.

Unlike flowcharts (which model process flow), sequence diagrams emphasize:

• Participants (actors/components)

• Message exchange

• Chronological ordering

• Request/response patterns

Sequence diagrams are ideal for:

• API call modeling

• Authentication flows

• Microservice interaction

• Event-driven architecture

• Debugging communication paths

In Mermaid, every sequence diagram starts with:

---

3.1.2 Participants

Participants represent:

• Users

• Systems

• Services

• APIs

• Databases

• External providers

Basic participant declaration:

Example:

If you omit explicit declarations, Mermaid auto-generates participants based on message lines.

Example:

Mermaid automatically creates User and Server.

---

3.1.3 Naming Participants Clearly

Use meaningful identifiers:

Poor:

Better:

Clear naming improves:

• Architectural clarity

• Debug traceability

• Documentation quality

---

3.1.4 Basic Message Syntax

The core message syntax:

Sender->>Receiver: Message

Example:

This defines:

• Direction

• Sender

• Receiver

• Message label

---

3.1.5 Arrow Types in Sequence Diagrams

Mermaid supports different arrow styles.

Arrow	Meaning
->>	Solid arrow (synchronous message)
-->>	Dotted arrow (response/return)
->	Solid line (no arrow head emphasis)
-->>	Asynchronous/return style

---

Example: Request–Response Pattern

Solid arrows = requests Dotted arrows = responses

This is standard API modeling practice.

---

3.1.6 Ordering Matters

Sequence diagrams are time-ordered from top to bottom.

This:

Means:

1. User sends request

2. Server queries DB

3. DB returns result

Reordering lines changes system behavior representation.

---

3.1.7 Real-World Example — Login Flow

Observe:

• Explicit participants

• Clear call chain

• Return responses

• Time-ordered interaction

---

3.1.8 Implicit vs Explicit Participants

Implicit version:

Explicit version:

Best practice: Declare participants explicitly in production diagrams.

---

3.1.9 External Actors

Mermaid supports actor keyword:

Actors visually appear differently from system participants.

Use actors for:

• End users

• External clients

• Third-party integrations

---

3.1.10 Multi-Service Microservice Example

This models a distributed system clearly.

---

3.1.11 Best Practices for Participants

1. Keep names descriptive

2. Avoid single-letter identifiers

3. Use consistent naming conventions

4. Declare participants at top

5. Order participants logically (left to right)

Example ordering strategy:

• User

• Gateway

• Core Services

• Database

• External APIs

---

3.1.12 Hands-On Exercise

Build a Password Reset Flow:

Requirements:

• User requests reset

• System sends email

• User clicks link

• Token validation

• Password update

• Confirmation response

Constraints:

• Use at least 4 participants

• Include request and response arrows

• Keep chronological ordering correct

---

3.1.13 Common Beginner Mistakes

1. Forgetting sequenceDiagram keyword

2. Using wrong arrow syntax

3. Placing responses before requests

4. Overcrowding with too many participants

5. Mixing flowchart syntax inside sequence diagrams

Incorrect:

A --> B

Correct:

A->>B

---

3.1.14 Key Takeaways

Sequence diagrams focus on:

• Who communicates

• What is sent

• In what order

• How responses flow back

Participants define actors in the system.

Messages define interaction.

Chronology defines behavior.

Mastering these primitives allows you to model:

• API interactions

• Microservice choreography

• Authentication flows

• Event-driven systems

In the next topic, we will explore Activation and Deactivation, which models execution lifelines and processing duration.