Skip to content

Event Storming

This page documents the Event Storming of the Workflow Engine module. It maps every domain event, command, aggregate, and policy extracted directly from the source code.

The Workflow Engine is structured around two event streams:

  • Domain events — produced by aggregates (Process, StepExecution) and consumed internally via the outbox pattern.
  • Integration events — exchanged with external systems (workers, API callers) via Kafka or Spring embedded events.
flowchart TD
    classDef evt fill:#FF8C00,color:#fff,stroke:#CC6000,font-weight:bold
    classDef cmd fill:#1565C0,color:#fff,stroke:#0D47A1
    classDef agg fill:#F9A825,color:#000,stroke:#F57F17,font-weight:bold
    classDef pol fill:#6A1B9A,color:#fff,stroke:#4A148C
    classDef ext fill:#B71C1C,color:#fff,stroke:#7F0000
    classDef sch fill:#37474F,color:#fff,stroke:#263238

    EXT(["API / Sistema Externo"]):::ext
    WRK(["Worker Externo"]):::ext
    SCH(["TimeoutScheduler"]):::sch

    PCR(["ProcessCreationRequested"]):::evt
    PCRH["ProcessCreationRequestedEventHandler"]:::pol
    CP["CreateProcessUseCase"]:::cmd
    PA[/"Process"/]:::agg
    PCE(["ProcessCreated"]):::evt
    PCEH["ProcessCreatedEventHandler"]:::pol
    SPS["StartProcessUseCase"]:::cmd
    SOP["StepOverProcessUseCase"]:::cmd

    SEA[/"StepExecution"/]:::agg
    TER(["TaskExecutionRequested"]):::evt
    TERH["StepExecutionRequestedEventHandler"]:::pol
    SSEU["StartStepExecutionUseCase"]:::cmd

    TSC(["TaskStatusChanged"]):::evt
    TSCH["TaskStatusChangedEventHandler"]:::pol
    USE["UpdateStepExecutionUseCase"]:::cmd
    SESC(["StepExecutionStatusChanged"]):::evt
    SESCH["StepExecutionStatusUpdatedEventHandler"]:::pol
    PUU["ProcessUpdateStepExecutionUpdateUseCase"]:::cmd

    TCR(["TimeoutCheckRequested"]):::evt
    TCRH["TimeoutCheckRequestedEventHandler"]:::pol
    CTO["CheckTimeoutUseCase"]:::cmd
    TCANR(["TaskCancellationRequested"]):::evt

    CPUC["CancelProcessUseCase"]:::cmd

    TLE(["TaskLogEmitted"]):::evt
    TLEH["TaskLogEmittedEventHandler"]:::pol
    RLM["RegisterLogMessageUseCase"]:::cmd
    TRC(["TaskResourceCreated"]):::evt

    %% Flujo 1: Creación de Proceso
    EXT -->|crea proceso| PCR
    PCR --> PCRH --> CP --> PA -->|emite| PCE
    PCE --> PCEH
    PCEH --> SPS
    PCEH --> SOP

    %% Flujo 2: Ejecución de Paso
    SOP --> SEA
    SEA -->|emite| TER --> TERH --> SSEU --> WRK

    %% Flujo 3: Feedback del Worker
    WRK -->|reporta estado| TSC
    TSC --> TSCH --> USE --> SEA
    SEA -->|emite| SESC --> SESCH
    SESCH --> PUU
    SESCH -->|siguiente paso| SOP

    %% Flujo 4: Timeout
    SCH -->|periódico| TCR --> TCRH --> CTO --> SEA
    SESCH -->|retry| SEA
    SESCH -->|timeout| TCANR --> WRK

    %% Flujo 5: Cancelación
    EXT -->|cancela| CPUC --> TCANR

    %% Flujo 6: Logs y Recursos
    WRK -->|log| TLE --> TLEH --> RLM
    WRK -->|recurso| TRC

Colour legend:

  • Orange — Domain / integration events
  • Blue — Commands / Use Cases
  • Yellow — Aggregates (Process, StepExecution)
  • Purple — Policies / Event Handlers
  • Red — External systems (API caller, Worker)
  • Dark grey — Scheduler

An external system or API sends ProcessCreationRequested. The engine creates a Process aggregate, which emits ProcessCreated. The handler then starts every eligible entry step — the START roots complete instantly (fanning the flow out to their successors) and WAIT_FOR_MESSAGE roots arm their wait.

ProcessCreationRequested
→ ProcessCreationRequestedEventHandler
→ CreateProcessUseCase
→ Process.create() emits ProcessCreated
→ ProcessCreatedEventHandler
→ StartProcessUseCase + StepOverProcessUseCase

StepOverProcessUseCase creates a StepExecution and starts it. The aggregate emits TaskExecutionRequested, which is delivered to the worker.

StepOverProcessUseCase
→ StepExecution.start() emits TaskExecutionRequested
→ StepExecutionRequestedEventHandler
→ StartStepExecutionUseCase
→ Worker

The worker reports the outcome via TaskStatusChanged. The engine updates the step, emits StepExecutionStatusChanged, and either advances to the next step or completes the process.

TaskStatusChanged (from Worker)
→ TaskStatusChangedEventHandler
→ UpdateStepExecutionUseCase
→ StepExecution.updateStatus() emits StepExecutionStatusChanged
→ StepExecutionStatusUpdatedEventHandler
→ ProcessUpdateStepExecutionUpdateUseCase
→ StepOverProcessUseCase → (next step — loop to Flow 2)

TimeoutScheduler fires periodically. If a step has exceeded its timeout, the step is marked TIMEOUT. Depending on configuration, the engine retries the step or starts a compensation step.

TimeoutScheduler
→ TimeoutCheckRequested
→ TimeoutCheckRequestedEventHandler
→ CheckTimeoutUseCase
→ StepExecution emits StepExecutionStatusChanged(TIMEOUT)
→ StepExecutionStatusUpdatedEventHandler
├─ if retries available → StepExecution (loop to Flow 2)
├─ if compensation step → compensation StepExecution (loop to Flow 2)
└─ otherwise → Process marked ERROR
+ TaskCancellationRequested → Worker

An actor (UI, MCP tool, or your own code) invokes CancelProcessUseCase directly — there is no upstream cancellation event with a handler. The engine sends TaskCancellationRequested to any running worker. The worker responds with TaskStatusChanged(CANCELLED), which re-enters Flow 3.

CancelProcessUseCase.handle(new CancelProcessCommand(processId))
→ TaskCancellationRequested → Worker

Workers can emit log messages and resource references at any point during execution. These are stored independently of step status.

TaskLogEmitted → TaskLogEmittedEventHandler → RegisterLogMessageUseCase
TaskResourceCreated (stored; no further handler currently)

EventTypeProduced byConsumed by
ProcessCreationRequestedIntegration (upstream)External API / callerProcessCreationRequestedEventHandler
ProcessCreatedDomainProcess aggregateProcessCreatedEventHandler
ProcessCancellationRequestedIntegration (upstream)— (declared but never raised; cancellation is a direct call to CancelProcessUseCase)— (no handler)
TaskExecutionRequestedIntegration (downstream)StepExecution aggregateWorker
TaskCancellationRequestedIntegration (downstream)CancelProcessUseCase, timeout handlerWorker
TaskStatusChangedIntegration (upstream)WorkerTaskStatusChangedEventHandler
TaskLogEmittedIntegration (upstream)WorkerTaskLogEmittedEventHandler
TaskResourceCreatedIntegration (upstream)Worker— (stored, no handler yet)
StepExecutionStatusChangedDomainStepExecution aggregateStepExecutionStatusUpdatedEventHandler
StepExecutionsCreationRequestedIntegration—— (defined, not yet handled)
TimeoutCheckRequestedIntegration (downstream)TimeoutSchedulerTimeoutCheckRequestedEventHandler

Represents a running instance of a workflow definition.

StatusMeaning
PENDINGCreated, waiting for first step
COMPLETEDAll steps finished successfully
CANCELLEDCancellation requested and confirmed
ERRORA step failed with no remaining retries or compensation

Represents the execution of a single step within a process.

StatusMeaning
CREATEDInitialised, not yet started
PENDINGHanded off to the worker
RUNNINGWorker has acknowledged execution
COMPLETEDWorker reported success
ERRORWorker reported failure, no retries left
CANCELLEDCancelled before completion
TIMEOUTDid not complete within the configured timeout

State transitions:

CREATED → PENDING → RUNNING → COMPLETED
→ ERROR
→ CANCELLED
→ TIMEOUT → (retry) → RUNNING
→ (compensate) → new step

Event delivery uses one of two transports, selectable via configuration:

ModeTransport
embeddedSpring ApplicationEventPublisher (in-process)
kafkaApache Kafka topics (distributed)

Domain events from aggregates are stored in an outbox table before being published, guaranteeing at-least-once delivery and consistency with the database transaction.