Show how a request moves

Flows, branches, a request turned away, and what the drawing shows where nothing moves.

A flow is the path a request takes through your system. archgram animates it inside the SVG, so the reader sees the request move from one part to the next. Without flows, the diagram stands still.

The browser asks the API for the user's orders. Before anything is read, the API has Clerk check the request's session. A request without a session is refused at the session check and the refusal goes back to the browser; signed in, it passes to the orders service, which reads the orders from Postgres. a request without a session: Browser → API → Session, refused at Session. signed in, it goes through: Browser → API → Session → Orders → Postgres.

A flow#

A flow has a name and its steps, each the id of a node.

yaml

flows:
  - { name: a visit, steps: [browser, api, db] }

Each step must be reached by an edge from the step before it. archgram checks this and says which step has no edge.

docs/diagrams/linkshort.archgram.yaml:12:44: flow `a visit` goes from `api` to `db`, but no edge goes from `api` to `db`

A branch#

A list inside the steps is a branch. Its nodes are reached at once, and their signals leave together.

yaml

flows:
  - { name: an order, steps: [api, queue, worker, [db, mail]] }

Each node of a branch must have an edge from the step before it, and an edge to the step after it, if there is one.

A request turned away#

stop names the node that refuses a flow. It must be the flow's last step, and a single node. A ✕ marks the line into it, the refusal travels back to where the flow began, and the node stays marked.

yaml

flows:
  - { name: a request without a session, steps: [browser, api, session], stop: session }
  - { name: "signed in, it goes through", steps: [browser, api, session, orders, db] }

A refused flow followed by one that passes the same node shows a retry. The node stays marked until the second flow passes it. The drawing above is this spec.

Several flows#

Flows play one after another, in the order the spec lists them. archgram times them itself. A signal moves at one speed, so a longer line takes longer, signals that meet at a node arrive together, and a refusal travels back before the next flow starts.

Where nothing moves#

A reader who turns motion off in their system sees the still image, and so does a printout or a PNG. still decides what the still image adds, so it carries the whole meaning.

`still`	What the still image shows
`none`	The diagram alone. The default.
`legend`	Each flow in words under the legend. Best for three flows or more.
`numbers`	Each step's number on the lines it takes. Best for one or two flows.

A screen reader hears each flow in words after the description, whichever you choose.

How the signal looks#

These fields change how a flow is drawn, never what it says.

Field	Values	What it changes
`signal`	`wire` (the default), `spark`, `arc`, `comet`, `dot`, `pulse`, `current`	How the moving request is drawn along the lines.
`border`	`spark` (the default), `drain`, `ring`, `afterglow`	How a card's border lights up as the request reaches it.
`wait`	`solid` (the default), `pending`	How a refused card waits for a later flow, its red border as drawn or marching round as dashes.
`glow`	`true` (the default), `false`	Whether the signal glows faintly, in `wire`, `spark` and `arc`.

The Examples use several of them.