Getting Started

This guide provides a comprehensive overview of Kuetix Engine's architecture, core concepts, and how to build effective workflows.

Installation

Complete Workflow

Follow these steps to set up and use the Kuetix Engine:

1. Add Engine as Go Module Dependency

# Create your project directory
mkdir myapp
cd myapp

# Initialize Go module
go mod init myapp

# Add Kuetix Engine as dependency
go get github.com/kuetix/engine@latest

2. Install kue CLI Tool

The kue CLI lives in its own repository at github.com/kuetix/kue and consumes the engine as a Go module dependency:

# Option A: Clone and use Makefile (recommended)
git clone https://github.com/kuetix/kue.git
cd kue
make install

# Option B: Clone and use install.sh
git clone https://github.com/kuetix/kue.git
cd kue
make build
./install.sh kue

# Verify installation
kue version

3. Initialize Your Project

Use kue create to generate project structure:

# Go back to your project directory
cd myapp

# Initialize a CLI application
kue create --name myapp --app-type cli

# Available types: cli, api, consumer, service

4. Generate Components

Use kue add for workflows, features, solutions, or modules:

# Generate a workflow
kue add workflow PaymentProcess

# Generate a feature
kue add feature Authentication

# Generate a solution
kue add solution OrderManagement

# Generate a module
kue add module payment

5. Generate Module Cache

kue update --verbose

6. Build Your Application

# Using go build
go build -o runtime/bin/myapp-cli ./cmd/cli

# Or using Makefile
make build-cli

7. Run Your Application

# Run a workflow
./runtime/bin/myapp-cli workflows/common/example.wsl

# With verbose output
./runtime/bin/myapp-cli -v workflows/common/example.wsl

Install CLI Tools Globally

For global access to CLI tools:

# Install kue CLI tool (separate repository)
git clone https://github.com/kuetix/kue.git
cd kue && make install

See the CLI Reference for detailed usage.

Core Concepts

Workflows

A workflow is a series of connected states that perform actions and make decisions. Workflows are defined using WSL (Workflow Specific Language) and executed by the workflow engine.

workflow example {
    start: Initial
    
    state Initial {
        action some/action.DoSomething() as Result
        on success -> Next(Result)
        on error -> HandleError
    }
    
    state Next(Result) {
        action another/action.Process(data: $Result)
        end ok
    }
    
    state HandleError {
        action response/Error(message: "Something went wrong")
        end error
    }
}

States

States are individual units of work within a workflow. Each state:

• Executes a single action (transition handler)
• Can capture results using as <Alias>
• Defines transitions to other states based on success/error

State Types:

Type	Description
initial	Entry point of the workflow (marked by start:)
normal	Standard processing state
final	Terminal state (uses end ok or end error)

Transitions

Transitions connect states and define the flow of execution:

state MyState {
    action some/action.Do()
    on success -> NextState        // On success, go to NextState
    on error -> ErrorState         // On error, go to ErrorState
}

Actions

Actions are the work performed in each state. They call transition handlers that implement the actual business logic:

action services/common/response.ResponseValue(message: "Hello", statusCode: 200)

Action path format: module/path/service.Method(args)

Architecture Overview

Layers

The engine is organized into distinct layers:

Application Layer (engine.go)

Entry point that initializes the application and coordinates all components.

Bootstrap Layer (boot/)

Handles system initialization, environment setup, and dependency injection configuration.

Workflow Engine Layer (engine/workflow/)

The heart of the engine that executes workflows:

• engine.go - Main workflow engine implementation
• worker.go - Worker that processes workflow states
• worker_context.go - Context management for workers
• wsl_integration.go - WSL to engine integration

WSL Compiler Layer (internal/wsl/)

The Workflow Specific Language compiler and runtime:

• lexer.go - Tokenizes WSL source code
• parser.go - Parses tokens into CST
• build_ast.go - Builds Abstract Syntax Tree
• ir.go - Intermediate Representation (Graph)

Module System (modules/)

Extensible plugin architecture for custom functionality.

Event System (event/)

Event-driven communication using an event bus pattern.

Execution Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Start()   │────▶│  LoadJson() │────▶│    Run()    │────▶│   Done()    │
│  Initialize │     │ Load Schema │     │  Execute    │     │  Finalize   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
                                    ┌───────────────────┐
                                    │   ProcessState()  │◀──┐
                                    │ Execute Transition│   │
                                    └───────────────────┘   │
                                               │            │
                                               ▼            │
                                    ┌───────────────────┐   │
                                    │    can(next)?     │───┘
                                    │  More States?     │
                                    └───────────────────┘

Project Structure

engine/
├── engine.go                # Top-level RunWorkflow entry point
├── boot/                    # Bootstrap and initialization
│   ├── bootstrap.go         # DI container setup
│   └── ...
├── cmd/                     # Binaries
│   └── mcp-server/          # MCP server binary
├── engine/                  # Core engine packages
│   ├── defines/             # Constants and shared types
│   ├── domain/              # Domain models
│   ├── helpers/             # Internal helpers
│   ├── manager/             # Sync/async workflow managers
│   ├── services/            # Internal services
│   └── workflow/            # Engine, worker, runners, execution
├── event/                   # Event system
│   └── bus.go               # Event bus implementation
├── internal/                # Internal packages
│   └── wsl/                 # WSL/SWSL compiler
├── modules/                 # Module registration (generated + hand-written)
├── runtime/                 # Runtime configuration
│   ├── etc/                 # Config profiles
│   └── workflows/           # Example workflow files
└── tests/                   # Test suites

Creating Custom Modules

Module Structure

modules/
└── my_module/
    └── transitions/
        └── my_transitions.go

Implementing a Transition

package transitions

import (
    "github.com/kuetix/engine/engine/domain"
    "github.com/kuetix/engine/engine/domain/interfaces"
    "github.com/kuetix/engine/engine/workflow"
)

type MyTransitions struct {
    workflow.BaseServiceTransition
}

func NewMyTransitions() interfaces.ServiceTransitions {
    return &MyTransitions{}
}

func (t *MyTransitions) MyMethod(p *workflow.WorkerSessionContext) domain.FlowStepResult {
    // Access properties
    value := t.Property("myKey")
    
    // Do something
    result := processValue(value)
    
    // Set response
    t.SetResponse(result, 200)
    
    return domain.FlowStepResult{
        Success:    true,
        StatusCode: 200,
    }
}

Registering the Module

After creating your module, regenerate the module cache and rebuild:

# Generate cache
kue update --verbose

# Rebuild application
make build-cli

This updates modules/di.go and modules/meta.go with your new transition handlers.

:::tip Auto-Cache in Generated Projects In projects created with kue create, the runner.sh script can automatically regenerate the cache before running workflows. :::

Configuration

Environment Profiles

Configuration files are organized by environment:

runtime/
└── etc/
    ├── development/
    │   └── engine.ini
    └── production/
        └── engine.ini

Configuration Options

type Config struct {
    Application    ApplicationConfig
    Server         ServerConfig
    Database       DatabaseConfig
    WorkflowConfig []WorkflowConfigItem
}

type ApplicationConfig struct {
    Name          string
    Env           string
    Debug         bool
    Locale        string
    LogFile       string
    ModulesPath   string
    WorkflowsPath string
}

Environment Variables

Key environment variables:

Variable	Description
NAME	Application name
APP_ENV	Environment (development/production)
CONFIG_PATH	Path to configuration directory

Execution Modes

Synchronous Execution

Runs a single workflow instance:

responses := workflow.RunOne(wfConfig, app, context)

Asynchronous Execution

Runs multiple instances concurrently:

workflow.RunBatch(wfConfig, app, &wg, resultChan, contexts...)

Restart Policies

Policy	Behavior
always	Always restart after completion
on-failure	Restart only on error
stop	Stop after first execution

Event System

Subscribe to workflow lifecycle events:

event.Bus.Subscribe("on:workflow:complete", func(wfConfig domain.WorkflowConfigItem, contexts []map[string]interface{}) {
    log.Printf("Workflow %s completed", wfConfig.Name)
})

Available events:

• on:workflow:before:run - Before workflow starts
• on:workflow:run:batch - Before batch execution
• on:workflow:complete - After workflow completes
• on:workflow:exit - When workflow exits

Next Steps

• WSL Documentation - Learn the Workflow Specific Language
• Examples - See real-world workflow patterns
• CLI Reference - Command-line options
• Configuration - Detailed configuration guide