Getting Started

Orcher Architecture


Orcher is a Rust-native workflow orchestration engine with a modular crate architecture. Workflows are defined as regular async functions using macros and decorators, compiled directly into your worker binary, and executed in-process — eliminating the need for external runtimes, YAML definitions, or separate deployment pipelines. The system is built around three core components: an orchestrator server that manages state and scheduling, workers that execute your workflow and task code, and a PostgreSQL storage backend that persists journals, state, and execution history.

System Overview

The three main components communicate over gRPC. Your application embeds an Orcher worker that connects to the orchestrator server, polls for work, executes tasks locally, and reports results back. The server coordinates scheduling, manages workflow state machines, and persists everything to PostgreSQL.

Your App
+ Worker
gRPC
Orchestrator
:50051
PostgreSQL
Journal · State · Queue
Redis
Fast dispatch · optional
  • Orchestrator Server — Manages workflow lifecycle, schedules tasks onto queues, handles journal persistence, fires durable timers, and exposes the gRPC API on port 50051
  • Workers — Embed your workflow and task code, poll the server for work, execute tasks in-process, and report completions with eager dispatch for reduced latency
  • Storage Backend — PostgreSQL stores workflow executions, journal entries, task state, timer schedules, and the outbox queue for reliable delivery

Code-First Design

Unlike configuration-driven orchestrators that require YAML or DSL definitions, Orcher workflows are written as regular async functions decorated with macros (Rust) or decorators (TypeScript/Python). This means your workflows live in the same codebase as your application, benefit from compile-time type checking, and can be tested with standard unit testing frameworks.

1
use orcher::prelude::*;
2
3
#[task]
4
async fn validate_order(ctx: TaskContext, order: Order) -> Result<ValidatedOrder> {
5
// Validate the order
6
Ok(ValidatedOrder { /* ... */ })
7
}
8
9
#[task]
10
async fn process_payment(ctx: TaskContext, order: ValidatedOrder) -> Result<Payment> {
11
// Charge the customer
12
Ok(Payment { /* ... */ })
13
}
14
15
#[task]
16
async fn ship_order(ctx: TaskContext, payment: Payment) -> Result<Shipment> {
17
// Create shipment
18
Ok(Shipment { /* ... */ })
19
}
20
21
#[workflow]
22
async fn order_workflow(ctx: WorkflowContext, order: Order) -> Result<OrderResult> {
23
let validated = ctx.execute_task(validate_order, order).await?;
24
let payment = ctx.execute_task(process_payment, validated).await?;
25
let shipped = ctx.execute_task(ship_order, payment).await?;
26
Ok(OrderResult { shipped })
27
}

Worker-Embedded Execution

Workflows and tasks execute inside your application's worker process rather than in a separate runtime. The worker binary includes the SDK, gRPC client, and all your workflow definitions — there's nothing else to install or run. This architecture eliminates serialization overhead for local data, gives your tasks direct access to your application's services and databases, and simplifies deployment to a single binary.

  • No External Dependencies — Workers are self-contained; no JVM, no runtime, no sidecar processes
  • Direct Data Access — Tasks can call your application's services, query your databases, and use your existing libraries
  • Low Latency — In-process execution avoids network hops and serialization overhead between scheduler and executor

Automatic Journaling

Every task execution is automatically journaled to PostgreSQL without any manual checkpointing code. Before a task runs, the input is recorded; after it completes, the output is stored. On replay (after a crash or restart), the journal returns cached results instead of re-executing tasks — giving you crash recovery with no repeated work on replay: completed tasks return their journaled result instead of running again.

  1. Before Execution — Task input and metadata are recorded to the journal
  2. After Execution — Task output and completion status are persisted
  3. On Replay — Cached results are returned instantly, skipping re-execution

This enables crash recovery (resume from the last completed step), no repeated work on replay (completed tasks are not re-run — their journaled result is reused), and full execution history for debugging and auditing.

Compile-Time Validation

Orcher's Rust SDK validates workflows at compile time through the type system and proc macros. Task input/output types must match, all referenced tasks must exist, and configuration errors are caught before your code ever ships. The TypeScript and Python SDKs provide similar validation through typed decorators and runtime checks during worker startup.

  • Type Checking — Task inputs and outputs are statically validated; mismatched types are compile errors
  • Dependency Validation — Referenced tasks must exist and have compatible signatures
  • Configuration Validation — Invalid retry policies, timeout values, and queue names are caught early

Eager Dispatch

In a traditional workflow engine, completing a task requires a full round-trip: the worker reports the result, then polls again for the next task. Orcher's eager dispatch optimization eliminates that second poll — when a worker completes a task, the server checks whether the same workflow has another task ready and returns it directly in the completion response. This removes one full round-trip per task, which is where most of the latency in a sequential workflow accumulates.

1
Traditional: complete task → poll → receive next task (2 round-trips)
2
Eager: complete task → receive next task (1 round-trip)

The server uses a short-TTL soft claim to prevent double execution: if the worker doesn't start the eager task within 10 seconds, a background reclaimer resets it back to the queue for normal polling. This means eager dispatch is a pure optimization — it never compromises correctness.

Events & Signals

Workflows can pause and wait for external events using wait_for_event, then resume when a signal arrives via the send_event gRPC API. This is the foundation for human-in-the-loop approvals, webhook callbacks, and inter-workflow communication. Events are journaled just like task completions, so they survive crashes and replay correctly.

  • External signals — Send events from your API, webhooks, or other services via SendEvent gRPC call
  • Inter-workflow communication — Workflows can signal other workflows using ctx.send_event(target_workflow, event_name, payload)
  • Timeouts — wait_for_event_with_timeout returns None if no signal arrives within the deadline, enabling escalation and fallback logic

Scalability

Orcher scales horizontally by adding workers. Each worker connects to the orchestrator server, polls for tasks on its registered queues, and executes work independently. The orchestrator itself is stateless (all state lives in PostgreSQL) and can run as multiple replicas behind a load balancer for high availability.

  • Multiple Workers — Add workers to increase throughput; each worker handles tasks concurrently with configurable capacity
  • Partitioned Queues — Route tasks to specific workers by queue name, enabling workload isolation and resource tuning
  • Stateless Orchestrator — Run multiple orchestrator instances for high availability; PostgreSQL is the single source of truth

Next Steps