Software ArchitectureAtlas

Software Architecture Atlas

Gain an overview. Understand the connections.

ArtifactChapter III · Documentation · Building block 3 of 6

Sequence diagram

A sequence diagram shows involved actors and messages along a common timeline. It makes the order, response and alternative paths of a process visible.

By Michael Meierhoff · Meierhoff Systems

  1. LifelinesActors involved as traces.
  2. NewsOrder along time.
  3. Error pathstate in the absence of response.

Context

Why this is important

Which message comes when and from whom, decides in payments on double charge or open orders. A sequence diagram makes sequence and error paths visible. Repeat and Timeout have their own building blocks.

This building block deals with temporal interactions. Timeout deepens the uncertain call output; delivery explains message repetition.

At a glance · Messages in order

Three participants exchange numbered messages; the reply closes the flow.
Shop example · Sequence of time

Ordering and payment with clarification path

The shop reserves an order, authorizes the payment and then confirms the order. If the answer is lost, he asks for the existing payment status.

This is how you read the picture

  1. Lifelines Tracks “Order”, “Payment” and “Provider”.
  2. News Events of ‘0 ms: Payment order B-1042 handed over until “”320 ms: Confirm order.
  3. Error path Missing ‘280 ms: Authorization confirmed, remains B-1042 unconfirmed.
OrderPaymentProviders

Step 1 of 6 · Order → Payment

0 ms: Payment order B-1042 handed over

Order module transfers the amount and order identifier to the payment module.

The payment module has the provider integration; order receives the confirmed status via its module contract.

Benefits & limitations

Helps if:

  • The sequence of multiple messages can shape business impact and error behaviour.
  • Interruption points, acknowledgements and parallel actions benefit from a shared interaction view.

Boundaries

  • The diagram does not show latency; runtime measurements complement message ordering.
  • A diagram covering every special case becomes cluttered; draw independent flows separately, such as a retry after a Timeout.
  • It shows interactions; C4 provides the structure of the building blocks.

In practice

  1. Bound the process. Choose a trigger and expected outcome, then identify the necessary participants. Limit alternative paths to the question at hand. This gives the interaction a focused scope.
  2. Map messages and state changes. Place calls, responses and asynchronous messages in time order and mark business commit points. Distinguish technical acknowledgements from durable outcomes. This makes the effect of each message clear.
  3. Check failure paths. Add relevant interruptions, retries and concurrent cases, then compare them with implementation or runtime observations. Keep unresolved states visible. This creates a process model that exposes important questions requiring resolution.
Read the detailed explanation

A sequence diagram places participants on lifelines and shows messages in time order from top to bottom. Responses, conditions, loops and parallel paths make the interaction precise. It focuses on temporal interactions using Synchronous communication or Asynchronous communication; suitable structural views describe static structure.

Important state changes, acknowledgements and persistence points should be distinct. Alternative paths show the consequences of failures or cancellation. The diagram describes intended ordering; timings and actual execution need other evidence. A clearly bounded process keeps it reviewable; choose only variants relevant to the decision being examined. Activations, conditions and returns help distinguish shifts in responsibility. Include only message details relevant to the process under study. A sequence diagram describes selected interactions rather than the entire system state.

UML (Unified Modeling Language) is the notation from which sequence diagrams originate: lifelines with messages in chronological order.

Check your understanding

Test yourself in three stages

  1. ReadingCheck in the picture

    Which lane calls the provider?

    View the solution with justification

    The lane “Payment” sends to 20 ms the authorization P-731 to the provider. Order does not speak directly to him.

  2. ApplyingTransferred to a new situation

    The notification to: 300 ms to the order remains, but the authorization is with the provider. What are you checking?

    View the solution with justification

    B-1042 is not confirmed. The payment module asks the status of P-731 from the provider and logs it to the order module, instead of re-authorizing.

  3. EvaluateWeighing an alternative

    Should the error path be in the same diagram or in its own? Weigh in.

    View the solution with justification

    In the same diagram, the connection remains visible, but it becomes fuller. A separate diagram remains readable, but requires a clear reference to the point where the path branches off.

Explore further

These building blocks continue the thoughts of this page.

OperationsTimeoutA timeout limits waiting time. Here you learn how the caller handles the resulting state.Opening CommunicationIdempotencyIdempotence keeps the business effect stable when the same command is repeated.Opening FundamentalsArchitecture viewsArchitecture views explain a system from the perspective that answers a specific question.Opening

References

Continue on the learning path

Next in Documentation & communication: Deployment view.

6 Building blocks

Continue withDeployment view