On this page

Walk through one task

Run pnpm tour and keep examples/src/tour.ts open. It starts the real service loops and an application worker, awaits a workflow result, and prints the recorded history. The sequence below explains how those independently running components produced the events. Every step between server roles is an internal RPC; run pnpm wire to print each call and its proto3 JSON payload.

  1. Frontend → History. WorkflowClient.start calls Frontend.StartWorkflowExecution, which sends historyservice.StartWorkflowExecution to the History host that owns the workflow's shard. History creates an execution, appends WorkflowStarted and WorkflowTaskScheduled, and stores a transfer task. The transfer processor can now deliver that task.
  2. History transfer → Matching. QueueProcessor.drain sends matchingservice.AddWorkflowTask to the Matching host that owns the task queue partition. History's service loop runs this asynchronously.
  3. Workflow poll → History. ApplicationWorker.run polls Frontend, which calls Matching. Matching calls historyservice.RecordWorkflowTaskStarted before returning the task, and builds the worker's response from History's answer: the history, event IDs, and a task token. The workflow yields an activity command; the worker sends it through Frontend to History, which validates and completes the Workflow Task, then atomically appends WorkflowTaskCompleted and CommandScheduled with an activity transfer task.
  4. Activity transfer → Matching. Background processing puts the activity task on the same named task queue, where an activity worker can poll it.
  5. Activity result → History. The worker polls through Frontend and Matching, which records ActivityTaskStarted in History. The worker calls greet and reports the result through Frontend. History appends CommandCompleted, then schedules another Workflow Task. The result is in history; the activity function need not run again during replay.
  6. Replay → completion. The worker starts the workflow generator from the beginning, compares its activity command to the saved command, feeds in the recorded result, and reaches return. History appends WorkflowCompleted; a background visibility task updates the read model.
sequenceDiagram
  participant C as Client
  participant F as Frontend
  participant H as History
  participant I as History Queue Processor
  participant M as Matching
  participant W as Application Worker
  C->>F: start workflow
  F->>H: create execution + events
  H->>I: transfer task
  I->>M: add Workflow Task
  W->>F: poll Workflow Task
  F->>M: poll Workflow Task
  M->>H: record Workflow Task started
  M-->>F: task + history
  F-->>W: task + history
  W->>F: schedule Activity command
  F->>H: schedule Activity
  H->>I: activity transfer task
  I->>M: add Activity Task
  W->>F: poll Activity Task
  F->>M: poll Activity Task
  M->>H: record Activity Task started
  M-->>F: task
  F-->>W: task
  W->>F: activity result
  F->>H: activity result
  H->>I: next Workflow Task transfer
  I->>M: add Workflow Task
  W->>F: poll Workflow Task
  F->>M: poll Workflow Task
  M->>H: record Workflow Task started
  M-->>F: task + history
  F-->>W: task + history
  W->>F: replay and complete
  F->>H: complete Workflow

The key distinction: the workflow execution is History state; a Matching task is a temporary delivery record. A single task queue can contain tasks from many executions. The event history is what lets the workflow worker rebuild its local state after a restart.