Best Practices & Performance
Everything on this page assumes the patterns from this section — order processing, stateful actors, stream aggregation, and pattern detection. Each practice below links back to the pattern that demonstrates it.
Design Principles
One Workflow per Event Type
Keep event handlers focused — a single workflow should handle one event type or one closely related group. This makes them easier to test, version independently, and reason about during debugging. The order-processing dispatcher shows the shape, and the point where a fat match should split into per-type child workflows.
Actors for State, Workflows for Chains
If multiple events update the same entity — a shopping cart, user profile, device status — use an actor, whose single-writer guarantee removes the race by construction. If you need to react to one event by running a sequence of tasks, use a workflow. They compose: an actor operation can start a child workflow, and a workflow can invoke actor operations.
Design for Idempotent Event Handling
Orcher never repeats a completed step within a workflow, but external sources deliver at-least-once — webhook retries and queue redelivery mean the same event can start the workflow twice. Make the downstream effects idempotent (dedupe on the event or order ID) so a redelivery is a no-op, exactly as laid out in what the handler must tolerate.
Use Event Gates for Correlations Over Time
When you need to detect a pattern across events over time — fraud, abandoned carts, SLA breaches — use wait_for_event_with_timeout rather than polling a database. The workflow suspends at zero cost and wakes instantly when the correlated event arrives; the timeout branch handles the "it never came" case for free. Pattern detection covers both the presence and absence signals.
Keep Actor Operations Fast
An exclusive operation holds the actor's writer slot per key, so a slow one blocks every other write to that entity. Keep exclusive operations to state reads and writes, and delegate heavy work — payment, shipping, transcoding — to a child workflow, as stateful actors does with checkout. And remember the corollary: throughput scales with distinct actors, so a single hot entity is your ceiling.
Next Steps
Actors Guide
Deep dive into actor definitions, operations, state API, concurrency modes, and the execution model.
Events & Signals
Core concepts behind event gates, signal delivery, and inter-workflow communication.
Long-Running Processes
Durable timers, human-in-the-loop approvals, and workflows that run for days or weeks.
Service Orchestration
Child workflows, saga rollback, event gates, and parallel fan-out for distributed systems.