Lifeline Budget

A settlement flow drawn as one page with 14 lifelines and 61 messages has stalled three consecutive reviews. The instinct is to enlarge the canvas. The arithmetic says otherwise: a reader must track the state of every lifeline at every step, which is over 850 cells, across 14 × 13 = 182 ordered pairs that could interact.

Comprehension collapses somewhere around five or six lifelines, and the consequence is not merely that the diagram is hard to read. It is that the annotations which make a sequence diagram more useful than prose — a timeout on each arrow, the retry policy, whether the receiver is idempotent — have no room on the page, so they are absent from exactly the diagrams that most need them.

A lifeline budget turns that into a rule: five lifelines per page, under about fifteen messages, and a stated split point when the flow exceeds it.

Why it matters

The two questions a sequence diagram exists to answer are what happens when a participant is slow, and what happens when a step is retried. Both are answered by labels on arrows. A crowded diagram answers neither, which means it costs maintenance and returns only an ordering that prose could have given.

Review time is the second cost. Three stalled reviews on a six-month settlement programme is six weeks of calendar on a decision that was never the hard part.

Implementation patterns

• Split at the first boundary the team does not own. That line is where failure semantics change — your timeouts inside, someone else's error taxonomy and latency outside — where the audiences split, and it is stable, because ownership changes yearly while internal structure changes every sprint.
• Write the latency budget in each page title: "this leg has 400 ms of the 1.2 s deadline". Without it three pages quietly sum to more than the deadline.
• One failure branch per page, for the step most likely to be slow, rather than every branch everywhere.
• Collapse only what is genuinely uniform. A loop over 50 identical line items collapses safely. A retry loop does not, because retry behaviour is where duplicate charges come from.
• Name the pages by flow, not by number: "authorisation", "capture at the processor", "reconciliation file". A reader looking for a specific behaviour then knows which page to open.

Industry example

The convention is visible in the way payment and ticketing integrations are documented in practice: the merchant-side flow, the processor-side flow and the settlement file flow are three diagrams in nearly every published integration guide, split precisely at the boundary of who operates what. The split is usually explained as a documentation convenience. It is really a failure-semantics boundary, which is why it is also the right split inside a single company's internal diagrams.

The underlying constraint is older than the notation. UML's interaction diagrams date from the 1990s and the limit has never been the tooling; it is the reader, who in production has to hold the picture in their head while something is on fire.

Stated as an archetype: the five-lifeline figure is a readability heuristic consistent with common practice, not a published measurement.

Failure scenarios

• The split is made along internal component lines, so the pages go stale at different rates and a reader cannot tell which page is current.
• Arrows are redrawn asynchronous to reduce clutter while the code is synchronous, and the diagram now hides the thread-blocking behaviour that matters most under load.
• Each page gets its own copy of the shared participants, and the copies drift until two pages disagree about the same interaction.
• The budget is applied to a throwaway diagram, so effort is spent splitting and maintaining a picture that existed to settle one argument.

Trade-offs

Splitting buys room for annotation and costs the single end-to-end view. For a reader who needs the total latency path, three pages are worse than one, and the per-page budget in the title is a partial substitute rather than a full one. Multiple pages also multiply the number of artefacts that can rot.

Choose the split when the diagram will be read again by people who were not in the room. It flips for a one-off: date the single crowded picture, attach it to the decision record, and let it expire.

When not to use it

Do not budget lifelines on a generated diagram. If the picture is produced from traces or from code on every build, crowding is a rendering problem and the correct fix is a filter, not a split — generated diagrams cost nothing to redraw and carry no staleness risk, so the economics that justify the rule do not apply.

Interview question

Q: An engineer brings you a one-page sequence diagram with 14 lifelines for a payment settlement flow and asks how to make it reviewable. Where do you cut it, what must appear on every page afterwards, and when would you tell them not to bother?

What a strong answer covers: cutting at the first boundary the team does not own, with the reasoning about failure semantics, audience and stability; five lifelines and under fifteen messages per page; timeouts, retry policy and idempotency on arrows plus a per-page latency budget; keeping retry loops uncollapsed; and declining the whole exercise for a throwaway diagram or a generated one.

Quick check

Quiz: Why are timeouts missing from most large sequence diagrams? — There is no room for the labels, so the diagrams that most need the annotation are the ones least able to carry it.

Flashcard: Where should a too-large sequence diagram be split, and why there? — At the first boundary the team does not own: failure semantics change there, the audiences differ, and ownership is stable while internal structure is not.