Rail

This page is the output of npx flowfig docs rail. Your agent reads the same text.

Read this topic for a request lifecycle, an API call chain or a Mermaid sequenceDiagram.

A spec has three forms.

• The map (the default). The map shows the boxes and the edges. A packet moves along an edge in each beat.
• The map with a rail ("rail": true in props). The rail is a lifeline diagram under the map. It has one row for each message.
• The rail alone ("rail": "only"). Use it when the reader needs only the message order, for example when the document already has the map.

Rules for a rail:

• Put each message on an edge. Put each phase in a step. Put messages that run at the same time in one beat.
• Give each hop its real payload in data: "POST /login", "sid cookie".
• Mark a message that does not wait for an answer with "async": true on the hop. This rule covers every send to a queue or topic, every emitted event, and every call without await. The rail draws such a message dashed, with an async tag.
• Draw a reply as a hop back on the same edge, with "back": true.
• Draw an error reply the same way, with the error in data. Example: { "edge": "login", "back": true, "data": "401 bad_credentials" }.
• A call that stays inside one part (a hash check, a guard) is not a message. Put it in say or in a show row of that part.

A Mermaid sequenceDiagram maps this way:

• participant: a box.
• A->>B: text: an edge from A to B, and a hop with "data": "text".
• B-->>A: text (a reply): a hop on the same edge with "back": true.
• A-)B: text: a hop with "async": true.
• par ... and ... end: the hops of all branches in one beat.
• alt and opt: one step per path.

A pasted design wins over the async rule: keep each arrow as the Mermaid draws it. A->>B stays a plain hop, also for a send to a queue. If you think the design is wrong, say so in the reply.