Diagram Atlas

SoftwarePILOT · EVIDENCE-BACKED

Sequence diagram

An interaction model where actors sit across the top, time moves downward, and horizontal messages explain a scenario.

TRY YOUR OWN SCENARIOUses the reviewed Sequence contract and live validator.

USE WHEN

Documenting API calls, protocols, authentication, or request/response behavior.

AVOID WHEN

The goal is a static component inventory.

VISUAL GRAMMAR

01actors02lifelines03messages04activation bars05fragments

SEMANTIC RULES

Time always moves downward.
Calls are solid and returns dashed.
Use ALT, OPT, or LOOP frames for branches.
Limit the default view to five actors and twelve messages.

QUESTIONS IT ANSWERS

Who calls whom?
In what order?
What happens on failure?

Evidence-backed pilot

Notation semantics are separated from Diagram Atlas editorial limits. Every executable rule points to evidence.

Reviewed 2026-08-23

01 · READING CONTRACT

What this diagram promises

A sequence diagram explains one interaction scenario. It privileges message order and responsibility—not system inventory or measured duration.

It should answer

Who exchanges each message?
In what order do interactions occur?
Where do alternatives, optional paths, and repetition change the scenario?

Choose another view for

A static inventory of system components
Precise elapsed-time or performance measurement
Ownership lanes in a business process

02 · ANATOMY

Five parts, each with one job

01Participant

A role, person, service, or object taking part in the interaction. [1][2]

02Lifeline

The vertical trace of one participant. Occurrence order increases from top to bottom; distance is not literal duration. [1]

03Message

A directed communication between lifelines, labeled with an action, request, signal, or result. [1]

04Activation

A narrow bar showing the period in which a participant executes or owns control. [2][3]

05Combined fragment

A framed region for alternatives, optional behavior, loops, or parallel behavior, with guards in square brackets. [1]

03 · MESSAGE VOCABULARY

Arrow shape carries meaning

This is the Diagram Atlas visual profile. UML defines message semantics; Mermaid and Diagram Design make the rendering conventions executable.

Kind	Atlas notation	Meaning	Example
Synchronous call	`solid line · filled head`	The sender waits while the receiver performs an operation. [3][2]	`API → Auth: verify()`
Reply	`dashed line · filled head`	A response or returned value from a previous call. [3][2]	`Auth ⇢ API: token`
Asynchronous signal	`solid line · open head`	The sender emits work without waiting for the receiver to finish. [1][2]	`API →) Queue: publish`
Self-message	`loop to same lifeline`	A participant calls its own behavior; the loop must remain visibly outside the activation. [3]	`Cache ↺ Cache: lookup`

04 · COMPLEXITY BUDGET

Defaults for a readable first view

These limits are editorial guardrails, not restrictions in UML. Exceeding them produces a warning, not an invalid diagram.

Participants≤ 5Default editorial view

Messages≤ 12Split longer scenarios

ALT regions≤ 2Prefer a second diagram

Nesting≤ 1Avoid frame mazes

05 · INTERACTIVE QUALITY LAB

Break the notation. Watch the rules repair it.

This specimen runs the same validator used by the drawing workspace. Introduce three semantic problems, then repair them from the knowledge model.

06 · EXECUTABLE RULES

Every claim has a basis and a check

SEQ-001NormativeRequired

Order occurrences downward

Read event order from top to bottom on each lifeline. Never use vertical spacing as a promise of elapsed time. [1]

Message order must be explicit; reject reverse-time routing.

SEQ-002NormativeRequired

Reference declared participants

Every message endpoint must resolve to a participant declared once across the top row. [1]

from and to must match participant IDs.

SEQ-003NormativeRequired

Frame conditional behavior

Place alternatives, optional paths, and loops inside a labeled combined fragment; put guards in square brackets. [1]

A conditioned message must reference an alt, opt, or loop fragment.

SEQ-004EditorialRecommended

Encode message intent

Use the Diagram Atlas profile consistently: calls are solid/filled, replies dashed/filled, and asynchronous signals solid/open. [2][3]

lineStyle and arrowhead must match message kind.

SEQ-005EditorialRecommended

Keep one readable scenario

Start with at most five participants and twelve messages. Treat these as editorial defaults, not UML limits. [3]

Warn above 5 participants or 12 messages.

SEQ-006EditorialRecommended

Name messages as actions

Use concise verb phrases, operations, or concrete results. Avoid labels such as data, call, or response without context. [3]

Warn on missing or placeholder labels.

07 · ANTI-PATTERN CLINIC

Common failures and direct repairs

SEQ-003

Free-floating branch

Two arrows diverge without a frame or guard.

Fix · Use an alt or opt fragment and label each guard.

SEQ-001

Timeline by pixel distance

A larger vertical gap is presented as a longer duration.

Fix · Add an explicit timing constraint or use a timing diagram.

SEQ-005

Message soup

Six or more lifelines and a wall of crossing arrows.

Fix · Extract a sub-scenario and link the two diagrams.

SEQ-004

Ambiguous arrows

Calls, replies, and fire-and-forget signals all look identical.

Fix · Apply one documented arrow profile consistently.

08 · VALIDATOR PROOF

The rules run, not just read

The repository includes a typed validator and automated tests. Issues return stable rule IDs, severity, and the failing data path.

PassFocused login flow

4 participants · 5 messages · endpoints resolve · reply style valid

FailUndeclared audit service

SEQ-002 · message endpoint is not declared

FailConditional retry without frame

SEQ-003 · conditioned message has no loop fragment

WarnLarge checkout scenario

SEQ-005 · 7 participants and 16 messages exceed the editorial budget

09 · SOURCES & PROVENANCE

Standards, implementation, editorial judgment

We label the role of each source so an opinion never masquerades as a standard.

Normative
Unified Modeling Language 2.5.1
Object Management Group · Interaction, lifeline, message, occurrence-order, guard, and combined-fragment semantics.
Implementation
Sequence diagram syntax
Mermaid · Executable syntax for participants, arrows, activations, notes, loops, alternatives, and sequence numbers.
Editorial
Sequence diagram design reference
Diagram Design · Cathryn Lavery · Visual defaults, density limits, anti-patterns, and the specimen style. MIT licensed.

VALIDATED MACHINE CONTRACT

id: sequence
version: 1
status: evidence_backed_pilot
intent: ordered_message_exchange
input:
  participants: { min: 2, recommended_max: 5 }
  messages: { min: 1, recommended_max: 12 }
  message_kinds: [sync, reply, async, self]
  fragments: [alt, opt, loop]
profile:
  sync: { line: solid, arrowhead: filled }
  reply: { line: dashed, arrowhead: filled }
  async: { line: solid, arrowhead: open }
checks:
  - id: SEQ-001
    severity: required
    basis: normative
  - id: SEQ-002
    severity: required
    basis: normative
  - id: SEQ-003
    severity: required
    basis: normative
  - id: SEQ-004
    severity: recommended
    basis: editorial
  - id: SEQ-005
    severity: recommended
    basis: editorial
  - id: SEQ-006
    severity: recommended
    basis: editorial
provenance:
  - omg-uml-251
  - mermaid-sequence
  - diagram-design-sequence