UML Interaction Overview Diagrams

An interaction overview diagram is an activity diagram whose steps are whole interactions: each box is a reference to, or a small inline copy of, a sequence diagram. It gives the big picture of a long scenario while each detailed exchange lives in its own diagram. Architects and analysts use it to stitch many sequence diagrams into one story.

1. What an Interaction Overview Diagram Shows

Real use cases contain branches, loops and parallel work, and a single sequence diagram with nested alt, loop and par fragments quickly becomes unreadable. The interaction overview diagram splits the problem: control flow (what happens next, under which condition) uses activity diagram notation, and each step is a frame pointing at a focused interaction.

Think of it as a table of contents for behaviour. The overview tells you the order and the decisions; drilling into a frame tells you the exact messages. Because each frame is a separate diagram, different teams can own different frames, and a change to one exchange does not force a redraw of the whole scenario.

2. Notation

It reuses activity diagram control nodes: initial and final nodes, decision/merge diamonds with guards, and fork/join bars for parallel flow. The steps are frames: ref frames name an interaction defined elsewhere (an interaction use), and sd frames contain a small sequence diagram inline. Lifelines are usually listed in the diagram header with the keyword lifelines.

3. Example 1: Checkout Overview

Walkthrough: after browsing, a decision checks whether the user is signed in; guests go through Login first. The two paths meet at a merge diamond, then a fork bar starts two interactions in parallel: reserving stock and authorizing payment. The join waits for both before Confirm runs. Each frame is its own sequence diagram, so the payment team can maintain AuthorizePayment without touching the overview.

4. Example 2: An LLM Agent Loop

Walkthrough: the agent plans with the LLM, then a decision checks whether a tool is needed. If so it runs CallTool (an inline sequence of request and response) and Observe, then loops back to planning. When the model is ready, it produces the answer and the flow ends. The overview makes the loop and its exit condition explicit, which is exactly where agent bugs such as runaway loops hide.

5. Pros, Cons, and When to Use

Pros

• Keeps long scenarios readable by splitting them into frames.
• Branches, loops and parallelism use familiar activity notation.
• Each frame can be owned and updated independently.
• Good navigation hub for a set of sequence diagrams.
• Makes exit conditions of loops visible.

Cons

• Adds another layer of diagrams to keep in sync.
• Rarely supported natively in diagrams-as-code tools.
• Readers must already know both activity and sequence notation.
• Little value if there are only one or two interactions.
• Easy to confuse with a plain activity diagram.

When to use

• Complex use cases spanning several sequence diagrams.
• Workflows with parallel or conditional interactions.
• Documenting agent, saga or orchestration flows at a high level.

When not to use

• Simple request-response scenarios.
• When nobody will maintain the referenced sequence diagrams.

6. Reading Tips and Common Mistakes

Read it like an activity diagram first, ignoring frame contents: follow arrows from the initial node, note every decision guard, and confirm every path reaches a final node. Then open only the frames relevant to your question.

Common mistakes: putting detailed messages in every frame (use ref and keep detail elsewhere); missing guards on decisions; and forgetting the join after a fork, which leaves it unclear whether the next step waits for both branches. Also keep frame names identical to the titles of the referenced sequence diagrams, so readers can find them.

7. As Diagrams-as-Code

Neither PlantUML nor Mermaid has a dedicated interaction overview syntax. A PlantUML activity diagram with each step named after its sequence diagram is the common approximation:

@startuml
start
:ref Browse;
if (signed in?) then (no)
  :ref Login;
endif
fork
  :ref ReserveStock;
fork again
  :sd AuthorizePayment;
end fork
:ref Confirm;
stop
@enduml

Modelling tools such as Enterprise Architect and Visual Paradigm draw the genuine notation with clickable ref frames.

8. Related Diagrams

• UML Diagrams — overview of all 14 UML diagram types and when to use each
• Communication Diagrams — another way to draw a single interaction
• Timing Diagrams — an interaction with an explicit clock
• State Machine Diagrams — lifecycle of one object rather than flow between interactions