T03: Notes and Loops

3.3.1 Why Notes and Loops Are Important

So far, sequence diagrams have shown:

• Participants

• Messages

• Activation

However, real-world systems also require:

• Contextual explanation

• Repeated behavior

• Conditional repetition

• Retry mechanisms

• Polling logic

Two powerful constructs in Mermaid help here:

• Notes → Add explanation to interactions

• Loops → Represent repeated execution

These features transform a basic interaction diagram into production-grade documentation.

---

3.3.2 Adding Notes

Notes provide commentary inside the diagram.

Basic syntax:

Note position of Participant: Text

Positions:

• right of

• left of

• over

---

Example 1 — Note on a Single Participant

Explanation:

• The note appears beside Server.

• \n creates a line break.

• Notes improve clarity without changing logic.

---

3.3.3 Notes Over Multiple Participants

You can attach notes across participants.

Syntax:

Note over A,B: Shared explanation

Example:

This is useful for:

• Security assumptions

• Network protocols

• Shared constraints

---

3.3.4 Multi-Line Notes

Mermaid supports block notes.

Use block notes for:

• Technical explanation

• Compliance details

• Performance notes

---

3.3.5 Loops: Modeling Repetition

In distributed systems, repetition is common:

• Retry logic

• Polling

• Batch processing

• Iteration through collections

Mermaid provides the loop keyword.

Basic syntax:

loop Condition
    messages
end

---

Example 2 — Retry Mechanism

This represents repeated attempts.

---

3.3.6 Practical Example — Payment Retry

The loop visually communicates:

• Iterative behavior

• Dependency on external state

• Conditional continuation

---

3.3.7 Combining Activation with Loops

Loops can contain activations.

This models polling systems clearly.

---

3.3.8 Loops with Nested Calls

Example: Order processing with inventory check.

This models iteration across data collections.

---

3.3.9 Notes Inside Loops

You can annotate loop logic.

Combining notes and loops improves documentation depth.

---

3.3.10 Real-World Example — Authentication with Token Refresh

This captures:

• Expired token handling

• Repeated refresh attempts

• Conditional termination

---

3.3.11 Best Practices for Notes

• Keep notes concise

• Use notes for context, not logic

• Avoid overloading diagram with excessive commentary

• Use Note over for system-level assumptions

Example of good use:

---

3.3.12 Best Practices for Loops

• Clearly describe loop condition

• Avoid vague labels like “Loop”

• Keep loop blocks focused

• Use loops only when repetition is essential

Good:

loop Retry up to 3 times

Poor:

loop Something

---

3.3.13 Common Mistakes

1. Forgetting end keyword

2. Nesting loops incorrectly

3. Adding excessive notes

4. Using loops where a single call suffices

Incorrect:

loop Retry
    A->>B: Call

Correct:

loop Retry
    A->>B: Call
end

---

3.3.14 Hands-On Exercise

Build a File Upload Workflow:

Requirements:

• User uploads file

• Server validates file

• If invalid, retry upload

• Loop maximum 3 attempts

• Add note explaining file size limit

• Show final success response

Constraints:

• Use at least one loop

• Use at least one note

• Maintain clean chronological order

---

3.3.15 Key Takeaways

Notes add contextual clarity.

Loops model repeated behavior.

Together, they allow you to represent:

• Retry mechanisms

• Polling systems

• Batch processing

• Token refresh flows

• Resilience strategies

By mastering participants, messages, activation, notes, and loops, you can now model realistic, production-level system interactions using Mermaid sequence diagrams.

In the next chapter, we will move into Class Diagrams, where structural modeling replaces chronological interaction modeling.