Generating Visual Workflow Diagrams from Dynamic Code using ASTs

Cloudflare Workflows is a durable execution engine designed for long-running processes, enabling features like chained steps, retries, and state persistence. Unlike traditional workflow builders that rely on declarative configurations (e.g., JSON/YAML), Cloudflare Workflows are written directly in code, supporting dynamic execution patterns such as Promises, loops, and conditionals. The article focuses on the system developed to generate visual diagrams for these code-driven workflows, which is crucial for understanding complex execution flows and debugging.

Dynamic vs. Static Workflow Execution

Workflow engines typically operate under either static (sequential) or dynamic execution models. Cloudflare Workflows adopt a dynamic model where steps execute as the runtime encounters them. Unawaited steps run in parallel, giving developers significant flexibility in flow control without needing explicit wrappers. The workflow engine, implemented as a Durable Object, orchestrates step execution, persisting results and managing retries. This dynamic nature, however, complicates static analysis for diagram generation as the engine doesn't inherently know the complete step order beforehand.

Architectural Handoff

1. A "supervisor" Durable Object (the engine) is spun up for each workflow instance.
2. The engine triggers a user Worker via dynamic dispatch, passing control.
3. When the Worker runtime encounters a `step.do` call, execution is passed back to the engine.
4. The engine executes the step, persists its result (or error), and re-triggers the user Worker.

Leveraging ASTs for Diagram Generation

To overcome the challenge of visualizing dynamic code, Cloudflare fetches the workflow script at deploy time (after bundling and minification) and uses an Abstract Syntax Tree (AST) parser. The AST allows static analysis to derive the workflow's structure, tracking `Promise` and `await` relationships to identify parallel execution, blocking operations, and overall step connectivity. This process involves generating an intermediate graph from the AST and then mapping it to a predefined set of workflow node types for rendering.

Tracking Relationships and Complex Patterns

Accurately tracking step and function relationships is critical. The system collects both function and step names, even when steps are wrapped in functions, defined as functions, or dynamically called. For functions, a subgraph is created to determine if it contains direct or indirect step calls; leaf functions without any step involvement are trimmed. The parsing logic also accounts for various control flow patterns, including different types of loops (`for...of`, `while`, `map`, `forEach`), branching (`switch`, `if/else`, ternary operators), and error handling (`try/catch/finally`).

const summaryPromise = step.do("summary agent", async () => { /* ... */ });
const correctnessPromise = step.do("correctness agent", async () => { /* ... */ });
const clarityPromise = step.do("clarity agent", async () => { /* ... */ });
// All three 'step.do' calls are executed in parallel due to Promises