Overview
ArcFlow is Surface's built-in workflow engine. Workflows are directed acyclic graphs of nodes — each node receives the output of its upstream nodes, runs its execute function, and passes a StepResult downstream. The engine handles scheduling, retries, gate suspensions, and parallel branches.
All nodes live in surface/src/lib/arcflow/nodes/ and are registered in index.ts. Adding a new node means writing one file and adding one line to the registry map.
Node interface
NodeHandler
Every node exports a NodeHandler — an object with a kind string and an async execute function.
import type { NodeHandler, WorkflowNode, StepResult, RunContext } from '../types'
export const myNode: NodeHandler = {
kind: 'my-node',
async execute(
node: WorkflowNode,
input: Record<string, unknown>,
ctx: RunContext
): Promise<StepResult> {
const cfg = node.config as { my_param?: string }
// ... do work
return { output: { result: 'value' } }
},
}
RunContext
The ctx argument carries everything the node needs to do its work without hitting the database directly.
| Field | Type | Description |
| runId | string | ID of the current workflow run |
| workflowId | string | ID of the parent workflow |
| version | number | Workflow version number |
| triggeredBy | string | Member ID or system identifier that started the run |
| payload | Record<string, unknown> | Original trigger payload (webhook body, manual input, etc.) |
| secrets | Record<string, string> | Tenant secrets map — use ctx.secrets['KEY'] instead of env vars |
| stepOutputs | Map<string, Record<string, unknown>> | Outputs of all previously completed steps, keyed by node ID |
| getStandingApprovals? | function | Returns active standing approvals for gate nodes |
| scheduleWait? | function | Suspends the run until a future ISO timestamp (used by wait node) |
StepResult
Return an object with an output map and an optional error string. A non-empty error marks the step as failed and stops the run unless the workflow has error-handling edges.
// Success
return { output: { id: '123', status: 'sent' } }
// Failure (stops the run)
return { output: {}, error: 'my-node: required field missing' }
Interpolation
Node config values are plain strings at rest. Before executing, call interpolate() from ./utils to resolve template tokens against the run context.
import { interpolate } from './utils'
// In execute():
const url = interpolate(cfg.url ?? '', input, ctx.secrets, ctx.payload, ctx.stepOutputs)
| Token | Resolves from |
| {'{{key}}'} | input — current step's merged upstream output |
| {'{{secret.NAME}}'} | ctx.secrets — tenant secret store |
| {'{{payload.key}}'} | ctx.payload — original trigger payload |
| {'{{steps.NODE_ID.field}}'} | ctx.stepOutputs — a prior step's output field |
Nested paths work: {'{{steps.step1.user.email}}'} traverses the output object. Unresolved tokens return an empty string — never throw.
Node catalog
All registered node kinds as of Oct 2026:
llm
Call ArcRouter with a model alias and prompt template
http
Outbound HTTP request with full method/header/body control
transform
Reshape data with a JavaScript expression
condition
Boolean branch — routes to true or false edge
switch
Multi-branch routing on a value match
gate
Human approval gate — suspends run until approved
email
Send transactional email via Resend
slack
Post message to Slack channel via webhook
discord
Post message or embeds to Discord webhook
ghl
GoHighLevel CRM operations (contacts, notes, pipeline)
notify
Internal Surface notification to a member
database
Read or write Supabase rows
postgres
Raw SQL query against the Surface database
graph-read
Query the neo4j Brain graph
schedule
Cron trigger entry point
wait
Suspend run until a future timestamp
parallel
Fan-out: run multiple branches concurrently
merge
Fan-in: wait for all parallel branches then combine outputs
foreach
Iterate a sub-workflow over an array
sub-workflow
Invoke another workflow as a step
qa-cycle
LLM quality check with retry until pass or max attempts
webhook-response
Emit a response body back to the triggering webhook caller
form
Collect structured input from a member mid-run
error
Explicit failure with a message — ends the run
note
No-op annotation node for documentation in the canvas
trigger and form are entry-point types — they are not executed as steps within a run.
Registration
Add a new node in two steps:
1. Create surface/src/lib/arcflow/nodes/my-node.ts exporting a NodeHandler.
2. Add it to index.ts:
import { myNode } from './my-node'
const registry = new Map<NodeKind, NodeHandler>([
// ... existing entries
['my-node', myNode],
])
Also add 'my-node' to the NodeKind union in types.ts.
Worked example
A minimal node that calls an external webhook and returns the response status:
import type { NodeHandler, WorkflowNode, StepResult, RunContext } from '../types'
import { interpolate } from './utils'
/**
* ping node - POST to a URL and return the HTTP status.
*
* Config:
* url - target URL (interpolated, required)
* payload - JSON body template (interpolated, optional)
*/
export const pingNode: NodeHandler = {
kind: 'ping',
async execute(node: WorkflowNode, input: Record<string, unknown>, ctx: RunContext): Promise<StepResult> {
const cfg = node.config as { url?: string; payload?: string }
const url = interpolate(cfg.url ?? '', input, ctx.secrets, ctx.payload, ctx.stepOutputs)
if (!url) return { output: {}, error: 'ping node: url is required' }
const body = cfg.payload
? interpolate(cfg.payload, input, ctx.secrets, ctx.payload, ctx.stepOutputs)
: undefined
try {
const res = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: body ?? '{}',
signal: AbortSignal.timeout(10_000),
})
return { output: { status: res.status, ok: res.ok } }
} catch (e) {
return { output: {}, error: `ping node: ${String(e)}` }
}
},
}