# Temporal Design Patterns

> A catalog of common, reusable, and proven design patterns for Temporal Workflows, organized by problem domain.

Temporal provides a set of durable execution primitives that you can compose into common, reusable, and proven patterns. Having these patterns in your toolbox helps you solve recurring problems in a battle-tested way.

## Distributed transaction patterns

- [Saga Pattern](/design-patterns/saga-pattern): Manages distributed transactions with compensating actions. Each step has a compensation that undoes its effects if subsequent steps fail.
- [Early Return](/design-patterns/early-return): Synchronous initialization with asynchronous completion. Returns results immediately while processing continues in the background.
- [Idempotent Distributed Transactions](/design-patterns/idempotent-distributed-transactions): Coordinates multi-step operations across external services with safe retries, automatic rollback on failure, and protection against duplicate submissions.

## Entity & lifecycle patterns

- [Entity Workflow](/design-patterns/entity-workflow): Models long-lived business entities as individual Workflows that persist for the entity
- [Continue-As-New](/design-patterns/continue-as-new): Prevents unbounded history growth by completing the current execution and starting a new one with fresh history.
- [Updatable Timer](/design-patterns/updatable-timer): Dynamically adjustable timers that respond to Signals or Updates. Extend, shorten, or cancel timers based on external events.

## Workflow messaging patterns

- [Signal with Start](/design-patterns/signal-with-start): Starts a Workflow when Signaling it if it does not already exist. If already running, it receives the Signal directly.
- [Request-Response via Updates](/design-patterns/request-response-via-updates): Synchronous request-response with validation. Updates modify state and return results directly.
- [Event Accumulator](/design-patterns/event-accumulator): Buffers a stream of incoming Signals and processes them together in batches based on size or time thresholds.

## Task orchestration patterns

- [Child Workflows](/design-patterns/child-workflows): Decomposes complex Workflows into smaller, reusable units. Each child has an independent Workflow ID, history, and lifecycle.
- [Parallel Execution](/design-patterns/parallel-execution): Executes multiple Activities concurrently for maximum throughput with error handling and controlled parallelism.
- [Pick First (Race)](/design-patterns/pick-first): Starts multiple Activities in parallel and uses the first result, cancelling the rest.

## External interaction patterns

- [Polling External Services](/design-patterns/polling): Strategies for polling external resources with varying frequencies: frequent, infrequent, and periodic patterns.
- [Long-Running Activity](/design-patterns/long-running-activity): Long-running Activities report progress via heartbeats and enable resumption after failures with cancellation support.
- [Approval](/design-patterns/approval): Human-in-the-loop Workflows that block until external approval decisions are made. Uses Signals to capture approval data with metadata.
- [Delayed Start](/design-patterns/delayed-start): Creates Workflows immediately but defers execution until a specified delay expires. Fits one-time scheduled operations and grace periods.
- [Delayed Callback](/design-patterns/delayed-callback): Durable webhook and callback handling: fire delayed outbound callbacks with durable timers and complete work asynchronously via task tokens.

## Worker configuration patterns

- [Worker-Specific Task Queues](/design-patterns/worker-specific-taskqueue): Routes Activities to specific Workers using unique Task Queues for Worker affinity and host-specific processing.
- [Activity Dependency Injection](/design-patterns/activity-dependency-injection): Injects external dependencies into Activities at Worker startup, keeping Workflow code deterministic and Activities testable.

## Error handling & retry patterns

- [Fixed Count of Retries](/design-patterns/fixed-count-retries): Cap the number of Activity retry attempts to control cost when each attempt consumes a paid or limited resource.
- [Fixed Wall-Time Retries](/design-patterns/fixed-wall-time-retries): Bound the total elapsed time across all retry attempts to enforce a business SLA, regardless of how many individual attempts occur.
- [Non-Retryable Errors](/design-patterns/non-retryable-errors): Mark error types that will never succeed \u2014 such as validation failures or missing records \u2014 so Temporal fails fast instead of retrying indefinitely.
- [Delayed Retry](/design-patterns/delayed-retry): Override the next retry interval for a specific failure using nextRetryDelay on ApplicationFailure. Use when an error carries information about how long to wait before retrying.
- [Fast/Slow Retries](/design-patterns/fast-slow-retries): Try aggressively with a short interval first, then shift to a long interval when fast retries are exhausted, keeping the Workflow alive until the downstream system recovers.
- [Retry Alerting via Metrics](/design-patterns/retry-metrics): Emit a custom metric from inside the Activity when the attempt count crosses a threshold, surfacing silent persistent failures to on-call teams before an SLA breach.
- [Resumable Activity](/design-patterns/resumable-activity): Park the Workflow after retries are exhausted and wait for a human to signal a correction, then resume execution from where it left off.

## QoS & throughput patterns

- [Downstream Rate Limiting](/design-patterns/downstream-rate-limiting): Caps Activity execution rate against a downstream service by routing throttled Activities to a dedicated Task Queue backed by Workers configured with a throughput limit.
- [Priority Task Queues](/design-patterns/priority-task-queues): Assigns a priority level to Workflows and Activities so that time-sensitive work executes ahead of lower-priority work within a single Task Queue.
- [Fairness](/design-patterns/fairness): Distributes Worker capacity evenly across tenants or users so that a burst from one caller does not starve the others.

## Batch processing patterns

- [Fan-Out with Child Workflows](/design-patterns/fanout-child-workflows): Distributes a large record set across parallel Child Workflows for concurrent processing with automatic scaling.
- [Batch Iterator](/design-patterns/batch-iterator): Pages through unbounded datasets using Continue-As-New to prevent history overflow while maintaining exactly-once processing guarantees.
- [Sliding Window](/design-patterns/sliding-window): Maintains a fixed number of concurrently active Child Workflows, starting a new one each time an existing one completes.
- [MapReduce Tree](/design-patterns/mapreduce-tree): Recursively splits a dataset into a binary tree of Child Workflows, processes leaves in parallel, then aggregates results back up the tree.