Workflow Engine

A simple .NET 8 workflow engine that lets you define state machines and run workflow instances.

Quick Start

Prerequisites

• .NET 8 SDK
• python 3.8 or up for tests

Run the Application

dotnet run

The API will start on http://localhost:5291 The Tests run on http://localhost:5292

Run Tests

cd Tests
pip install -r requirements.txt
pytest test_workflow_engine.py -v

The test suite automatically starts a fresh app instance on port 5292 and cleans up JSON files between runs. Unfortunately, running the tests will clear the json file stored in /bin/Debug/net8.0 which destroys all stored data

API Endpoints

Refer to Swagger docs at localhost:5291/swagger for parameter requirements and response structures.

Parameter Formats

Create Workflow Definition (POST /workflows/create)

{
  "states": [
    {
      "name": "INITIAL_STATE",
      "isInitial": true,
      "isFinal": false,
      "enabled": true
    },
    {
      "name": "FINAL_STATE",
      "isInitial": false,
      "isFinal": true,
      "enabled": true
    }
  ],
  "actions": [
    {
      "name": "ACTION_NAME",
      "enabled": true,
      "fromStates": ["INITIAL_STATE"],
      "toState": "FINAL_STATE"
    }
  ]
}

Notes:

• id is auto-generated (GUID)
• name is required for states and actions
• isInitial, isFinal, and enabled are optional with defaults (true, false, true respectively)
• fromStates is a list of state names (not IDs)
• toState is a single state name (not ID)
• Exactly one state must have isInitial: true
• At least one state must have isFinal: true
• State and action names must be unique within the workflow

Data Models

Workflow Definition

{
  "id": "workflow-id",
  "states": [
    {
      "id": "state-id",
      "name": "State Name",
      "isInitial": true,
      "isFinal": false,
      "enabled": true
    }
  ],
  "actions": [
    {
      "id": "action-id",
      "name": "Action Name",
      "enabled": true,
      "fromStates": ["state-id"],
      "toState": "target-state-id"
    }
  ]
}

Assumptions & Limitations

Assumptions

• workflow ids are unique
• instance ids are unique
• Workflow instances start in the initial state
• Only one action can be executed at a time per instance

Known Limitations

• No authentication: All endpoints are public
• No endpoints for editing workflows Not possible to change the states or actions of existing workflows
• No timeout handling: Instances can stay in states forever
• No rollback capability: Can't undo state transitions
• No error recovery: No retry mechanisms

Shortcuts

• JSON files stored in bin/Debug/net8.0/
• Simple file-based persistence
• No logging framework
• No middleware pipeline

Project Structure

WorkflowEngine/
├── Models/
│   ├── State.cs                    # State model
│   ├── Action.cs                   # Action model  
│   ├── WorkflowDefinition.cs       # Workflow definition model
│   └── WorkflowInstance.cs         # Workflow instance model
├── Controllers/
│   ├── WorkflowDefinitionController.cs  # Workflow CRUD operations
│   ├── WorkflowInstanceController.cs    # Instance management
│   └── HealthController.cs              # Health check endpoint
├── Services/
│   └── WorkflowRepository.cs       # Data persistence layer
├── Tests/
│   ├── test_workflow_engine.py     # Python test suite
│   └── requirements.txt            # Python dependencies
├── Program.cs                      # Application entry point
├── WorkflowEngine.csproj           # Project file
└── README.md                       # This file

Development Notes

Architecture

• Minimal API: Uses .NET 8 minimal APIs
• Static classes: No dependency injection
• File-based storage: Simple JSON persistence
• Controller pattern: Organized endpoint handlers

Testing Strategy

• Integration tests: Python pytest suite
• Fresh instances: Each test run gets clean state
• Port isolation: Tests run on separate port (5292)
• Auto cleanup: JSON files cleared between runs

TODO

• tests could cover more cases
• delete/update workflows/instances