Getting Started

Learning Path: Backend Engineers


Welcome to Orcher! This guide will teach you how to build production-ready backend services with automatic fault tolerance, distributed transactions, and durable workflows. By the end, you'll understand not just how to use Orcher, but why it fundamentally changes how we build reliable systems.

What You'll Learn

This learning path takes you from zero to production-ready in a structured way:

Part 1: Understanding the Core (30-45 minutes)

  • What durable execution really means and why it matters
  • How Orcher's architecture eliminates entire classes of bugs
  • The mental model shift from traditional backend development

Part 2: Building with Orcher (2-3 hours)

  • Payment processing that survives crashes without charging twice
  • Webhook handling that never misses events
  • Distributed transactions without distributed transaction coordinators
  • Long-running background jobs with progress tracking

Part 3: Production Excellence (1-2 hours)

  • Monitoring and observability patterns
  • Testing strategies for workflows
  • Performance optimization and scaling

Time to Complete: 5-7 hours Prerequisites: REST API experience, basic database knowledge Difficulty: Beginner to Advanced


Why Orcher for Backend Engineering?

Let's start with a real problem you've probably encountered.

The Reliability Problem

Imagine you're building a payment processing endpoint. A user submits their credit card, and you need to:

  1. Charge the card via Stripe
  2. Update your database with the payment record
  3. Send a receipt email
  4. Update the user's subscription status
  5. Notify your analytics system

What happens if step 3 fails?

With traditional approaches, you have three bad options:

Option 1: Fail the entire request

  • User's card was charged
  • But they see an error page
  • You have to manually issue refunds
  • Customer support nightmare

Option 2: Retry everything

  • You charge the card again (double charge!)
  • Database gets duplicate records
  • User receives multiple emails
  • Stripe complains about duplicate requests

Option 3: Manual state management

  • Store "step completed" flags in Redis
  • Check each flag before executing
  • Handle partial completions
  • Debug distributed state across services
  • Write hundreds of lines of error-handling code

None of these are good.

The Orcher Solution

Orcher provides durable execution as a primitive. Here's what that means:

Orcher uses a client-server architecture: an Orchestrator server (gRPC port 50051, HTTP port 8001) paired with SDK Workers that connect via gRPC. Every step in your workflow is automatically journaled to PostgreSQL. If anything fails, Orcher replays from the journal instead of re-executing completed steps. It's like having an automatic "save game" system for your business logic.

1
// Each step is automatically checkpointed
2
let charge = ctx.execute_task(charge_card, payment).await?; // ✓ Journaled
3
ctx.execute_task(update_db, charge.id).await?; // ✓ Journaled
4
ctx.execute_task(send_email, user.email).await?; // ✓ Journaled
5
ctx.execute_task(update_subscription, user.id).await?; // ✓ Journaled
6
7
// If crash happens after send_email, next run:
8
// - charge_card: Returns cached result (no API call)
9
// - update_db: Returns cached result (no DB write)
10
// - send_email: Returns cached result (no duplicate email)
11
// - update_subscription: Executes for the first time ✓

The magic: This code looks like normal, sequential business logic. But it's actually durable, recoverable, and idempotent—without any manual state management. Here's the recovery in the crash-after-send_email case, step by step:

Crash After the Email — What Reruns
✓
charge_cardcard charged — result journaled
✓
update_dbpayment recorded — journaled
✓
send_emailreceipt sent — journaled
✗
server crashesbefore update_subscription
↻
replayfirst three return journaled results — no re-charge, no duplicate email
▶
update_subscriptionruns for the first time — the pipeline finishes
The card is charged once and the email sent once — no matter where the crash lands.

Comparing Approaches

The reliability above usually costs you a pile of infrastructure. Durable execution folds most of it away — the stack you operate shrinks from five-plus moving parts to two you already run.

Traditional Stack
state scattered across systems
Load Balancer
API Servers
Redis Queue
Worker Pools
Database
Dead Letter Queue
"Step completed" flags
5+ parts · manual retries · no auto-recovery
Orcher Stack
all state in one place
Load Balancer
API Servers
Orchestrator
gRPC :50051 · HTTP :8001
journal + data
PostgreSQL
app data + workflow journal
gRPC
SDK Workers (your code)
One server + one database · built-in retries · auto-recovery

The point isn't fewer boxes for their own sake — it's that the recovery logic, retry state, and dead-letter handling that used to be your code and your infrastructure are now properties of the runtime.


The path