Flow System

Workflows As Ordered Node Graphs

A flow is the core execution unit in IAI. It is a set of nodes connected in a directed graph that the runtime can validate, execute, retry, and observe.

What Is A Flow

A flow is a workflow composed of ordered actions. The platform stores a graph definition, validates it, then turns it into execution steps.

Practical rule

If it cannot be serialized as nodes and edges, it is not yet a first-class flow artifact.

Flow Structure

{
  "nodes": [],
  "edges": []
}

The shape stays intentionally small. Complexity belongs inside node configuration, not in ad hoc flow-level nesting.

Node Types

`input`

Introduces data or user-provided values into the workflow.

`condition`

Evaluates a branch and chooses execution direction.

`transform`

Changes data shape or computes a derived payload.

`output`

Produces the terminal result of a flow.

`http`

Calls external HTTP services or internal APIs.

`ai` (future)

Reserved for model prompts, inference actions, or agentic steps.

Execution

Create Execution

The API or UI creates a run record linked to a flow definition.

Run

The runtime maps graph state into ordered node execution and stores logs.

Store Result

The final output and side-effects become part of execution history.

{
  "flowId": "flow_123",
  "status": "completed",
  "steps": [
    { "nodeId": "input-1", "status": "ok" },
    { "nodeId": "transform-1", "status": "ok" },
    { "nodeId": "output-1", "status": "ok" }
  ],
  "result": {
    "message": "Flow completed"
  }
}

UI Flow Builder

flow.iai.one is the current builder surface.

Drag & Drop

Compose nodes quickly without writing flow JSON by hand.

Preview

Inspect node configuration and flow structure before execution.

Run

Execute a draft and inspect runtime output with low friction.

Flow To Mail Integration

One of the first practical use cases is sending flow outputs into the communication layer.

{
  "action": "mail.send",
  "to": "operator@example.com",
  "subject": "Flow completed",
  "body": "Execution output is ready."
}

System pattern

Flows compute. Mail delivers. App surfaces review. Keeping those responsibilities separate prevents product boundaries from collapsing into one giant surface.