Sequence diagrams in Slack: capture API flows before they disappear

Sequence diagrams are useful in Slack because many engineering threads are really order-of-events debates. Who calls the auth service first? Does the webhook arrive before the database write? Where does the timeout happen?

Direct answer: Use sequence diagrams in Slack when timing and actor interaction matter. Name each actor, show the request and response path, include alternate or failure cases, and keep the diagram close to the thread where reviewers are asking about the flow.

When to use a sequence diagram

Use one for:

• Login and token refresh.
• Payment authorization and webhook handling.
• Background job dispatch.
• Third-party API callbacks.
• Mobile app to backend interactions.
• Retry and timeout behavior.

If the main question is "what order does this happen in?", a sequence diagram is likely the right shape.

Start with actors

A good sequence diagram starts with a clean actor list. Avoid naming every library or internal class. Focus on systems that send or receive meaningful messages.

Example actors: User, Web App, API, Auth Service, Email Service, Token Store.

Add failure paths

Sequence diagrams become much more useful when they show alternatives. For password reset, include expired token. For payments, include provider timeout. For webhooks, include duplicate event.

Do not bury these in prose if they are what the review is about.

Example prompt

@arialine create a sequence diagram for subscription renewal. Include scheduler, billing API, payment
provider, invoice database, email service, and user. Show successful charge and failed-card path.

Reviewers can then comment in Slack: "The email should be sent only after invoice write succeeds" or "Add idempotency check before updating subscription."

Where Arialine fits

Arialine's thread-based update model is a natural fit for sequence diagrams. API reviews often happen through short corrections, and each correction should produce a new diagram version with the reason attached.

That turns a conversation into a readable flow instead of leaving the final design buried in comments.

FAQ

Are sequence diagrams only for developers?

Mostly, but product and support teams can read simple sequence diagrams when actors are named clearly.

How detailed should messages be?

Use human-readable labels, not full payload schemas, unless the payload is the subject of the review.

What makes a sequence diagram bad?

Too many actors, no failure path, unclear direction, or messages named after implementation details that only one person understands.