> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Understanding workflow execution and the event sourcing model in Temporal Server

# Workflows

Workflows are the core abstraction in Temporal Server that enable durable execution of application logic. A Workflow Execution represents a single run of a workflow definition, tracked through an append-only event history that enables fault-tolerant, resumable execution.

## Event Sourcing Model

Temporal implements workflow durability through event sourcing. Every workflow execution maintains a complete history of events that describe everything that has happened during its execution.

### Workflow History

The Workflow History is a linear sequence of History Events stored durably in the persistence layer. Each event type represents a specific state transition:

<CardGroup cols={2}>
  <Card title="WorkflowExecutionStarted" icon="play">
    Marks the beginning of a workflow execution with input parameters and configuration
  </Card>

  <Card title="WorkflowTaskScheduled" icon="calendar">
    Indicates a workflow task has been created and is ready for worker pickup
  </Card>

  <Card title="ActivityTaskScheduled" icon="list-check">
    Records that an activity has been scheduled for execution
  </Card>

  <Card title="TimerFired" icon="clock">
    Captures when a workflow timer expires
  </Card>
</CardGroup>

### Deterministic Replay

Workflow code must be deterministic because execution state is recovered by replaying the history:

1. When a worker picks up a workflow task, it receives the complete event history
2. The SDK replays events through the workflow code to reconstruct state
3. Workflow continues execution from where it left off
4. New commands are generated and sent back to the server

```go theme={null}
// From service/history/workflow/mutable_state_impl.go
type MutableStateImpl struct {
    pendingActivityInfoIDs     map[int64]*persistencespb.ActivityInfo
    pendingTimerInfoIDs        map[string]*persistencespb.TimerInfo
    pendingChildExecutionInfoIDs map[int64]*persistencespb.ChildExecutionInfo
    
    executionInfo  *persistencespb.WorkflowExecutionInfo
    executionState *persistencespb.WorkflowExecutionState
    
    hBuilder *historybuilder.HistoryBuilder
    // ... workflow state tracking
}
```

## Mutable State

For performance, Temporal maintains a cached summary of workflow state called **Mutable State** rather than recomputing everything from history on each access.

### What Mutable State Tracks

Mutable State includes:

* **Pending Activities**: Activities that are scheduled or running
* **Pending Timers**: Active timers set by the workflow
* **Pending Child Workflows**: Child workflow executions in progress
* **Pending Signals**: External signal information
* **Execution Info**: Workflow type, task queue, timeouts
* **Execution State**: Current status (Running, Completed, Failed, etc.)

<Accordion title="Mutable State Implementation">
  ```go theme={null}
  // Mutable State contains in-memory summaries of workflow state
  pendingActivityTimerHeartbeats map[int64]time.Time
  pendingActivityInfoIDs         map[int64]*persistencespb.ActivityInfo
  pendingTimerInfoIDs           map[string]*persistencespb.TimerInfo

  // Modified data since last persistence write
  updateActivityInfos map[int64]*persistencespb.ActivityInfo
  deleteActivityInfos map[int64]struct{}
  ```

  Mutable State is persisted alongside history events and cached in memory for recently accessed workflows.
</Accordion>

## Workflow Lifecycle

A typical workflow execution follows this sequence:

```mermaid theme={null}
sequenceDiagram
    participant App as User Application
    participant Frontend
    participant History as History Service
    participant Matching
    participant Worker
    
    App->>Frontend: StartWorkflowExecution
    Frontend->>History: StartWorkflowExecution
    History->>History: Create [WorkflowExecutionStarted,<br/>WorkflowTaskScheduled] events
    History->>Matching: AddWorkflowTask
    
    Worker->>Matching: PollWorkflowTask
    Matching->>History: RecordWorkflowTaskStarted
    History->>History: Append WorkflowTaskStarted event
    History-->>Worker: Return task with history
    
    Worker->>Worker: Replay history,<br/>execute workflow code
    Worker->>History: RespondWorkflowTaskCompleted<br/>[Commands]
    History->>History: Process commands,<br/>append new events
```

### State Transitions

Each RPC or timer expiration triggers a state transition:

1. **Input**: RPC from application, worker response, or timer fired
2. **Processing**:
   * Create new History Events
   * Update Mutable State
   * Create History Tasks (Transfer or Timer tasks)
3. **Output**: Atomic transaction persisting events, state, and tasks

```go theme={null}
// From service/history/api/update_workflow_util.go
// State transitions use a common code path:
GetAndUpdateWorkflowWithNew(
    ctx,
    workflowContext,
    updateFunc, // Function that modifies mutable state
)
// Performs atomic write of:
// - New history events
// - Updated mutable state  
// - Generated tasks
```

## Workflow Tasks

A **Workflow Task** is how the History Service prompts a worker to advance workflow execution.

### When Workflow Tasks Are Created

* Workflow execution starts
* Activity completes (success or failure)
* Timer fires
* External signal received
* Query received

### Workflow Task Processing

<Steps>
  <Step title="Worker polls and receives task">
    Worker makes long-poll request to Matching Service, which returns a workflow task containing the execution's event history
  </Step>

  <Step title="SDK replays history through workflow code">
    The SDK feeds history events through deterministic workflow code to reconstruct state and determine next actions
  </Step>

  <Step title="Worker sends commands back">
    Worker returns a list of commands like `ScheduleActivityTask`, `StartTimer`, `CompleteWorkflowExecution`
  </Step>

  <Step title="History Service processes commands">
    Commands are converted to new history events and state updates in an atomic transaction
  </Step>
</Steps>

## Workflow Sharding

Workflow executions are distributed across **History Shards** for scalability:

* Each shard is a logical partition managing a subset of workflows
* Shard count is fixed at cluster creation (typically 512-16,384 shards)
* Each History Service instance owns multiple shards
* Shard ownership uses membership protocol (Ringpop) for distribution

<Accordion title="How Sharding Works">
  Workflows are assigned to shards by hashing the Namespace ID and Workflow ID:

  ```go theme={null}
  // Workflow is routed to specific shard
  shardID := hash(namespaceID, workflowID) % numShards
  ```

  Each shard independently:

  * Handles RPCs for its workflows
  * Processes background tasks
  * Maintains its own task queues
  * Has isolated failure domain
</Accordion>

## Consistency Guarantees

Temporal provides strong consistency for workflow state:

### Within History Service

* **Mutable State + History Events**: Consistent via event sourcing; mutable state tracks which event was last processed
* **Mutable State + History Tasks**: Consistent via database transactions
* **History to Matching**: Eventually consistent via Transfer Task queue and Transactional Outbox pattern

### Failure Handling

<CardGroup cols={2}>
  <Card title="Process Crash" icon="server">
    Workflow state is durable in persistence. Another History instance takes over the shard and continues processing.
  </Card>

  <Card title="Task Failure" icon="triangle-exclamation">
    Tasks in Transfer/Timer queues are retried. Ack levels ensure tasks aren't lost during failures.
  </Card>

  <Card title="Network Partition" icon="network-wired">
    Shard ownership fencing via RangeID prevents split-brain. Only one instance can write to a shard.
  </Card>

  <Card title="Database Unavailable" icon="database">
    Requests are retried with backoff. In-memory state is reloaded from persistence when available.
  </Card>
</CardGroup>

## Best Practices

<Warning>
  **Workflow code must be deterministic**. Side effects (I/O, randomness, system time) must go through Activities or SDK APIs that are recorded in history.
</Warning>

<Tip>
  Keep workflow history bounded. Very long-running workflows with millions of events can impact performance. Consider Continue-As-New for indefinite workflows.
</Tip>

## Related Concepts

* [Activities](/concepts/activities) - Execute non-deterministic operations
* [Task Queues](/concepts/task-queues) - Route tasks to workers
* [Workers](/concepts/workers) - Execute workflow and activity code