# danielgerlag/workflow-core architecture

> Architecture diagram of the GitHub repository danielgerlag/workflow-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danielgerlag/workflow-core
- Repository: https://github.com/danielgerlag/workflow-core

## Overview

Based on your review of the complete file tree and README, this is an advanced, modular .NET Standard library that implements a lightweight, embeddable workflow engine. The project—Workflow Core—is built to support long‐running processes (e.g., business workflows with human tasks, sagas with compensation, scheduled background tasks) and offers both a fluent API and JSON/YAML DSL for workflow definitions. It also provides a rich set of pluggable persistence, concurrency, queue, and search/index providers, as well as extensions for user/human workflows and a REST WebAPI.

##### Main Components
- Workflow Engine Core – The main library components (found in src/WorkflowCore) that orchestrate the creation, execution, and management of workflows. This includes components such as step execution, lifecycle event publishing, error handling, and concurrency control.
- DSL and Fluent API – The DSL components (src/WorkflowCore.DSL) and fluent builder classes which allow definitions via both code (fluent API) and external JSON/YAML files.
- Persistence Providers – A modular set of persistence implementations (located in the src/providers folder) for databases such as SQL Server, PostgreSQL, MongoDB, MySQL, Oracle, Sqlite, Redis, etc. These allow the state of the workflows to be stored and recovered.
- Queue and Event Handling – Components dealing with distributed locking, queue management, and event consumption. Look at the providers for RabbitMQ, SQL Server queues, and AWS or Azure provider integrations.
- Extensions – Additional functionality such as human workflow support (src/extensions/WorkflowCore.Users) and the WebAPI controller extension (src/extensions/WorkflowCore.WebAPI) that expose endpoints for interacting with the workflow engine.
- Background / Worker Services – Modules in the “Services” directories and background tasks (e.g., WorkflowConsumer, QueueConsumer, IndexConsumer) that continuously process scheduled commands, events, and queued work items.

##### Relationships and Data Flow
- Workflow engine core interacting with pluggable persistence providers. Indicate that the engine persists workflow state and execution pointers and uses the configured provider.
- Background service components (workers/pollers) that monitor workflow events and trigger re-entrant execution or error handling.
- For the extensions, show interactions where user workflow or REST API components call into the engine to start/monitor workflows.

##### Architectural Patterns and Design Principles
- Modularity/Pluggability – Highlight that many components (persistence, queue management, search indexing) are implemented as separate providers and extensions, allowing easy switching or extension.
- Separation of Concerns – The DSL and Fluent API are distinctly separated from the engine core; persistence and communication concerns are abstracted away via interfaces.
- Event-Driven / Pipeline Architecture – Illustrate that workflow steps are chained together and that the engine emits life cycle events, which are then handled by background processors.
- Error Handling and Compensation – Include elements for error handling, such as the retry saga patterns and compensation steps for sagas.

##### Additional Details You May Want to Capture
- The role of background tasks in executing long running or scheduled workflows. Include components like ExecutionPointerFactory, WorkflowConsumer, QueueConsumer, etc.
- The compensation mechanism in saga transactions. Include a node labeled “Saga & Compensation Workflow” that connects to specific steps like UndoTask1, UndoTask2, etc.
- The integration of persistence and search providers, to reflect how workflow state is maintained and queried over time.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Workflow Definition Layer
    subgraph "Workflow Definition"
        DSLAndFluentAPI["Fluent API/DSL"]:::dsl
    end

    %% Core Engine Layer
    subgraph "Core Engine"
        WorkflowEngineCore["Workflow Engine Core"]:::engine
    end

    %% Providers Layer
    subgraph "Providers and Queues"
        subgraph "Persistence Providers"
            SQLPersistence["SQL Server Persistence"]:::provider
            MongoPersistence["MongoDB Persistence"]:::provider
        end
        subgraph "Queue and Event Handling"
            RabbitMQQueue["RabbitMQ Queue Provider"]:::provider
            SQLQueue["SQL Server Queue Provider"]:::provider
        end
    end

    %% Extensions Layer
    subgraph "Extensions"
        HumanWorkflow["Human Workflow Extension"]:::extension
        RESTWebAPI["REST WebAPI Extension"]:::extension
    end

    %% Background Services Layer
    subgraph "Background Services"
        BackgroundServices["Background Services"]:::background
        WorkflowConsumer["Workflow Consumer"]:::background
        QueueConsumer["Queue Consumer"]:::background
        IndexConsumer["Index Consumer"]:::background
    end

    %% Connections
    DSLAndFluentAPI -->|"definesWorkflow"| WorkflowEngineCore
    HumanWorkflow -->|"callsEngine"| WorkflowEngineCore
    RESTWebAPI -->|"callsEngine"| WorkflowEngineCore

    WorkflowEngineCore -->|"persistsState"| SQLPersistence
    WorkflowEngineCore -->|"persistsState"| MongoPersistence
    WorkflowEngineCore -->|"queuesEvents"| RabbitMQQueue
    WorkflowEngineCore -->|"queuesEvents"| SQLQueue

    WorkflowEngineCore -->|"triggersEvents"| BackgroundServices
    BackgroundServices -->|"runs"| WorkflowConsumer
    BackgroundServices -->|"runs"| QueueConsumer
    BackgroundServices -->|"runs"| IndexConsumer

    %% Click Events
    click DSLAndFluentAPI "https://github.com/danielgerlag/workflow-core/blob/master/src/WorkflowCore.DSL"
    click WorkflowEngineCore "https://github.com/danielgerlag/workflow-core/tree/master/src/WorkflowCore"
    click SQLPersistence "https://github.com/danielgerlag/workflow-core/blob/master/src/providers/WorkflowCore.Persistence.SqlServer"
    click MongoPersistence "https://github.com/danielgerlag/workflow-core/blob/master/src/providers/WorkflowCore.Persistence.MongoDB"
    click RabbitMQQueue "https://github.com/danielgerlag/workflow-core/blob/master/src/providers/WorkflowCore.QueueProviders.RabbitMQ"
    click SQLQueue "https://github.com/danielgerlag/workflow-core/blob/master/src/providers/WorkflowCore.QueueProviders.SqlServer"
    click HumanWorkflow "https://github.com/danielgerlag/workflow-core/blob/master/src/extensions/WorkflowCore.Users"
    click RESTWebAPI "https://github.com/danielgerlag/workflow-core/blob/master/src/extensions/WorkflowCore.WebAPI"
    click BackgroundServices "https://github.com/danielgerlag/workflow-core/tree/master/src/WorkflowCore/Services/BackgroundTasks"

    %% Class Definitions
    classDef dsl fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef engine fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef provider fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef extension fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef background fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
