The assistant for sequence diagrams

The assistant works on sequence diagrams too. When a sequence diagram is open, it thinks like a software architect: it knows how sign-ins, payments, APIs, caches, queues and webhooks really talk, and draws the calls, replies and failure paths that matter. Setting it up, choosing the model, the change card and undo work the same as for a process. This page covers what's different.

Press ⌘ I (Ctrl I on Windows and Linux) to open it.

Draft a diagramCopy Anchor Link

On an empty sequence diagram, the assistant offers flows to start from: Sign in with Google, Checkout payment, Password reset, API with cache, Webhook delivery, File upload to storage, Chat message delivery and Two-factor sign-in. Each one fills in a request to draw that flow in a typical web app. Edit it to fit your system, then send it.

Or describe the interaction in your own words. A good request says:

• Who takes part. The people and systems, as you call them: "the mobile app, our API, the payments provider and the orders database".
• What starts it. "When a shopper pays for an order."
• How it ends, including the failure paths you care about: "card declined, provider timeout".
• The details only you know. Endpoint and event names, timeouts, retry limits: "retry up to 3 times, then give up".

For example:

Draw how our mobile app uploads a profile photo. The app asks our API for an
upload URL, uploads the file straight to storage, then tells the API it's done.
The API checks the file and saves it to the users database. Show what happens
when the upload fails or the file is too large.

For a well-known flow, such as an OAuth sign-in, the assistant drafts straight away. For your own system, when you haven't said who takes part, it may first ask up to three short questions, each with the answer it would assume. To skip them, say "draft it now and list your assumptions".

How it drawsCopy Anchor Link

The assistant follows the same style the sequence code reference describes:

• one scenario per diagram, with the participant who starts it on the left;
• short message text: an action for a call ("Create payment"), a result for a reply ("Payment confirmed");
• a reply to every call that waits for one, and async messages for events, queues and webhooks;
• alt and opt for the failure paths that matter, and a loop with a limit for retries;
• activation bars on the main service handling a request, not on every message;
• about 3 to 8 participants and up to 30 messages. For more, it suggests a second diagram.

When it drafts, it can look up reference interactions for common flows, such as an API request, a cache, a sign-in, webhook retries, a queue and a card payment, and adapts them to the systems you name.

Change a diagramCopy Anchor Link

Point at what should change and say how:

• "Add a cache in front of the database."
• "After Create payment, retry up to 3 times if the provider times out."
• "Make Order paid an async message to the queue."
• "Put a note over API and Payments: idempotency key on every request."

For small changes the assistant edits only what you asked about, so the rest keeps its ids and your comments stay on their elements. To have most of a diagram redone, say so.

To point at particular elements, select them on the canvas before you send, or type @ and pick them from the list: participants first, then messages, fragments, notes and dividers in reading order.

Use a commandCopy Anchor Link

Type / at the start of the message box to pick a command. Each one fills in a request for you to read over and send.

On a diagram that already has elements, the starting points above the message box are Review this diagram, a fix for the issues the checks found, Explain it, and Add failure paths when the diagram has no fragments yet.

What it does with your diagramCopy Anchor Link

• Drafting or redoing most of it: it writes the whole diagram as sequence code and replaces the diagram with it.
• Smaller changes: it applies a batch of small edits to participants, messages, notes, dividers and fragments. If one edit in a batch fails, none apply.
• Checking its work: after every change it gets the checks back, and fixes errors and real problems before it finishes.

The change card shows each change as a diff of the sequence code. It ends with a short summary of what it drew or changed, what it assumed, and one or two things you might add next.

Use your own AI appCopy Anchor Link

A connected AI app can work on sequence diagrams through the same tools:

• Create one. Ask for it by name: "Create a sequence diagram called Checkout payment." create_diagram takes a kind, and sequence makes a sequence diagram. Without it, the AI creates a BPMN process.
• Find one. list_diagrams says each diagram's kind, so the AI knows which diagrams are sequence diagrams.
• Read and write it. get_diagram returns the sequence code with every element's id, write_diagram takes sequence code, and edit_diagram takes edits to participants, messages, notes, dividers and fragments.
• Look things up. lookup_guidance has topics for sequence diagrams: sequence-code for the syntax, sequence-style for the drawing style, and reference interactions for common flows. The AI is told to look up the syntax before its first write. See Guidance topics for every topic, word for word.

The diagram card in the chat, live updates in the app and the version history work as they do for a process. See Tools for every tool and edit, with its parameters.