Architecture Foundations

Swirls pairs a visual editor with a strongly typed backend so every workflow you design is reproducible, debuggable, and programmable. This page covers the high-level concepts that keep projects organized and executions trustworthy.

Data Model Overview

All persistent entities live in a single tenant-aware store. Each resource inherits shared metadata (creation timestamps, ownership context) so you can filter, audit, and govern activity without bolting on extra tables.

Projects

• Root container that scopes every other resource.
• Each project carries its own access context so shared workspaces in Swirls stay isolated from personal experiments.

Graphs

• Represent the DAG you run for a workflow.
• Reference their project and keep descriptive metadata so teams can search and reuse them.

Nodes

• Building blocks inside a graph.
• Capture the node type, configuration, and layout information used in the visual editor.
• Supported node families include decision, HTTP, LLM, and transformation; each enforces the properties it needs (e.g., prompts for LLM nodes, code for transformation nodes).

Edges

• Connect a sourceNodeId to a targetNodeId within the same graph.
• Optional label lets you document branches (e.g., yes/no from a decision node).

Forms

• Structured input definitions for a workflow.
• Store a schema alongside metadata so you can render the same contract anywhere—Swirls UI, embedded SDKs, or custom clients.

Triggers

• Represent external events that should invoke a workflow.
• Form triggers are available today; additional trigger types (webhook, schedule, agent) plug into the same structure.

Workflows

• Join a trigger to a graph and capture whether it is enabled.
• Provide a named entry point you can target from the dashboard, SDK, or API.

Execution Records

• Graph executions log each run with status, timestamps, payload, and results.
• Node executions track per-step input/output so you can pinpoint where a flow succeeded or failed.

Runtime Flow

1. Form submission (or manual trigger) produces a payload that matches the trigger configuration.
2. Workflow resolution finds the associated graph and builds the runtime plan.
3. Graph execution runs through nodes topologically, storing intermediate data in nodeExecutions.
4. Completion writes outputs to graphExecutions and unblocks any downstream automation.

Programmatic Access

Swirls exposes the same capabilities found in the UI through its public API and SDKs. You can manage graphs, forms, triggers, and workflows from your own codebase, invoke executions, and subscribe to progress updates.

Execution Isolation

• Transformation nodes run user-provided JavaScript in an isolated runtime, keeping your main process safe.
• HTTP nodes capture request and response metadata for auditability.
• LLM nodes track the configuration used for each call so you can reproduce results when needed.

Swirls’ architecture emphasizes traceability and composability: every artifact is stored as a first-class entity, validation happens automatically, and executions are logged in detail so you can iterate with confidence.