> ## 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.

# Workflow Execution Lifecycle

> Detailed sequence diagrams showing workflow execution from start to completion

# Workflow Execution Lifecycle

This page follows a typical sequence of events in the execution of a simple workflow, showing how requests flow between User Applications, Frontend, History, Matching services, and Workers.

## Example Workflow

We'll trace the execution of this simple workflow:

```javascript theme={null}
function myWorkflow() {
  result = callActivity(myActivity);
  return result;
}
```

<Info>
  The diagrams below show the detailed interaction between services. For high-level architecture, see [Architecture Overview](/architecture/overview).
</Info>

<Note>
  In the diagrams below:

  * "Initialize history" and "Append event to history" refer to durable writes to the persistence layer
  * "Persist Mutable State and history tasks" refers to atomic database transactions
</Note>

## Step 1: Start Workflow Execution

The user application sends a `StartWorkflowExecution` request:

* Workflow History is initialized with `[WorkflowExecutionStarted, WorkflowTaskScheduled]`
* A Transfer Task is created to add a Workflow Task to the Matching service

```mermaid theme={null}
sequenceDiagram
    participant App as User Application
    participant Frontend
    participant History
    participant Persistence
    participant Matching
    
    App->>Frontend: StartWorkflowExecution
    Frontend->>History: StartWorkflowExecution
    History->>Persistence: CreateWorkflowExecution
    note over Persistence: Initialize History:<br/>[WorkflowExecutionStarted, WorkflowTaskScheduled]<br/>persist MutableState and Transfer Task
    Persistence-->>History: Create Succeed
    History-->>Frontend: Start Succeed
    Frontend-->>App: Start Succeed
    
    loop Queue Processor
        History->>Persistence: GetHistoryTasks
        History->>History: ProcessTask
        History->>Matching: AddWorkflowTask
    end
```

### State After Step 1

```mermaid theme={null}
flowchart LR
    subgraph State["Workflow State"]
        direction TB
        
        subgraph MS["Mutable State"]
            WT["Workflow Task: Scheduled"]
        end
        
        subgraph TQ["Transfer Queue"]
            T1["WorkflowTask"]
        end
        
        subgraph TimerQ["Timer Queue"]
            TM1["Workflow Timeout"]
        end
    end
    
    subgraph History["Workflow History"]
        direction TB
        E1["1. WorkflowExecutionStarted"]
        E2["2. WorkflowTaskScheduled"]
        E1 ~~~ E2
    end
    
    State ~~~ History
    
    style State fill:#fff4e1
    style History fill:#e1f5ff
```

<Accordion title="Code Entrypoints">
  * History service `StartWorkflow` handler: `service/history/api/startworkflow/api.go`
  * Queue processors: `service/history/history_engine.go:303`
  * Transfer task processor: `service/history/queues/queue_immediate.go:150`
</Accordion>

## Step 2: Worker Polls and Processes Workflow Task

A worker dequeues the Workflow Task and advances workflow execution:

* The workflow code executes and becomes blocked on the activity call
* A `WorkflowTaskStarted` event is appended to history

```mermaid theme={null}
sequenceDiagram
    participant Worker
    participant Frontend
    participant Matching
    participant History
    participant Persistence
    
    Worker->>Frontend: PollWorkflowTask
    Frontend->>Matching: PollWorkflowTask
    History->>Matching: AddWorkflowTask (from step 1)
    Matching->>History: RecordWorkflowTaskStarted
    History->>Persistence: UpdateWorkflowExecution
    note over Persistence: append History Event: WorkflowTaskStarted<br/>update Mutable State & add Timer Task (timeout)
    Persistence-->>History: Update Succeed
    History->>Persistence: GetHistoryEvents
    Persistence-->>History: History Events
    History-->>Matching: Record Succeed
    Matching-->>Frontend: WorkflowTask
    Frontend-->>Worker: WorkflowTask
    Worker->>Worker: Advance workflow<br/>(execute until blocked)
```

### State After Step 2

```mermaid theme={null}
flowchart LR
    subgraph State["Workflow State"]
        direction TB
        
        subgraph MS["Mutable State"]
            WT["Workflow Task: Started"]
        end
        
        subgraph TQ["Transfer Queue"]
            T1[" "]
        end
        
        subgraph TimerQ["Timer Queue"]
            TM1["Workflow Task Timeout"]
            TM2["Workflow Timeout"]
            TM1 ~~~ TM2
        end
    end
    
    subgraph History["Workflow History"]
        direction TB
        E1["1. WorkflowExecutionStarted"]
        E2["2. WorkflowTaskScheduled"]
        E3["3. WorkflowTaskStarted"]
        E1 ~~~ E2 ~~~ E3
    end
    
    State ~~~ History
    
    style State fill:#fff4e1
    style History fill:#e1f5ff
```

<Accordion title="Code Entrypoints">
  * History service `RecordWorkflowTaskStarted` handler: `service/history/handler.go:319`
</Accordion>

## Step 3: Worker Completes Workflow Task with ScheduleActivity Command

The workflow launches an activity, causing the worker to send a `ScheduleActivityTask` command:

* Events are appended: `WorkflowTaskCompleted`, `ActivityTaskScheduled`
* A Transfer Task is created to add an Activity Task to Matching

```mermaid theme={null}
sequenceDiagram
    participant Worker
    participant Frontend
    participant History
    participant Persistence
    participant Matching
    
    Worker->>Frontend: RespondWorkflowTaskCompleted<br/>[ScheduleActivityTask]
    Frontend->>History: RespondWorkflowTaskCompleted<br/>[ScheduleActivityTask]
    History->>Persistence: UpdateWorkflowExecution
    note over Persistence: append History Events:<br/>WorkflowTaskCompleted, ActivityTaskScheduled<br/>update MutableState and add Transfer Task
    Persistence-->>History: Update Succeed
    History-->>Frontend: Respond Succeed
    Frontend-->>Worker: Respond Succeed
    
    loop Queue Processor
        History->>Persistence: GetHistoryTasks
        History->>History: ProcessTask
        History->>Matching: AddActivityTask
    end
```

### State After Step 3

```mermaid theme={null}
flowchart LR
    subgraph State["Workflow State"]
        direction TB
        
        subgraph MS["Mutable State"]
            WT["Workflow Task: Empty"]
            AT["Activity Task: Scheduled"]
            WT ~~~ AT
        end
        
        subgraph TQ["Transfer Queue"]
            T1["Activity Task"]
        end
        
        subgraph TimerQ["Timer Queue"]
            TM1["Workflow Task Timeout"]
            TM2["Activity Task Timeout"]
            TM3["Workflow Timeout"]
            TM1 ~~~ TM2 ~~~ TM3
        end
    end
    
    subgraph History["Workflow History"]
        direction TB
        E1["1. WorkflowExecutionStarted"]
        E2["2. WorkflowTaskScheduled"]
        E3["3. WorkflowTaskStarted"]
        E4["4. WorkflowTaskCompleted"]
        E5["5. ActivityTaskScheduled"]
        E1 ~~~ E2 ~~~ E3 ~~~ E4 ~~~ E5
    end
    
    State ~~~ History
    
    style State fill:#fff4e1
    style History fill:#e1f5ff
```

<Accordion title="Code Entrypoints">
  * History service `ScheduleActivityTask` command handler: `service/history/workflow_task_handler.go:338`
</Accordion>

## Step 4: Worker Polls and Executes Activity

A worker dequeues the Activity Task and executes the activity:

* An `ActivityTaskStarted` event is appended
* The activity code runs (can have side effects)

```mermaid theme={null}
sequenceDiagram
    participant Worker
    participant Frontend
    participant Matching
    participant History
    participant Persistence
    
    Worker->>Frontend: PollActivityTask
    Frontend->>Matching: PollActivityTask
    History->>Matching: AddActivityTask (from step 3)
    Matching->>History: RecordActivityStarted
    History->>Persistence: UpdateWorkflowExecution
    note over Persistence: append History Event: ActivityTaskStarted<br/>update Mutable State, add Timer Task (timeout)
    Persistence-->>History: Update Succeed
    History-->>Matching: Record Succeed
    Matching-->>Frontend: ActivityTask
    Frontend-->>Worker: ActivityTask
    Worker->>Worker: Execute activity
```

### State After Step 4

```mermaid theme={null}
flowchart LR
    subgraph State["Workflow State"]
        direction TB
        
        subgraph MS["Mutable State"]
            WT["Workflow Task: Empty"]
            AT["Activity Task: Started"]
            WT ~~~ AT
        end
        
        subgraph TQ["Transfer Queue"]
            T1[" "]
        end
        
        subgraph TimerQ["Timer Queue"]
            TM1["Activity Task Timeout"]
            TM2["Workflow Timeout"]
            TM1 ~~~ TM2
        end
    end
    
    subgraph History["Workflow History"]
        direction TB
        E1["1. WorkflowExecutionStarted"]
        E2["2. WorkflowTaskScheduled"]
        E3["3. WorkflowTaskStarted"]
        E4["4. WorkflowTaskCompleted"]
        E5["5. ActivityTaskScheduled"]
        E6["6. ActivityTaskStarted"]
        E1 ~~~ E2 ~~~ E3 ~~~ E4 ~~~ E5 ~~~ E6
    end
    
    State ~~~ History
    
    style State fill:#fff4e1
    style History fill:#e1f5ff
```

<Accordion title="Code Entrypoints">
  * History service `RecordActivityTaskStarted` handler: `service/history/handler.go:287`
</Accordion>

## Step 5: Worker Completes Activity Task

Once the activity completes, the worker sends the result back:

* Events are appended: `ActivityTaskCompleted`, `WorkflowTaskScheduled`
* A new Workflow Task is created to allow the workflow to process the result

```mermaid theme={null}
sequenceDiagram
    participant Worker
    participant Frontend
    participant History
    participant Persistence
    participant Matching
    
    Worker->>Frontend: RespondActivityTaskCompleted
    Frontend->>History: RespondActivityTaskCompleted
    History->>Persistence: UpdateWorkflowExecution
    note over Persistence: append History Events:<br/>ActivityTaskCompleted (w/ result),<br/>WorkflowTaskScheduled<br/>update Mutable State & add Transfer Task
    Persistence-->>History: Update Succeed
    History-->>Frontend: Respond Succeed
    Frontend-->>Worker: Respond Succeed
    
    loop Queue Processor
        History->>Persistence: GetHistoryTasks
        History->>History: ProcessTask
        History->>Matching: AddWorkflowTask
    end
```

### State After Step 5

```mermaid theme={null}
flowchart LR
    subgraph State["Workflow State"]
        direction TB
        
        subgraph MS["Mutable State"]
            WT["Workflow Task: Scheduled"]
        end
        
        subgraph TQ["Transfer Queue"]
            T1["Workflow Task"]
        end
        
        subgraph TimerQ["Timer Queue"]
            TM1["Workflow Task Timeout"]
            TM2["Activity Task Timeout"]
            TM3["Workflow Timeout"]
            TM1 ~~~ TM2 ~~~ TM3
        end
    end
    
    subgraph History["Workflow History"]
        direction TB
        E1["1. WorkflowExecutionStarted"]
        E2["2. WorkflowTaskScheduled"]
        E3["3. WorkflowTaskStarted"]
        E4["4. WorkflowTaskCompleted"]
        E5["5. ActivityTaskScheduled"]
        E6["6. ActivityTaskStarted"]
        E7["7. ActivityTaskCompleted"]
        E8["8. WorkflowTaskScheduled"]
        E1 ~~~ E2 ~~~ E3 ~~~ E4 ~~~ E5 ~~~ E6 ~~~ E7 ~~~ E8
    end
    
    State ~~~ History
    
    style State fill:#fff4e1
    style History fill:#e1f5ff
```

<Accordion title="Code Entrypoints">
  * History service `RespondActivityTaskCompleted` handler: `service/history/handler.go:361`
</Accordion>

## Step 6: Worker Processes Final Workflow Task

The worker dequeues the Workflow Task and advances the workflow:

* The workflow finds it has reached its end (received activity result)
* The worker will send a `CompleteWorkflowExecution` command

<Note>
  This step has the same sequence diagram as Step 2 above.
</Note>

## Step 7: Worker Completes Workflow Execution

The worker sends `RespondWorkflowTaskCompleted` with a `CompleteWorkflowExecution` command:

* Events are appended: `WorkflowTaskCompleted`, `WorkflowExecutionCompleted`
* Additional tasks are created for visibility, archival, and retention

```mermaid theme={null}
sequenceDiagram
    participant Worker
    participant Frontend
    participant History
    participant Persistence
    
    Worker->>Frontend: RespondWorkflowTaskCompleted<br/>[CompleteWorkflowExecution]
    Frontend->>History: RespondWorkflowTaskCompleted<br/>[CompleteWorkflowExecution]
    History->>Persistence: UpdateWorkflowExecution
    note over Persistence: append History Events:<br/>WorkflowTaskCompleted,<br/>WorkflowExecutionCompleted<br/>update Mutable State & add tasks<br/>(visibility, archival, retention)
    Persistence-->>History: Update Succeed
    History-->>Frontend: Respond Succeed
    Frontend-->>Worker: Respond Succeed
    
    loop Queue Processor
        History->>Persistence: GetHistoryTasks
        History->>History: ProcessTask<br/>(Update visibility,<br/>Upload to archival storage,<br/>Schedule retention deletion)
    end
```

### Final State

```mermaid theme={null}
flowchart LR
    subgraph State["Workflow State"]
        direction TB
        
        subgraph MS["Mutable State"]
            WT["Workflow Task: Empty"]
            Status["Status: Completed"]
            WT ~~~ Status
        end
        
        subgraph TQ["Transfer Queue"]
            T1[" "]
        end
        
        subgraph TimerQ["Timer Queue"]
            TM1["Delete History (retention)"]
        end
    end
    
    subgraph History["Workflow History"]
        direction TB
        E1["1. WorkflowExecutionStarted"]
        E2["2. WorkflowTaskScheduled"]
        E3["3. WorkflowTaskStarted"]
        E4["4. WorkflowTaskCompleted"]
        E5["5. ActivityTaskScheduled"]
        E6["6. ActivityTaskStarted"]
        E7["7. ActivityTaskCompleted"]
        E8["8. WorkflowTaskScheduled"]
        E9["9. WorkflowTaskStarted"]
        E10["10. WorkflowTaskCompleted"]
        E11["11. WorkflowExecutionCompleted"]
        E1 ~~~ E2 ~~~ E3 ~~~ E4 ~~~ E5 ~~~ E6 ~~~ E7 ~~~ E8 ~~~ E9 ~~~ E10 ~~~ E11
    end
    
    State ~~~ History
    
    style State fill:#fff4e1
    style History fill:#e1f5ff
```

<Accordion title="Code Entrypoints">
  * History service `RespondWorkflowTaskCompleted` handler: `service/history/handler.go:478`
</Accordion>

## Alternative Path: Activity Failure and Retry

If an activity fails, it can be automatically retried:

```mermaid theme={null}
sequenceDiagram
    participant Worker
    participant Frontend
    participant History
    participant Persistence
    participant Matching
    
    Worker->>Frontend: RespondActivityTaskFailed
    Frontend->>History: RespondActivityTaskFailed
    History->>Persistence: UpdateWorkflowExecution
    note over Persistence: Append History Events:<br/>ActivityTaskFailed, ActivityTaskScheduled<br/>update MutableState & add Timer Task (retry delay)
    Persistence-->>History: Update Succeed
    History-->>Frontend: Respond Succeed
    Frontend-->>Worker: Respond Succeed
    
    Note over History: Wait for retry timer
    
    loop Queue Processor (after retry delay)
        History->>Persistence: GetHistoryTasks
        History->>History: ProcessTask
        History->>Matching: AddActivityTask
    end
```

### State After Activity Failure

```mermaid theme={null}
flowchart LR
    subgraph State["Workflow State"]
        direction TB
        
        subgraph MS["Mutable State"]
            WT["Workflow Task: Empty"]
            AT["Activity Task: Scheduled<br/>Attempt 2"]
            WT ~~~ AT
        end
        
        subgraph TQ["Transfer Queue"]
            T1[" "]
        end
        
        subgraph TimerQ["Timer Queue"]
            TM1["Activity Retry"]
            TM2["Workflow Timeout"]
            TM1 ~~~ TM2
        end
    end
    
    subgraph History["Workflow History"]
        direction TB
        E1["1. WorkflowExecutionStarted"]
        E2["2. WorkflowTaskScheduled"]
        E3["3. WorkflowTaskStarted"]
        E4["4. WorkflowTaskCompleted"]
        E5["5. ActivityTaskScheduled"]
        Note["...ActivityTaskStarted...<br/>...ActivityTaskFailed...<br/>...ActivityTaskScheduled (retry)..."]
        E1 ~~~ E2 ~~~ E3 ~~~ E4 ~~~ E5 ~~~ Note
    end
    
    State ~~~ History
    
    style State fill:#fff4e1
    style History fill:#e1f5ff
    style Note fill:#ffe1e1
```

<Accordion title="Code Entrypoints">
  * History service `RespondActivityTaskFailed` handler: `service/history/handler.go:400`
  * Activity retry timer handling: `service/history/timer_queue_active_task_executor.go:426`
</Accordion>

## Key Takeaways

<AccordionGroup>
  <Accordion title="Event Sourcing">
    Every state change is recorded as an immutable event in Workflow History. The complete history can be used to reconstruct any past state.
  </Accordion>

  <Accordion title="State Transitions">
    Each request (from user or worker) triggers a state transition that atomically:

    * Appends new events to history
    * Updates Mutable State
    * Creates new tasks (Transfer or Timer)
  </Accordion>

  <Accordion title="Task Queues as Buffers">
    History Service generates tasks that are processed asynchronously by Queue Processors, providing natural buffering and backpressure.
  </Accordion>

  <Accordion title="Worker-Driven Execution">
    Workflows only make progress when workers poll for and complete tasks. The cluster never directly executes user code.
  </Accordion>
</AccordionGroup>

## Further Reading

<CardGroup cols={2}>
  <Card title="History Service" icon="database" href="/architecture/history-service">
    Deep dive into History Service internals
  </Card>

  <Card title="Matching Service" icon="arrows-split-up-and-left" href="/architecture/matching-service">
    How task queues work
  </Card>

  <Card title="Event Sourcing" icon="timeline" href="/architecture/event-sourcing">
    Event sourcing implementation details
  </Card>

  <Card title="Architecture Overview" icon="sitemap" href="/architecture/overview">
    High-level system architecture
  </Card>
</CardGroup>