Visualizing Workflows

Understanding the structure of a complex workflow can be challenging just by reading code or JSON. Flowcraft includes a utility to generate Mermaid diagram syntax directly from a WorkflowBlueprint.

This makes it easy to visualize, document, and debug your workflows. Flowcraft provides multiple ways to visualize your workflows:

generateMermaid

The generateMermaid function takes a blueprint and returns a string of Mermaid flowchart syntax. Node labels include the node ID and, if present, the node's parameters for richer visualization.

import { createFlow, generateMermaid } from 'flowcraft'

const flow = createFlow('conditional-workflow')
	.node('fetch', async () => ({ output: { value: 10 } }))
	.node('check', async ({ input }) => ({
		action: input.value > 5 ? 'big' : 'small'
	}), { threshold: 5 })
	.node('process-big', async () => ({}))
	.node('process-small', async () => ({}))
	.edge('fetch', 'check')
	.edge('check', 'process-big', { action: 'big', condition: 'result.output > 0' })
	.edge('check', 'process-small', { action: 'small' })
	.toBlueprint()

const mermaidSyntax = generateMermaid(flow)
console.log(mermaidSyntax)

Rendering the Diagram

The output of generateMermaid will be:

flowchart TD
	fetch["fetch"]
	check["check<br/>params: {"threshold":5}"]
	process-big["process-big"]
	process-small["process-small"]
	fetch --> check
	check -- "big | result.output > 0" --> process-big
	check -- "small" --> process-small

When this syntax is rendered by a tool that supports Mermaid (like this documentation site, GitHub markdown, or the Mermaid Live Editor), you get a clear visual representation of your workflow:

This is particularly useful for building workflow editors, debuggers, or any application that needs to display workflows in a user-friendly graph format.

Notice how the action and condition from the edges are automatically added as labels to the connections in the diagram.

toGraphRepresentation

For programmatic visualization in user interfaces, the Flow class provides a .toGraphRepresentation() method that returns a UIGraph. This method:

• Simplifies complex patterns like loops and batches for cleaner UI display
• Replaces loop controllers with direct cyclical edges
• Replaces batch scatter/gather pairs with single representative nodes
• Preserves all essential node and edge information

import { createFlow } from 'flowcraft'

const flow = createFlow('my-workflow')
  .node('start', async () => ({}))
  .node('process', async () => ({}))
  .node('end', async () => ({}))
  .edge('start', 'process')
  .edge('process', 'end')
  .loop('my-loop', {
    startNodeId: 'start',
    endNodeId: 'end',
    condition: 'i < 10'
  })
  .batch('my-batch', async () => ({}), { inputKey: 'items', outputKey: 'results' })

const uiGraph = flow.toGraphRepresentation()
// Use uiGraph.nodes and uiGraph.edges to render in your UI

---

Visualizing your workflows is an invaluable tool for:

• Debugging: Quickly spot incorrect connections or logic flows.
• Documentation: Automatically generate up-to-date diagrams for your team.
• Onboarding: Help new team members understand the structure of complex processes.
• UI Integration: Build interactive workflow editors and visual debuggers.

Choose generateMermaid for static documentation and sharing, or toGraphRepresentation for dynamic, programmatic visualization in your applications.