200apps Corpus

Appearance

Architecture & Technical Design · master area

Sequence Diagrams ​

Request flow through services, with failure paths visible. Every Epic has at least one. The diagram the amigos session reads aloud — and the artefact that catches integration-gap before code begins.

Owners: Tech Lead, Developer Phase it lives in: What We Build (Volume III) The corpus principle this enacts: Name every state — including the moments between systems.

Where it lives in the chain ​

How to do this ​

A sequence diagram shows the actors (frontend, gateway, service A, service B, database, third-party) and the messages between them, in order, with timing and failure modes visible:

  • Happy path — the messages that flow when nothing goes wrong.
  • Failure paths — what happens when service B times out, when the database is locked, when the third-party returns 503.
  • Retries — where they happen, how many, with what backoff.
  • Compensations — when a downstream step fails, what gets undone upstream.

What good practice looks like ​

The diagram is drawn in Mermaid (text, versionable) or drawn in Figma (visual, annotated) — but lives in source control, next to the ADR. A sequence diagram on someone's whiteboard photo in Slack is a sequence diagram that doesn't exist.

Every line on the diagram has an owner (which service publishes, which service consumes), a contract (which API contract describes the message), and a failure mode (what does the caller do if this call fails). The amigos session reads the diagram aloud — "The frontend posts to the gateway, which calls Grading, which publishes ExamGraded, which Billing consumes…" — and at every step asks "what if this fails?" The session that doesn't ask is the session that lets integration-gap ship.

The Tech Lead's discipline: the diagram is updated when the contract changes. A diagram that lags the implementation is a diagram that lies to the next reader.

200apps · How We Work · NWIRE

Internal corpus. Voice and structure © 200apps.