🧩 Basic Concepts

This section establishes the technical foundation you need to understand how Loopstack executes AI workflows and manages data flow.

Loopstack is built around several key concepts that work together to create powerful, flexible automations. Understanding these core components and their relationships is essential for building effective solutions.

Overview

Loopstack’s architecture is designed around five primary components:

1. Workspaces - Organizational containers that group related components
2. Pipelines - Orchestration units that coordinate workflow execution
3. Workflows - State machines that define business processes
4. Tools - Functional units that perform specific tasks
5. Documents - Structured data objects that store and display information

These components are configured through YAML definitions and work together to create automations that can range from simple tasks to complex business processes.

Workspaces

Workspaces contain pipelines, which in turn contain workflows. They serve as the top-level organizational unit in Loopstack.

Purpose: Provide organizational structure for your automations.

• Create logical groupings of related automations
• Control access and permissions at a high level

workspaces:
  - name: customer_support
    title: "Customer Support Automation"

Pipelines

Pipelines belong to a dedicated workspace and execute one or more workflows.

Purpose: Orchestrate the execution of workflows in a defined sequence or pattern.

• Define execution order (sequential or parallel)
• Coordinate data flow between workflows
• Provide execution entry points for users

pipelines:
  - name: customer_onboarding
    type: root
    workspace: customer_support
    sequence:
      - workflow: verify_customer
      - workflow: create_account
      - workflow: send_welcome_email

Workflows

Workflows are executed by pipelines and use tools to perform operations. They control the flow of a business process and manage its state.

Purpose: Define specific business processes as state machines with transitions between states.

• Model processes with states (places) and transitions
• Execute tools to perform actions
• Handle errors and decision points
• Manage the flow of data through the process

workflows:
  - name: example_workflow
    type: stateMachine
    transitions:
      - name: first_step
        from: start                             # Initial state
        to: processed                           # Target state
        call:
          - tool: my_tool                       # A tool to call during this transition
            arguments:                          # Tool arguments
              input: "data"
            as: RESULT              # Identifier for the tool output
 
      - name: second_step
        from: processed
        to: end                                 # Final state
        call:
          - tool: another_tool
            arguments:
              data: ${ RESULT.response.data }   # Access data from a previous step

Execution Process:

1. Workflow always starts in start state
2. Finds transition with matching from state
3. Executes specified tools with provided arguments
4. Exports results to variables if specified
5. Moves to to state
6. Repeats until reaching terminal end state

Tools

Tools are called by workflow transitions and can create or modify documents. They’re the functional units that do the actual work in Loopstack.

Purpose: Perform specific actions or operations within workflows.

• Execute defined operations (API calls, data processing, etc.)
• Accept input arguments
• Return structured responses
• Connect to external services and systems

tools:
  - name: customer_validator
    execute:
      - handler: ApiServiceHandler
        arguments:
          url: "https://api.example.com/validate"
          method: "POST"
          body: ${ FORM.input }

Documents

Documents are created and used by workflows and tools. They can store data persistently and provide interactive forms for user input.

Purpose: Store, display, and collect data throughout the automation process. They are also used to display information in the UI and interact with the user.

• Define data schemas for validation
• Provide UI components for user interaction
• Store information between workflow steps
• Serve as inputs and outputs for tools

documents:
  - name: customer_form
    schema:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
    ui:
      properties:
        name:
          label: "Customer Name"
        email:
          label: "Email Address"

How Components Work Together

Let’s examine how these components interact in a typical automation:

1. A workspace provides organizational structure
2. A pipeline within that workspace defines execution order
3. The pipeline executes one or more workflows
4. Each workflow consists of transitions between states
5. Transitions call tools to perform actions
6. Tools create or modify documents to store and display data

Example Flow

Data Flow Between Components

Data flows through the system in several ways:

1. Pipeline Context: Shared context object accessible by all workflows in a pipeline
2. Template Variables: Results from tool calls stored temporarily for subsequent steps and workflows
3. Documents: Persistent data storage with defined schemas
4. Transition Payloads: Data passed during manual transitions (typically from forms)

Variables are referenced using expressions like ${ VARIABLE_NAME.property } and can be passed between components.

State Persistence

Workflow state is automatically persisted, enabling:

• Execution resume after interruptions
• Human in the loop interaction
• Audit trails of workflow progress
• Historical execution analysis

Each transition creates a state checkpoint that can be inspected via the Studio interface.

Learn more about Core Components

Now that you understand the core concepts of Loopstack, you can explore each component in more detail:

• Workspaces - Learn how to organize your automations
• Pipelines - Discover pipeline types and configuration options
• Workflows - Explore workflow state machines and transitions
• Tools - See how to create and use different types of tools
• Documents - Learn about document schemas and UI components