Helix

Helix is a SaaS-first durable distributed execution platform: brokered execution, external processor fabric, static DAG workflows, persistent leases, replayable events, scheduling, signals, typed SDKs, and operations tooling.

See PRD.md for product requirements and phased delivery.

Architecture docs

• Architecture Decision Records
• Domain glossary
• Architecture checklist
• Event policy

Workspace

Yarn workspace layout:

• apps/control-plane — SaaS API/control plane shell; owns the v1 /admin UI.
• services/broker — job, lease, attempt, and routing runtime shell.
• services/scheduler — schedules, timers, and wake-up runtime shell.
• packages/contracts — shared API/event contract shell.
• packages/producer-sdk — TypeScript producer SDK shell.
• packages/processor-sdk — TypeScript processor SDK shell.
• packages/workflow-sdk — TypeScript workflow SDK shell.

Local infrastructure

Helix uses Postgres as authoritative state and Redpanda as the Kafka-compatible derived event bus for local/CI smoke checks.

cp .env.example .env
docker compose up -d
yarn infra:smoke
yarn db:migrate
docker compose down

Use docker compose down -v only when you intentionally want to delete local Postgres and Redpanda volumes.

Workflow recovery assumptions

Workflow recovery treats Postgres-backed workflow runs, steps, and dependencies as authoritative state. A runtime restart may recreate service instances over the same durable store and call the workflow resume path to activate persisted running job steps and any pending steps whose dependencies are already complete. Step jobs use idempotency keys of the form workflow-step:<runId>:<stepId>, so recovery retries do not duplicate completed or already activated work. Runtime events/outbox records remain derived from durable state; recovery must not emit a second workflow.run.started event for the same run.

Commands

yarn install --immutable
yarn docs:check
yarn tooling:check
yarn infra:smoke
yarn db:migrate
yarn check
yarn test
yarn lint
yarn validate