Overview

Swirls is a visual workflow platform and headless runtime for Large Language Model applications. It helps teams move from prototype to production quickly by combining a node-based editor, isolated execution environment, and fully typed APIs you can embed anywhere.

Why Swirls

Core Concepts

Projects

• Logical container for everything you build.
• Every graph, form, trigger, and workflow is scoped to a single project so teams stay neatly partitioned.

Graphs & Nodes

• Graphs describe the data and AI workflow you want to run.
• Nodes are typed building blocks—decision, HTTP, LLM, and transformation—that carry structured configuration and can be reused across graphs.
• Edges connect nodes to control execution order and data flow.

Forms

• Forms define structured input your users (or agents) submit before a workflow runs.
• Each form stores a schema that Swirls validates automatically, keeping downstream steps predictable.

Triggers & Workflows

• A trigger represents the event that should execute a graph. Today, Swirls ships with form-based triggers.
• A workflow ties a trigger to a graph, along with metadata like name, description, and whether it’s currently enabled.
• You can switch triggers on or off, point them at new graphs, or duplicate them for new intake paths without rewriting automation.

Execution Tracking

• Every run produces graphExecutions and nodeExecutions records with timestamps, status, input, output, and error fields.
• The contract provides getExecution, listExecutions, and node-level subscriptions so you can monitor progress or build custom dashboards.

Typical Flow

1. Create a project and define a graph with the nodes your use case requires.
2. Add a form that captures the structured context your workflow needs.
3. Register a form trigger and map it to your graph via a workflow.
4. Use Swirls UI or the API to run the workflow—execution details are recorded automatically.
5. Embed the form or trigger workflow programmatically in your own application.

Headless First

The same capabilities available in the visual editor are exposed through Swirls’ public interfaces and SDKs:

• Manage graphs, forms, triggers, and workflows programmatically.
• Orchestrate runs from any client while keeping type safety and validation consistent.
• Stream execution updates so you can reflect progress inside your own product surfaces.

Swirls lets product teams iterate visually while giving engineers the control they need to ship reliable, AI-enhanced experiences. Dive into the next sections to see how the architecture comes together and how workflows and triggers bridge the gap between your UI and automated actions.