How we use Abstract Syntax Trees (ASTs) to turn Workflows code into visual diagrams
Cloudflare uses Abstract Syntax Trees (ASTs) to turn code-based Workflows into visual diagrams. Because Workflows execute dynamically—supporting parallel promises, awaits, loops, and conditionals—the system analyzes code structure and relationships to infer execution order. The resulting diagrams help developers understand workflow shape, especially as coding agents generate more application code. ## Why Code-Based Workflows Are Difficult to Visualize - Unlike declarative workflow builders, Cloudflare Workflows are ordinary code. - Workflows may contain: - `Promise` and `await` relationships - `Promise.all` for parallel execution - Loops and conditionals - Steps nested inside functions or classes - The runtime discovers and executes steps as it encounters them, rather than following a predefined sequence. - Unawaited steps can execute in parallel, while `await` establishes blocking dependencies. ## How Workflow Execution Works - A supervisor Durable Object, called the engine, starts for each workflow instance. - The engine dispatches execution to the user Worker. - When the Worker encounters `step.do`, control returns to the engine. - The engine executes the step, persists its result or error, and invokes the Worker again. - Since the engine does not inherently retain the complete intended order of steps, diagram generation must reconstruct those relationships from the source code. ## Parsing and Building the Workflow Graph - Cloudflare fetches the bundled Worker script at deployment time. - A parser converts the script into an Abstract Syntax Tree. - An internal service: - Identifies `WorkflowEntrypoints` - Finds calls to workflow steps - Builds and traverses an intermediate graph - Produces the final diagram through Cloudflare’s API - AST analysis tracks promises and `await` expressions to determine: - Which steps depend on one another - Which steps block execution - Which steps can run concurrently ## Handling Bundled and Minified JavaScript - Workers are generally bundled with tools such as esbuild and may be minified. - Minified output can obscure the original TypeScript structure and vary between bundlers. - The diagram system therefore has to recognize workflow patterns in dense, transformed JavaScript. - For example, several agent steps—such as summary, correctness, and clarity agents—may be created without awaiting them, indicating parallel execution. - The generated graph makes that concurrency visible even when the deployed code is difficult to read. Cloudflare’s AST-based approach provides a practical way to visualize dynamic, code-defined workflows. Developers can inspect how steps connect, branch, and execute in parallel directly from the dashboard, though the beta diagrams will continue to improve as more workflow patterns are supported.
Read original(opens in new tab)