Component reference

Actor / clientTakes part in a run

Starts a bounded request and receives its explicit response.

Ports

Settings

Use case — a shopper checks out

A shopper presses Buy in a web shop. The actor’s request port starts the journey and its response port receives the final answer — that round trip is the story most journeys tell. Set Request count to 5 and Interval (ms) to 200 and the same actor becomes a small burst of shoppers, with each request visible throughout the run.

The event output is for things the client sends without waiting — an analytics beacon dropped onto a queue, or an event published to a topic — so you can model “tell and move on” traffic from the same actor that makes requests.

The actor's response input is the optional return half of a request. When this actor or a scheduler is selected as a journey start, the selected output must have exactly one executable route; use separate source components for separate public starts.

In a run you’ll see: TOKEN_EMITTED · CALL_STARTED · RESPONSE_RECEIVED · CALL_COMPLETED

Scheduler / triggerTakes part in a run

Starts bounded scheduled work by emitting tick events at a fixed virtual interval.

Ports

Settings

Use case — a nightly report job

Nothing clicks a button at 2 a.m. — a schedule does. Here the scheduler stands in for a cron job: each tick drops a job onto a queue, and a worker service builds the report. Set Tick count to 3 and Interval (ms) to 60,000 to watch three job cycles play out — including what happens when one of them fails and retries.

The tick port sends events, so it plugs into anything that consumes events: a queue’s enqueue, a service’s event input, or a topic’s publish. Ticks are bounded — the run schedules up to the count you configure, after the Start offset (ms) and spaced by Interval (ms) in virtual time. Ticks beyond the run horizon are skipped; a compiler warning identifies that clipping. Downstream failures or safety limits can still stop the run. This is simulated scheduling, not a wall-clock cron job.

In a run you’ll see: TOKEN_EMITTED · QUEUE_ENQUEUED · QUEUE_DEQUEUED

Gateway / routerTakes part in a run

Routes requests through explicitly authored handler actions.

Ports

Settings

Use case — a public API edge

A mobile app calls your public API. Configure explicit handler actions on the gateway's request input: test a condition, call the selected service, then respond to the caller. Author the rejection path as well. Connections provide routes; the gateway does not infer routing rules or responses from them. Actions run in their authored order, and a false condition skips that action rather than ending the handler.

The responses flow back through the gateway’s response in and response out ports. You never draw those return connections yourself — they’re paired automatically when you draw the forward requests. Pairing defines where a response can go; a downstream reply resumes the calling handler, whose respond action must return the answer upstream. An empty handler does not route or reply.

In a run you’ll see: ROUTE_EVALUATED · ROUTE_SELECTED · RESPONSE_SENT

Round-robin backend calls

Add Call next backend to a Gateway handler to call one backend, wait for its response, and continue. Connect at least one synchronous request from requestOut, each with a paired response into responseIn. Conditional backend connections are rejected. No extra routing setting is required; finish the handler with a response to the original caller.

Backends are ordered by ascending connection priority, then stable connection ID. Each run starts at the first backend and cycles A/B/C/A. Retries stay on the selected backend; the next action execution selects the next one. Explicit Call actions keep their existing behavior. Potential routes include every eligible backend, while the trace identifies the connection actually selected. Try the Round-robin gateway starter for a three-backend example.

Service / functionTakes part in a run

Performs bounded compute and explicit downstream calls.

Ports

Settings

Use case — a checkout service orchestrating a purchase

The service is the workhorse of most diagrams. This checkout service receives an order on request in, then uses three different kinds of ports for three different conversations: call / return to ask the auth service a question and wait, data command / data result to read the orders database, and publish event to announce the finished order without waiting for anyone.

What the service does with these connections — and in which order — is its handler: call auth, load the order, publish the event, respond. To model a worker, author its event in handler to process a queue delivery and return ACK or NACK. Selecting worker in Operation alone does not create those actions.

In a run you’ll see: NODE_ENTERED · CALL_STARTED · CALLER_WAITING · RESPONSE_SENT · NODE_EXITED

TransformTakes part in a run

Passes request or record payloads through unchanged by default; authored actions can define explicit processing.

Ports

Settings

Use case — an explicit record-processing step

A legacy adapter emits a customer record through write record. A transform passes it to the profile service's data result. This makes a processing step visible, but the default identity mapping does not automatically validate or reshape the record. If the adapter first calls a database, its result must return to that caller before the handler sends the record onward.

In a run you’ll see: TRANSFORM_APPLIED

Cache / key-value storeTakes part in a run

Models explicit get, set and delete operations with lazy TTL.

Ports

Settings

Use case — cache-aside session lookup

A session service checks the cache before touching the database. The cache’s defining feature is that hit and miss are separate output ports, so the fast path and the slow path are two different routes you can see and follow. On a miss the service loads from the database. Once the result returns, the service resumes its handler and writes the record to the cache. The database result is a matched return to the caller, not a second write-back route.

The TTL setting gives every entry a virtual lifetime, and Key path says which part of the payload identifies the entry (like /sessionId). Preload entries through journey fixtures to start a run with a warm cache — or leave it cold and watch the misses.

In a run you’ll see: CACHE_LOOKUP · CACHE_HIT · CACHE_MISS · CACHE_WRITE · CACHE_EXPIRED

DatabaseTakes part in a run

Reads and deterministically mutates bounded journey fixture records. Get preserves the input payload and adds /record; query adds /records.

Ports

Settings

Use case — the orders system of record

The database holds the records your journey cares about. An order service reads through query / result and mutates through write / written — two explicit conversations, so reads and writes are separate arrows you can trace in the run. In the current catalog, Read operation chooses get or query and Write operation chooses insert, update, upsert, delete, or Atomic batch against the configured collection. The defaults are get and upsert.

Records come from your journey’s fixtures — you decide exactly which rows exist before the run starts, which is what makes runs repeatable. Writes during the run show up as state patches you can inspect afterwards.

For a write, Record path is a JSON Pointer to the object that should be stored, and Key path is evaluated inside that object to find its stable key. With {"job":{"jobId":"job-1001"}}, use /job and /jobId. An empty record path selects the whole incoming value. Connect get and query to the query port; connect insert, update, upsert, and delete to the write port. A get result is added at /record; a query result is added at /records.

Atomic batch — all writes succeed together

Choose Atomic batch under Write operation for 1–32 ordered insert, update, upsert, or delete rows. Each row selects a record from the incoming payload with a JSON Pointer. All rows use this database's collection and key path; a delete row selects an object containing its key. Later rows see earlier staged writes, so insert-then-update works. Updates replace the record, so supply the complete intended object.

Connect the caller to writeIn and return through writtenOut. The database commits one state update only when every row succeeds and preserves the incoming payload. On the first failure, all staged writes are discarded, the trace identifies the failed row, and the existing database failure code reaches the caller's catch. Rolled-back rows emit no successful mutation evidence.

Batch writes use the intrinsic database handler: custom writeIn actions and catches are rejected. Prepare the payload, call the database, and respond in the service; handle recovery there too. A batch executes in one scheduler operation, with no intermediate calls, waits, or visible partial state. General transactions across calls or collections, isolation levels, and Begin/Commit/Rollback actions are not modeled. The Atomic database batch starter includes successful and rolled-back journeys.

In a run you’ll see: DB_READ · DB_RESULT · DB_MUTATION · DB_TRANSACTION_COMMITTED · DB_TRANSACTION_ROLLED_BACK · STATE_PATCH_APPLIED

Object storageTakes part in a run

Stores opaque objects behind explicit put, get and delete operations; tokens carry object references, never blob bytes.

Ports

Settings

Use case — an image upload pipeline

An upload API stores a photo, and a thumbnailer fetches it later. Object storage models the S3-style half of that story: put stores an object and acknowledges through stored; get looks one up and branches — object when it exists, missing when it doesn’t — so the not-found path is a real route, just like a cache miss.

In a run you’ll see: OBJECT_PUT · OBJECT_GET · OBJECT_MISSING · OBJECT_DELETED

QueueTakes part in a run

Models bounded competing consumers, retries and explicit dead-letter routing.

Ports

Settings

Use case — a fulfilment worker with retries and a DLQ

Checkout finishes and hands fulfilment to a queue so the customer never waits on it. The queue dispatches each message to its single consumer — the worker — which reports back through ACK or NACK. A NACK sends the message back for another attempt after the configured backoff; when Maximum attempts runs out, the message takes the DLQ route instead of retrying forever.

The dispatch port accepts one connection, so the queue sends work to one consumer. Consumer slots controls how many deliveries that consumer may have active at once; it does not add more dispatch connections. Maximum attempts includes the first delivery, so a value of 3 permits the initial attempt plus two retries. Watching a message bounce through MESSAGE_REQUEUED into MESSAGE_DEAD_LETTERED is one of the most instructive stories Graphrun can tell.

In a run you’ll see: QUEUE_ENQUEUED · QUEUE_AVAILABLE · QUEUE_DEQUEUED · MESSAGE_ACKED · MESSAGE_REQUEUED · MESSAGE_DEAD_LETTERED

Topic / event busTakes part in a run

Broadcasts one published event to every subscription, forking a correlated child token per subscriber with recorded lineage.

Ports

Settings

Use case — fanning out an order-placed event

When an order is placed, three unrelated parts of the system care: email wants to confirm it, analytics wants to count it, loyalty wants to award points. Instead of the checkout calling all three, it publishes one event to a topic. Every connection drawn from the topic’s deliver port is a subscription, and each subscriber receives its own copy.

Each subscription receives its own copy of the event. Want a subscriber to get retries and a dead-letter path? Send that subscription to a queue first.

In a run you’ll see: TOPIC_PUBLISHED · TOKEN_FORKED · TOKEN_COMPLETED

Timer / delayTakes part in a run

Advances virtual time and resumes through an explicit output.

Ports

Settings

Use case — an explicit pause in the flow

Real systems are full of deliberate waits: a cool-down before a retry, a grace period before an escalation. The timer makes that wait a visible box in the diagram. A request arriving at request advances the run’s virtual clock by the configured duration, then continues through response — nothing hidden, no implicit delays.

The current ports carry a request and its response, so the timer keeps the caller’s synchronous interaction paired while advancing virtual time. In the run you can watch the virtual clock jump: the wait costs virtual time, never real time. Older timer graph versions may expose the equivalent start / elapsed control ports.

In a run you’ll see: WAIT_STARTED · WAIT_COMPLETED

Join / aggregatorTakes part in a run

Waits for correlated branch arrivals and lets one satisfying token continue once its policy is met, completing earlier arrivals at the barrier.

Ports

Settings

Use case — scatter-gather price quotes

A travel site asks two suppliers for a price at the same time and can only answer once both quotes are in. The fan-out half is a topic; the fan-in half is the join. Each supplier’s answer arrives at branch, and the join waits at the barrier until its policy is met — all branches, any branch, or an exact count (a quorum). Then the story continues through joined.

Graphrun keeps branches from the same request together, so two shoppers' quotes never mix. The branch that satisfies the policy is the one that continues.

In a run you’ll see: JOIN_ARRIVED · JOIN_SATISFIED · JOIN_TIMED_OUT · TOKEN_JOINED

Workflow / sagaTakes part in a run

Runs graph-derived steps sequentially as a durable saga, answering its caller once every step completes.

Ports

Settings

Use case — an order saga, step by step

Placing an order really means several things in a row: reserve the stock, charge the payment. The workflow receives the original request on start, then drives each outgoing step connection as one sequential step — the connection priorities set the order. Each step is an ordinary synchronous call whose answer returns on step result; when the last step completes, the workflow answers its caller through completed.

In a run you’ll see: WORKFLOW_STARTED · WORKFLOW_STEP_STARTED · WORKFLOW_STEP_COMPLETED · WORKFLOW_STEP_FAILED · WORKFLOW_COMPLETED · WORKFLOW_FAILED · WORKFLOW_COMPENSATED

External dependency / terminalTakes part in a run

Models a fixed-latency dependency that answers synchronous calls with a configured success or failure outcome.

Ports

Settings

Use case — a payment provider you don’t control

Your checkout calls a payment provider, but the provider’s internals aren’t your story — only its answers are. The external dependency stands in for it: after the latency you choose, success mode replies through the matching interaction, while failure mode fails with the named outcome. Flip one setting and the same diagram tells the sad-path story — what your system does when payments are down.

Its event input also makes it a terminal sink: point a queue’s DLQ or any fire-and-forget event at it to give a story an explicit, named ending — “lands in ops audit” — instead of trailing off the edge of the diagram.

The current boundary also exposes callback and publish ports:request out can start a callback request, response in receives its return, event out publishes an event, and command out sends a write command. The intrinsic fixed-outcome behavior applies to an untouched request in: success needs its matching response out route; failure raises the configured outcome and does not use an error output. Other ports need authored handlers.

In a run you’ll see: RESPONSE_SENT · ERROR_RAISED

Diagram linkTakes part in a run

References another diagram in this workspace as a typed boundary; answers callers with a configured outcome and navigates to the linked diagram in the editor.

Ports

Settings

Use case — decomposing a big estate into diagrams

A real system is many diagrams, not one enormous canvas. A diagram link stands in for another diagram in the workspace: your order flow can point to Accounts without redrawing it. Select the node, choose the target diagram, then use Open to visit it. Graphrun leaves a trail back to the original diagram.

During a run, the link acts as a boundary with the success, failure, outcome, and delay you set on the link itself. It does not run the contents of the other diagram. This keeps the current story focused and predictable.

On an untouched request, success follows the matching response out route, or the first response route when no interaction match is available; if there is no response route, the token completes. Failure takes the first error out route when one is connected and otherwise ends the token with the configured outcome. An empty or malformed target ID is shown as an advisory unlinked/broken state; it does not make the host graph's pure configuration validation fail.

If the target is removed or you lose access to it, the node shows a broken-link state. The rest of the current diagram can still be opened, saved, and run.

In Present mode, a diagram link is a labeled boundary: the viewer cannot open the linked diagram from presentation. The public share page currently shows only access and publication metadata, not the diagram or linked content.

In a run you’ll see: RESPONSE_SENT · ERROR_RAISED

Group / boundaryVisual helper

Organizes trust zones, regions, systems or teams without executing.

Settings

Use case — showing who owns what

A diagram that mixes two teams’ services needs boundaries. Draw a group around the payments components and label it — reviewers instantly see ownership, trust zones, or regions. Collapse a group to hide its children while you focus elsewhere; expand it when the detail matters again. Groups never execute and never change a run.

Note / legendVisual helper

Adds plain-text documentation without affecting behavior.

Settings

Use case — explaining the diagram to the next reader

Notes hold the things a diagram alone can’t say: assumptions (“charges are idempotent”), pointers (“see the retry journey”), or a legend for your labels — as in the figure above. Note text is always plain text: it’s never executed, never rendered as markup, and never affects a run.

The note text is limited to 2,000 characters and preserves line breaks. Fit canvas note to content grows the note vertically so the plain text remains visible; when it is off, you can set the note's width and height directly. The optional inspector description is context for editors and is not shown on the canvas.