Core Concepts
The mental model behind Ductor — the execution and routing engines that implement the clearing lifecycle, driven by a single-writer coordinator over Postgres and Redis.
Ductor clears work through one lifecycle — priced → routed → executed →
settled → proven. This section is the engine vocabulary underneath that
lifecycle: the concepts here are how a work item (Routable)
actually gets executed and routed. The public primitives — Work, Route,
Settlement, and the Receipt — are defined in the
glossary; the pages below are the mechanisms that
carry them.
Under the hood Ductor is two engines sharing one substrate. A Go DAG workflow engine runs durable, multi-step processes (the executed stage); a routing engine turns an incoming event into a concrete assignment (the routed stage). Both sit on Postgres (the source of truth) plus Redis/Dragonfly (wakeups and hot counters), and both are driven by the same shape: a single-writer coordinator — the "tick" engine — owns all state transitions, while stateless workers execute the side effects in parallel and only ever append results.
Read this section before the deeper Architecture, Strategies, Workflows, AI, and SDK sections — each of those assumes the model laid out here.
The concepts
Coordinator & Step Workers
The single-writer coordinator + append-only workers that keep run state correct under concurrency.
The DAG Workflow Model
Steps, edges, scatter/gather, sub-workflows, waits, and ContinueAsNew — the vocabulary for durable work.
Routing Pipeline
How a routable event flows through registered stages to a concrete assignment.
The Tiered Fair Queue
How step tasks and coordinator wakeups are delivered fairly across tenants.
Optimistic Locking
The record_version primitive that makes every tick commit race-free.
Idempotency & Exactly-Once
How durable append plus dedup keys turn at-least-once dispatch into effectively-once work.
Deduplication & Outcomes
Suppress duplicate inbound work, then feed outcomes back into learning and billing.
Events & Event Sourcing
The trigger plane plus Ductor's three distinct event systems — sourcing, bus, and journal.
Connectors
How a step reaches the provider catalog with credentials encrypted at rest.
Tenancy
How every run, decision, and counter is scoped to a tenant.
Entitlements
The quota and plan checks that gate the hot path.
Engine Extensions
The eight extension-point types — strategies, plugins, CEL functions, middleware, providers — how to ship them, and the spec.yaml that declares their identity and compatibility.
Durable Execution Workers
The single-writer execution model that keeps DAG run state correct under concurrency.