Skip to main content

Workflow Architecture

Overview of the ValkyrAI workflow engine, covering core runtime, scheduling, events, state, and branching.

  • Engine: Asynchronous execution with Quartz scheduling and event triggers.
  • Tasks: Ordered sets of modules (adapters) with optional parallel groups.
  • Modules: Spring components with a simple execute() contract; Map-based variants can exchange state.
  • State: WorkflowState as durable context; modules read/write via map I/O.
  • Branching: Modules implement BranchingModule signaling DEFAULT | CONDITIONAL | FAILURE.

Key packages

  • valkyrai/src/main/java/com/valkyrlabs/workflow/service/ValkyrWorkflowService: Orchestration, scheduling, branching.
  • .../modules: Concrete adapters including LLM, REST, Files, Email.
  • .../engine/conditions: Condition evaluation (OpenXLS-ready + JEXL fallback).
  • .../events: Event bus and trigger registry.

Parallel execution

  • Mark modules with {"parallel": true, "parallelGroup": "A"} in moduleData to run as a batch.
  • Aggregated outcomes prioritize FAILURE > CONDITIONAL > DEFAULT.

Branching modules

  • Implement BranchingModule and return a BranchOutcome.
  • FormulaBranchingModule evaluates spreadsheet-like conditions and can direct to a specific next task (via nextTaskId).

Security context

  • Workflows run under a role (SYSTEM, ASSISTANT, USER). See runAsWorkflowRole in the service.

  • Graph-driven next steps

  • The Workflow Builder saves edges into workflow.meta as:

    • { "graph": { "edges": [{ "sourceTaskId": "...", "targetTaskId": "..." }] } }

  • The engine consults this graph first to select the next task, falling back to list order when no edge is found.