Sequence code

Sequence code is the text form of a sequence diagram. The Sequence code pane beside the canvas shows it, and you can edit it there: the diagram follows when you pause typing. The assistant and a connected AI app write the same code, so knowing it helps you read what they draft. The layout is automatic, so the code only says who takes part and what they send.

A first diagramCopy Anchor Link

Paste this into the Sequence code pane to see it drawn.

title Password reset
actor User
participant App
database Users DB as DB

User->App: Forgot password
App->DB: Find user by email
alt user found
  DB-->App: User
  App->>User: Email reset link
else no such user
  DB-->App: Nothing
end
App-->User: Check your email

Reading it from the top:

• title Password reset names the diagram.
• actor, participant and database declare the columns, left to right. as DB gives a long name a short alias for the lines below.
• Every other line is a message: who sends it, an arrow, who receives it, then a colon and the text.
• alt and else start the two branches, and end closes the fragment.

The rules that matterCopy Anchor Link

1. One element per line, top to bottom. The order of the lines is the order of the messages.
2. Participants are created as lines name them. The first line that mentions a name adds its column, so you don't have to declare anything. Declare participants at the top to fix their order, set their kind, or give them an alias.
3. A message needs a colon before its text. App->DB: Find user. The text can be left out: App->DB draws an arrow with no label.
4. Fragments close with end. Indenting the lines inside by two spaces is the app's style and makes the code easier to read, but the app doesn't need it.
5. Keywords and names ignore case. ALT works like alt, and app finds the participant called App.

Title and numberingCopy Anchor Link

title Checkout payment
autonumber

title names the diagram, the same name you see at the top of the editor. autonumber, on a line of its own, numbers the messages 1, 2, 3.

ParticipantsCopy Anchor Link

participant Shop
actor Shopper
database "Orders DB" as DB

• participant draws a box, actor a stick figure for a person, and database a cylinder for a data store.
• as gives the participant an alias: a short name that later lines use instead of its full name. Lines can still use the full name too.
• Each participant can be declared once. Declaring it after a message has already named it is fine: the line sets its kind or alias, and the column stays where the first mention put it.
• Name participants as the reader knows them: "Shopper", "Payments API", "Orders DB".

MessagesCopy Anchor Link

Shopper->Shop: Pay for order
Shop-->Shopper: Order placed
Shop->>Queue: Order paid
Worker->Worker: Wait before retrying

A message can go from a participant to itself. In message text, \n starts a new line in the label.

Text after the colon is all message text, so it can hold URLs, paths and //: Client->API: GET https://api.example.com/v1.

Activation barsCopy Anchor Link

Client->API ++: GET /orders/42
API->DB: Load order
DB-->API: Order
API-->Client --: 200 OK

• ++ after the receiver starts the receiver's bar.
• -- after the receiver ends the sender's bar.
• Both can go on one message: ++ --.

You can also start or end a bar on a line of its own, with activate App and deactivate App. Ending a bar on a participant that isn't active is a warning in the Problems panel.

FragmentsCopy Anchor Link

alt card accepted
  Payments-->Shop: Payment confirmed
else card declined
  Payments-->Shop: Declined
end

par
  Shop->>Email: Send receipt
and
  Shop->>Warehouse: Pick order
end

loop up to 3 times
  Worker->Receiver: POST /webhooks
end

A fragment starts with its kind and an optional condition, and closes with end. The kinds are alt, opt, loop, par, break, critical and group. See Fragments for what each means.

• In an alt, each branch after the first starts with else and its condition.
• In a par, each branch after the first starts with and.
• The other kinds have one branch.
• Fragments can sit inside other fragments.

NotesCopy Anchor Link

note over App: Token cached for 5 minutes
note over App, Auth server: PKCE checked on every request
note left of User: On a phone
note right of Receiver
  Signed with HMAC-SHA256
  Replays rejected after 5 minutes
end note

• note over takes one participant, or several separated by commas, and spans them.
• note left of and note right of take one participant.
• For a note of several lines, leave out the colon, write the lines below, and close them with end note.

DividersCopy Anchor Link

== Delivery ==

A divider is a label between two ==, across the whole diagram. Use one to split a long interaction into phases.

QuotesCopy Anchor Link

Put a name in double quotes when it has characters the code would read otherwise, such as a colon, a comma, an arrow, a quote or //, or when it starts with a word that begins other lines, such as end, note or database.

"Users DB"->API: Query
"Billing: EU"->Ledger: Post entry
participant "Orders \"main\" DB" as Orders

Inside quotes, write \" for a quote and \\ for a backslash. Spaces alone don't need quotes: Orders DB->API: Query works.

CommentsCopy Anchor Link

// Happy path only for now
Client->API: GET /orders

A line that starts with // is a comment. The app ignores it, and keeps it in the text when the diagram changes. A // later on a line isn't a comment, so a message's text can hold it.

IdsCopy Anchor Link

Every participant and element has an id, such as Participant_Shop or Message_CreatePayment. Comments, the assistant and connected AI apps refer to elements by id. When you edit the code, the app keeps each element's id while it still says the same thing: a participant by its alias or name, a message while it has the same sender, receiver and text. So you can reorder lines and add new ones, and comments stay on their elements.

When a line has a mistakeCopy Anchor Link

If a line can't be read, the pane's header shows the message with its line number, and so does the Problems panel. The diagram keeps its last working version until you fix it.

One case reads without an error but not as you meant: a message with no colon, such as App->DB Find user, reads DB Find user as the receiver's name. If a participant appears that you didn't expect, check for a missing colon.

Import a fileCopy Anchor Link

You can bring in a sequence diagram written for Mermaid or PlantUML. In the Diagrams panel, open New diagram (the plus button) and choose Import Mermaid or PlantUML file…. The app reads .mmd, .mermaid, .puml, .plantuml, .pu and .txt files, A file whose first line is sequenceDiagram is read as Mermaid, and any other file as PlantUML.

The file becomes a new diagram, named after its title or the file. Parts a sequence diagram here can't show, such as styling, participant boxes or shapes other than participant, actor and database, are read as near as they can be. When something is left out, a message after the import names it. A file with no sequence diagram in it isn't imported, and the message says so.

Export a fileCopy Anchor Link

Open Export at the top right of the diagram. Pictures are under Image, text files under Code:

View Mermaid… and View PlantUML… at the bottom of the menu show the text read-only, with a button to copy it. In the Mermaid file, dividers become notes across the diagram and groups become shaded areas.

Full referenceCopy Anchor Link

The sequence code reference has the complete syntax on one page, exactly as the assistant gets it.