FluxFlow

Code-First Workflow Engine for Modern Applications

</div>

📚 Table of Contents

🎯 What is FluxFlow?
🚀 Why Choose FluxFlow?
✨ Key Features
🔥 Quick Example
📊 Workflow Visualization
💡 Example Use Cases
⚡ Quick Start
🏗️ Architecture Overview
📋 Core Concepts
🔗 Resources & Links
❓ Frequently Asked Questions
🚧 Compatibility
🤝 Community & Support
👥 Contributors

🎯 What is FluxFlow?

FluxFlow is a lightweight, developer-friendly workflow engine that transforms how you build and manage business processes. Instead of wrestling with XML configurations or visual designers, you define workflows directly in your Java or Kotlin code – making them testable, maintainable, and type-safe.

💡 The FluxFlow Philosophy

Your code IS your workflow.
Transform your Java/Kotlin classes into powerful workflow steps, where properties become state and methods define transitions.

Unlike traditional BPMN engines that scatter logic across multiple artifacts, FluxFlow consolidates everything in your domain code. This means:

✅ No XML hell – Pure code-based workflows
✅ Type safety – Compile-time verification of your workflows
✅ Easy testing – Unit test your business logic naturally
✅ Version control friendly – Track changes like any other code
✅ IDE support – Full autocomplete, refactoring, and debugging

🚀 Why Choose FluxFlow?

| Traditional BPMN | FluxFlow | |----------------------|--------------| | 🔴 XML configuration files | 🟢 Pure Java/Kotlin code | | 🔴 Separated business logic | 🟢 Unified codebase | | 🔴 Hard to test | 🟢 Easy unit testing | | 🔴 Designer dependency | 🟢 IDE-native development | | 🔴 Runtime errors | 🟢 Compile-time safety | | 🔴 Complex debugging | 🟢 Standard debugging tools |

✨ Key Features

<details> <summary><strong>🏗️ Code-First Architecture</strong></summary>

Step Classes: Your POJOs become workflow steps
State Management: Properties hold step-specific data
Action Methods: Methods define transitions and business logic
Type Safety: Compile-time verification of workflow structure

</details> <details> <summary><strong>🔄 Workflow Components</strong></summary>

Workflow Data: Shared information across the entire workflow
Step Data: Step-specific state that can be queried and updated
Step Actions: Transitions and business logic execution
Jobs: Scheduled automatic execution (powered by Quartz)
Validation: Built-in Jakarta Bean Validation support

</details> <details> <summary><strong>🌱 Spring Boot Integration</strong></summary>

Dependency Injection: Full Spring context support
Auto-Configuration: Zero-configuration setup
Persistence: Automatic workflow state management
Testing: Comprehensive test utilities
Monitoring: Built-in metrics and health checks

</details> <details> <summary><strong>🧪 Testing & Quality</strong></summary>

Unit Testing: Test workflow logic like any other code
Mocking Support: Easy step and action mocking
Test Utilities: Specialized testing framework
Coverage: Full code coverage for workflows

</details>

🔥 Quick Example

Transform this pizza ordering process into executable code:

1. Add FluxFlow to your project:

<details> <summary><strong>Gradle (Kotlin DSL)</strong></summary>

dependencies {
    implementation("de.lise.fluxflow:springboot:0.2.0")
    implementation("de.lise.fluxflow:mongo:0.2.0") // For MongoDB persistence
}

</details> <details> <summary><strong>Gradle (Groovy)</strong></summary>

dependencies {
    implementation 'de.lise.fluxflow:springboot:0.2.0'
    implementation 'de.lise.fluxflow:mongo:0.2.0' // For MongoDB persistence
}

</details> <details> <summary><strong>Maven</strong></summary>

<dependency>
    <groupId>de.lise.fluxflow</groupId>
    <artifactId>springboot</artifactId>
    <version>0.2.0</version>
</dependency>
<dependency>
    <groupId>de.lise.fluxflow</groupId>
    <artifactId>mongo</artifactId>
    <version>0.2.0</version>
</dependency>

</details>

2. Define your workflow steps:

// 1️⃣ Add Pizza to Cart Step
@Step
class AddPizzaToCartStep(
    @Data 
    @NotEmpty(message = "Cart cannot be empty. Please add at least one pizza before checkout.")
    var pizzas: MutableList<Pizza> = mutableListOf()
) {
    @Action(beforeExecutionValidation = ValidationBehavior.AllowInvalid)
    fun addPizza(pizza: Pizza): AddPizzaToCartStep {
        // Add the pizza to cart
        pizzas.add(pizza)
        // Return to same step for more pizzas
        return AddPizzaToCartStep(pizzas)
    }
    
    @Action
    fun toCheckout(): CheckoutStep {
        // Calculate total and proceed to checkout with current pizzas
        val total = pizzas.sumOf { it.price }
        return CheckoutStep(pizzas, total)
    }
}

// 2️⃣ Checkout Step
@Step
class CheckoutStep(
    @Data val pizzas: List<Pizza>,
    @Data val total: BigDecimal
) {
    @Data var deliveryAddress: String = ""
    @Data var paymentMethod: String = ""
    
    @Action
    fun submitOrder(): Continuation<OrderConfirmation> {
        // Process order with pre-calculated total
        val confirmation = OrderConfirmation(
            orderId = UUID.randomUUID().toString(),
            pizzas = pizzas,
            total = total,
            deliveryAddress = deliveryAddress
        )
        
        // Workflow completes successfully
        return Continuation.end(confirmation)
    }
}

data class Pizza(val name: String, val price: BigDecimal)
data class OrderConfirmation(
    val orderId: String,
    val pizzas: List<Pizza>,
    val total: BigDecimal,
    val deliveryAddress: String
)

3. Test your workflow logic:

class PizzaOrderWorkflowTest {
    
    @Test
    fun `addPizza should add pizza to cart and return to same step`() {
        // Arrange
        val initialStep = AddPizzaToCartStep()
        val pizza = Pizza("Margherita", BigDecimal("12.99"))
        
        // Act
        val result = initialStep.addPizza(pizza)
        
        // Assert
        assertThat(result.pizzas).hasSize(1)
        assertThat(result.pizzas[0]).isEqualTo(pizza)
        assertThat(result).isInstanceOf(AddPizzaToCartStep::class.java)
    }
    
    @Test
    fun `toCheckout should transition to checkout step with current pizzas`() {
        // Arrange
        val pizzas = mutableListOf(
            Pizza("Margherita", BigDecimal("12.99")),
            Pizza("Pepperoni", BigDecimal("14.99"))
        )
        val step = AddPizzaToCartStep(pizzas)
        
        // Act
        val result = step.toCheckout()
        
        // Assert
        assertThat(result).isInstanceOf(CheckoutStep::class.java)
        assertThat(result.pizzas).hasSize(2)
        assertThat(result.total).isEqualTo(BigDecimal("27.98"))
    }
    
    @Test
    fun `submitOrder should create confirmation with pre-calculated total`() {
        // Arrange
        val pizzas = listOf(
            Pizza("Margherita", BigDecimal("12.99")),
            Pizza("Pepperoni", BigDecimal("14.99"))
        )
        val checkoutStep = CheckoutStep(pizzas, BigDecimal("27.98")).apply {
            deliveryAddress = "123 Main St"
            paymentMethod = "Credit Card"
        }
        
        // Act
        val result = checkoutStep.submitOrder()
        
        // Assert
        assertThat(result.isCompleted).isTrue()
        val confirmation = result.completionData as OrderConfirmation
        assertThat(confirmation.pizzas).isEqualTo(pizzas)
        assertThat(confirmation.total).isEqualTo(BigDecimal("27.98"))
        assertThat(confirmation.deliveryAddress).isEqualTo("123 Main St")
        assertThat(confirmation.orderId).isNotBlank()
    }
}

That's it! You now have a fully functional pizza ordering workflow with:

✅ Type-safe state management
✅ Decision logic with looping
✅ Built-in validation rules
✅ Comprehensive unit tests
✅ Automatic persistence (with Spring Boot)

📊 Workflow Visualization

Sample Workflow Process

Pizza ordering workflow: Add Pizza (addPizza/toCheckout actions) → Checkout → Submit

</div>

💡 Example Use Cases

FluxFlow is well-suited for various business scenarios:

🏢 Enterprise Applications

Employee onboarding/offboarding
Approval processes
Document workflows
Compliance procedures

💰 Financial Processing

Loan application processing
KYC/AML workflows
Trade settlement
Risk assessment flows

</td> <td width="50%">

🛒 E-Commerce Applications

Order fulfillment
Return processing
Inventory m

Fluxflow

Install / Use

README