Core Concepts

Loopstack has three core building blocks — workflows, tools, and documents — plus a modular system of extensions for LLM providers, OAuth, sandboxes, and more.

Workflows

A workflow is a state machine. It defines a sequence of steps (transitions) that move through named states (places). Each transition runs TypeScript code — calling tools, saving documents, making decisions.


start → fetch_data → process → waiting_for_approval → approved → end

Key properties:

Transitions move between places and run your logic
Guards route conditionally (if X, go left; otherwise go right)
Wait transitions pause until a user clicks a button, a sub-workflow completes, or an API calls back
State is typed and persisted — survives pauses and restarts
Workflows can launch sub-workflows and receive their results via callbacks

Tools

A tool is a reusable unit of logic. It has a typed input schema (Zod), a description (used by LLMs), and an implementation. Tools are injected into workflows and called with await this.tool.call(args).

Tools serve two purposes:

Direct use — workflows call tools explicitly in transitions
LLM function calling — the LLM reads the tool’s description and schema, then decides when to call it

Built-in tools include LLM text generation, structured output, tool delegation, sandbox execution, and more. You create custom tools for your domain logic.

Documents

A document is a typed data object displayed in the Loopstack Studio UI. It has a Zod schema for validation and a YAML config for rendering.

Documents are how workflows communicate with users:

LlmMessageDocument — chat messages, from @loopstack/llm-provider-module
MarkdownDocument — rendered markdown
LinkDocument — clickable links to sub-workflows
ErrorDocument — error messages
Custom documents — forms, code editors, structured data displays

Documents are saved via this.documentStore.save() and automatically appear in the Studio UI.

Modules & Extensions

Loopstack is modular. The core framework provides the workflow engine, tools, and documents. Everything else is added through NestJS modules that you import as needed:

LLM Providers — Claude, OpenAI, or custom providers. Multi-provider support with runtime switching.
OAuth — Provider-agnostic OAuth 2.0 with Google and GitHub built-in.
Sandboxes — Run untrusted code in isolated Docker containers.
Secrets — Request and store API keys from users at runtime.
Agents — Built-in agent workflows with automatic tool-calling loops.

You only import what you use. Adding a capability is one line in your module imports.

How They Fit Together

Workflows call tools and save documents. That’s the core loop. Extension modules add capabilities like LLM access or OAuth that your tools and workflows can use.

NestJS Integration

Loopstack is built on NestJS. Workflows, tools, and services are standard NestJS providers:

Modules group related workflows, tools, and services
Constructor injection wires everything together
Decorators (@Workflow, @Tool, @Document, @Transition, @Guard) configure behavior

If you know NestJS, you already know how to structure a Loopstack project.

Next steps

Capabilities — feature matrix for quick validation
Getting Started — build your first workflow
Creating Workflows — deep dive into workflow patterns