Architecture
Execution & Data Flow
How a workflow run moves from trigger to handlers to logs and cost metering.
A workflow goes through the same lifecycle whether it's triggered by a button, a webhook, a schedule, or an inbound poll.
Lifecycle
flowchart LR
classDef step fill:#00D4AA,stroke:#0F766E,color:#06302B
classDef data fill:#3B82F6,stroke:#1E40AF,color:#fff
classDef gate fill:#FF6B35,stroke:#C2410C,color:#fff
S1["Build<br/>canvas"]:::step --> S2{"Validate<br/>reference checks"}:::gate
S2 --> S3["Save<br/>blocks + edges"]:::data
S3 --> S4["Deploy<br/>immutable version"]:::step
S4 --> S5["Bind trigger<br/>webhook · schedule · poll"]:::step
S5 --> S6["Execute<br/>resolve inputs → handlers"]:::step
S6 --> S7["Logs + cost<br/>per-block metering"]:::dataWhat happens during a run
sequenceDiagram
participant T as Trigger
participant A as API
participant S as Serializer
participant X as Executor
participant H as Handler
participant L as LLM / Integration
participant D as Database
T->>A: Fire (webhook / schedule / manual)
A->>S: serialize(workflow)
S->>S: Build graph + topological sort
S-->>A: Execution plan
A->>X: execute(plan)
loop For each block
X->>H: handle(block, inputs)
alt AI / Integration block
H->>L: Provider call
L-->>H: Result
else Data block
H->>D: Query / insert
D-->>H: Rows
end
H-->>X: Block output (stored in context)
end
X->>D: Write execution log + cost
A-->>T: Result (streamed when applicable)Key properties
- Topological execution — blocks run in dependency order;
parallelandloopblocks spawn isolated sub-contexts that share a trace ID. - Typed dispatch — each block resolves to one of 30 handlers behind a single interface, so the engine is open to new block types without core changes.
- Streaming — AI blocks stream tokens back over Server-Sent Events; the editor shows live output as a run progresses.
- Cost metering — every block records input/output tokens and cost into the execution log, which the Usage page reads.
Sync vs async
User-initiated runs execute synchronously within the request. Triggered and long-running workflows are dispatched to Cloud Tasks and run in a background function, so they aren't bound by the request timeout.
Synchronous runs are bound by the platform request timeout. For workflows that may run longer, prefer a webhook or scheduled trigger, which dispatch asynchronously.