Skip to content

README.md

Latest commit

 

History

History
67 lines (48 loc) · 3.74 KB

README.md

File metadata and controls

67 lines (48 loc) · 3.74 KB

@workflow-builder/execution-worker

Note: setup is in root README "Path C. Run the full stack demo". This file documents the worker's internals.

Background process that executes workflow graphs submitted by the backend. Currently backed by Temporal; structured so other engines (in-memory, BullMQ, …) can slot in without touching domain logic.

Role

backend  ──▶  Temporal (queue)  ──▶  execution-worker  ──┬──▶  execute node (AI agent, decision, …)
                                                          ├──▶  emit execution events → Postgres
                                                          └──▶  update execution status → Postgres

The worker polls a task queue, runs activities, and persists side-effects. All workflow logic lives in @workflow-builder/execution-core; the worker is the adapter that wires that logic to Temporal primitives.

Running alone

For debugging only. pnpm dev:ai-studio from the root starts the worker alongside backend and frontend.

pnpm dev:worker          # alias for pnpm --filter execution-worker dev

Requires Postgres + Temporal running. Start them with pnpm infra:up.

Environment

See .env.example. Required:

Var Purpose Default
OPENROUTER_API_KEY AI agent activities (required) —
DATABASE_URL Execution events + status postgresql://wb:wb@127.0.0.1:5432/workflow_builder
TEMPORAL_ADDRESS Temporal server address 127.0.0.1:7233
AI_MODEL OpenRouter model ID anthropic/claude-3.5-haiku

Structure

src/
├── database.ts            # Raw SQL for exec events + status updates (no Drizzle — avoids backend schema coupling)
├── env.ts                 # Centralized env validation — fail fast at module load
└── engines/
    └── temporal/
        ├── worker.ts                      # Temporal Worker bootstrap + NodeExecutorRegistry
        ├── activities-interface.ts        # Activity signatures proxied from the workflow sandbox
        └── workflows/
            └── run-workflow.ts            # Temporal workflow — delegates to runGraph from execution-core

Temporal specifics

  • Task queue: workflow-execution (must match TemporalEngine in the backend).
  • Workflow ID: execution-<executionId> — deterministic, lets the backend cancel by execution ID.
  • Activity timeouts: DB activities get 30s / 5 retries; node activities (may call LLMs) get 10m / 2 retries. See run-workflow.ts.
  • Sandbox constraint: workflows/*.ts runs in V8 with no Web APIs — import from @workflow-builder/execution-core/workflow (sandbox-safe subset), never from the root barrel.

Adding a new engine

  1. Create src/engines/<name>/ with:
    • a bootstrap (equivalent of worker.ts) that wires up NodeExecutorRegistry and connects to the queue
    • an adapter in apps/backend/src/engine/<name>-engine.ts implementing WorkflowEnginePort
  2. Point getWorkflowEngine() in apps/backend/src/engine/index.ts at the new adapter (or add config-driven selection).
  3. Reuse runGraph from @workflow-builder/execution-core/workflow — the graph traversal is engine-agnostic.

The domain layer (execution-core) never has to change.