Best Practices & Performance
Everything on this page assumes the patterns from this section — child workflows, the saga pattern, event gates, and multi-service deployment. Each practice below links back to the pattern that demonstrates it.
Design Principles
Make Compensation Actions Idempotent
Compensation tasks might be replayed after a crash. Always check the current state before acting — for example, verify a booking isn't already cancelled before calling the cancellation API. This prevents double-refunds, double-cancellations, and other duplication issues. The crash-mid-rollback walkthrough shows why: the journal skips completed compensations on replay, but a compensation that died mid-flight will run again.
Pass All Required Data to Child Workflows
Don't rely on shared state or external lookups that might return different results on replay. Pass the full input (amount, currency, customer ID) rather than just a reference ID that requires a database lookup. This makes child workflows self-contained and deterministic — see the determinism rules for the full reasoning.
Keep Workflow Hierarchies Shallow
Two to three levels (parent, child, grandchild) is the practical limit. Deep hierarchies are harder to debug, slower to recover, and more complex to reason about. If you find yourself nesting deeper, flatten the structure by having the parent orchestrate more steps directly — and remember the granularity rule: not every unit deserves to be a workflow.
Use Timeouts on Every Event Gate
A workflow waiting for an event with no timeout can wait forever. Always specify a timeout and handle the timeout path — escalate to a different approver, auto-reject, or retry with a different provider. And if you chain gates into an escalation ladder, make sure the ladder ends in a deliberate terminal default.
Compensate in Reverse Order — When Order Matters
When rolling back a saga whose steps depend on each other, undo them in the reverse order they were executed — the compensation stack pops newest-first. When the completed steps are independent, as in an all-or-nothing fan-out, run the compensations in parallel instead. The rule is dependency order, not ceremony.