README.md

Gorkflow

A powerful, type-safe workflow orchestration engine for Go with built-in state persistence, retries, and DAG-based execution.

📚 Full Documentation | Quick Start | Examples

Overview

Gorkflow is a lightweight, type-safe workflow orchestration engine that makes it easy to build complex workflows in Go. Using generics for compile-time type safety and a fluent builder API, you can create robust workflows with minimal boilerplate.

✨ Key Features

• 🎯 Type-Safe - Strongly-typed steps using Go generics
• ✅ Auto-Validation - Built-in input/output validation with struct tags
• 📊 DAG-Based - Sequential, parallel, and conditional execution
• 🔄 Smart Retries - Configurable retry policies with backoff strategies
• 💾 Persistent - Multiple storage backends (LibSQL/SQLite, in-memory)
• ⚡ Parallel - Execute independent steps concurrently
• 🎨 Conditional - Dynamic workflow paths based on runtime data
• 🏗️ Fluent API - Easy-to-use builder pattern

🚀 Quick Start

Installation

go get github.com/sicko7947/gorkflow

Example

package main

import (
    "context"
    "fmt"
    "github.com/sicko7947/gorkflow"
    "github.com/sicko7947/gorkflow/engine"
    "github.com/sicko7947/gorkflow/store"
)

// Define types
type Input struct {
    A int `json:"a"`
    B int `json:"b"`
}

type Output struct {
    Sum int `json:"sum"`
}

func main() {
    // Create a step
    addStep := gorkflow.NewStep(
        "add", "Add Numbers",
        func(ctx *gorkflow.StepContext, input Input) (Output, error) {
            return Output{Sum: input.A + input.B}, nil
        },
    )

    // Build workflow
    wf, _ := gorkflow.NewWorkflow("calc", "Calculator").
        Sequence(addStep).
        Build()

    // Execute
    store := store.NewMemoryStore()
    eng := engine.NewEngine(store)
    runID, _ := eng.StartWorkflow(context.Background(), wf, Input{A: 10, B: 5})

    // Get result
    run, _ := eng.GetRun(context.Background(), runID)
    fmt.Printf("Status: %s, Output: %s\n", run.Status, run.Output)
}

📖 Documentation

Visit our comprehensive documentation for:

• Getting Started - Installation, quick start, and tutorials
• Core Concepts - Workflows, steps, validation, state management
• Advanced Usage - Parallel execution, conditionals, error handling
• Storage Backends - LibSQL, in-memory stores
• API Reference - Complete API documentation

💡 Examples

Check out the examples/ directory for complete, runnable examples:

• Sequential - Basic sequential workflow
• Parallel - Parallel step execution
• Conditional - Runtime conditional logic
• Validation - Input/output validation
• LibSQL Persistence - Persistent storage

🏗️ Architecture

┌─────────────┐
│  Workflow   │  Define your workflow with type-safe steps
└──────┬──────┘
       │
       ↓
┌─────────────┐
│   Engine    │  Orchestrates execution with retries
└──────┬──────┘
       │
       ↓
┌─────────────┐
│    Store    │  Persists state (Memory/LibSQL)
└─────────────┘

🔧 Core Concepts

Type-Safe Steps

step := gorkflow.NewStep(
    "process",
    "Process Data",
    func(ctx *gorkflow.StepContext, input UserInput) (UserOutput, error) {
        // Fully type-safe - input and output are validated
        return UserOutput{UserID: "123"}, nil
    },
    gorkflow.WithRetries(3),
    gorkflow.WithTimeout(30 * time.Second),
)

Workflow Patterns

Sequential:

wf, _ := gorkflow.NewWorkflow("seq", "Sequential").
    Sequence(step1, step2, step3).
    Build()

Parallel:

wf, _ := gorkflow.NewWorkflow("parallel", "Parallel").
    Parallel(stepA, stepB, stepC).
    ThenStep(aggregateStep).
    Build()

Conditional:

condition := func(ctx *gorkflow.StepContext) (bool, error) {
    var flag bool
    ctx.State.Get("process_data", &flag)
    return flag, nil
}

wf, _ := gorkflow.NewWorkflow("cond", "Conditional").
    ThenStepIf(processStep, condition, nil).
    Build()

Storage Backends

Backend	Use Case	Setup
Memory	Development, Testing	store.NewMemoryStore()
LibSQL	Small-Medium Apps, Edge	store.NewLibSQLStore("file:./db")

See Storage Documentation for details.

📦 Requirements

• Go 1.21+ (uses generics)
• Optional: LibSQL client (for SQLite/Turso)

🤝 Contributing

Contributions welcome! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Extracted from the Tendor Email Agent project and refactored into a standalone workflow engine library.

📞 Support

• Documentation: https://cai139193541.gitbook.io/gorkflow/
• Issues: https://github.com/sicko7947/gorkflow/issues
• Discussions: https://github.com/sicko7947/gorkflow/discussions

---

Ready to build powerful workflows? Check out the Quick Start Guide! 🚀