---
title: "Introduction to Temporal: Durable Execution for Distributed Systems"
description: "Learn what Temporal is, how its durable execution model works, and when to use it for long-running workflows, distributed transactions, and cross-service orchestration."
url: https://agent-zone.ai/knowledge/workflow-orchestration/temporal-introduction/
section: knowledge
date: 2026-02-22
categories: ["workflow-orchestration"]
tags: ["temporal","durable-execution","distributed-systems","workflows","activities","workers","task-queues"]
skills: ["temporal-concepts","workflow-design","distributed-system-patterns"]
tools: ["temporal","go"]
levels: ["beginner"]
word_count: 1265
formats:
  json: https://agent-zone.ai/knowledge/workflow-orchestration/temporal-introduction/index.json
  html: https://agent-zone.ai/knowledge/workflow-orchestration/temporal-introduction/?format=html
  api: https://api.agent-zone.ai/api/v1/knowledge/search?q=Introduction+to+Temporal%3A+Durable+Execution+for+Distributed+Systems
---


# Introduction to Temporal

Temporal is a durable execution engine. You write workflows as ordinary code -- if/else, loops, function calls -- and Temporal guarantees that code runs to completion even when processes crash, machines fail, or deployments happen mid-execution. It eliminates the need to build retry logic, state machines, and recovery mechanisms by hand.

This article introduces the core concepts, architecture, and use cases. It is the first in a series that takes you from zero to running production workflows on Kubernetes.

## What Is Durable Execution?

Consider a typical distributed operation: charge a customer, provision a resource, send a confirmation email. If the process crashes after charging but before provisioning, you need to figure out what already happened and resume from the right point. Traditionally, you solve this with message queues, database flags, cron jobs, and a lot of error-prone glue code.

Temporal removes that glue. You write the entire operation as a single function:

```go
func ProvisionWorkflow(ctx workflow.Context, req ProvisionRequest) error {
    err := workflow.ExecuteActivity(ctx, ChargeCustomer, req.PaymentInfo).Get(ctx, nil)
    if err != nil {
        return err
    }

    var resource ResourceInfo
    err = workflow.ExecuteActivity(ctx, ProvisionResource, req.ResourceSpec).Get(ctx, &resource)
    if err != nil {
        // Temporal can automatically retry, or you can compensate
        _ = workflow.ExecuteActivity(ctx, RefundCustomer, req.PaymentInfo).Get(ctx, nil)
        return err
    }

    return workflow.ExecuteActivity(ctx, SendConfirmation, resource).Get(ctx, nil)
}
```

If the worker process crashes after `ChargeCustomer` succeeds but before `ProvisionResource` starts, Temporal replays the workflow from the beginning. It does not re-execute `ChargeCustomer` -- it replays the recorded result from history and picks up exactly where execution left off.

## Core Concepts

Temporal has five building blocks that every developer needs to understand.

### Workflows

A workflow is a deterministic function that orchestrates work. Workflows can run for seconds or years. They must not perform side effects directly -- no HTTP calls, no database writes, no random numbers, no reading the current time. All side effects go through activities.

```go
// Workflow function signature - always takes workflow.Context and returns error
func MyWorkflow(ctx workflow.Context, input MyInput) (MyOutput, error) {
    // Orchestration logic only -- no side effects here
    var result MyOutput
    err := workflow.ExecuteActivity(ctx, MyActivity, input).Get(ctx, &result)
    return result, err
}
```

### Activities

Activities are the functions that do actual work -- call APIs, write to databases, read files, send emails. They can be retried independently, have configurable timeouts, and run in their own goroutine with a standard `context.Context`.

```go
// Activity function signature - takes context.Context, not workflow.Context
func MyActivity(ctx context.Context, input MyInput) (MyOutput, error) {
    // Real side effects go here
    resp, err := http.Post("https://api.example.com/provision", ...)
    if err != nil {
        return MyOutput{}, err
    }
    return parseResponse(resp)
}
```

### Workers

Workers are your processes. They poll Temporal Server for tasks, execute workflow and activity code, and report results back. You write the worker binary, deploy it however you like (Kubernetes, VMs, bare metal), and scale it horizontally.

### Task Queues

Task queues route work to workers. When you start a workflow, you specify which task queue it runs on. Workers register on specific task queues. This lets you route CPU-intensive work to beefy machines and lightweight orchestration to smaller instances.

### Namespaces

Namespaces provide isolation. Each namespace has its own workflow history, retention policy, and access controls. Use separate namespaces for different environments (dev, staging, prod) or different teams.

## Server Architecture

Temporal Server is a cluster of four services that work together.

| Service | Role |
|---|---|
| **Frontend** | API gateway. Receives gRPC requests from clients and workers, routes them to the appropriate internal service. |
| **History** | Maintains workflow execution state. Each workflow is assigned to a history shard. This is the most stateful component. |
| **Matching** | Dispatches tasks to workers. Manages task queue state, matches pending tasks with polling workers. |
| **Worker** | Runs Temporal's own internal workflows -- archival, replication, batch operations. Not to be confused with your application workers. |

These services are backed by a persistence layer:

- **Primary store**: PostgreSQL, MySQL, or Cassandra. Stores workflow history events, execution state, and visibility records.
- **Visibility store** (optional): Elasticsearch or the primary database. Enables listing and filtering workflows by custom attributes.

For local development, the Temporal CLI (`temporal server start-dev`) runs everything in a single process with SQLite. For production, you deploy the cluster on Kubernetes with a real database. See [Running Temporal Server on Minikube](../temporal-minikube-setup/) for a full setup guide.

## Durable Execution Model

Temporal's durability comes from event sourcing. Every action in a workflow -- starting an activity, receiving a signal, completing a timer -- is recorded as an event in the workflow's history.

When a worker crashes and restarts, or when a workflow is moved to a different worker, Temporal replays the event history through the workflow function. The function re-executes, but instead of actually running activities, the replay uses the recorded results from history.

This is why workflows must be deterministic. If the workflow function produces different decisions on replay than it did originally, the execution is corrupted. Specifically, you must not:

- **Call `time.Now()`** -- use `workflow.Now(ctx)` instead
- **Use `rand`** -- use `workflow.SideEffect` for non-deterministic values
- **Spawn goroutines** -- use `workflow.Go` for concurrent work
- **Make network calls** -- all I/O goes through activities
- **Read environment variables** that might change between replays

```go
// WRONG - non-deterministic
func BadWorkflow(ctx workflow.Context) error {
    if time.Now().Hour() > 17 {  // time.Now changes on replay
        // ...
    }
    return nil
}

// CORRECT - deterministic
func GoodWorkflow(ctx workflow.Context) error {
    if workflow.Now(ctx).Hour() > 17 {  // replays consistently
        // ...
    }
    return nil
}
```

## When to Use Temporal

Temporal is the right choice when your operation involves multiple steps that need reliability guarantees.

**Long-running processes.** Operations that take minutes, hours, or days -- provisioning infrastructure, processing data pipelines, managing subscription lifecycles. Temporal workflows can run indefinitely without holding resources.

**Distributed transactions.** When you need to coordinate changes across multiple services and handle partial failures with compensating actions. Temporal implements the [Saga pattern](../../microservices/saga-pattern/) naturally through workflow code.

**Human-in-the-loop.** Approval flows, review processes, and onboarding workflows where execution pauses for human input. Temporal signals let you send data to a running workflow from outside.

**Scheduled and recurring jobs.** Cron-like schedules with built-in visibility, retry handling, and execution history. Replace fragile crontab entries with Temporal schedules.

**Cross-service orchestration.** Coordinating work across microservices without tight coupling. Each service exposes activities; the workflow orchestrates them.

## When NOT to Use Temporal

Not everything belongs in a workflow engine.

**Simple CRUD operations.** If your API handler reads from a database and returns a response, adding Temporal is overhead with no benefit.

**Sub-second latency requirements.** Temporal adds latency -- typically 50-200ms per activity dispatch. For hot-path request handling, this is too slow.

**Single-service operations.** If your entire operation runs within one service and a database transaction handles atomicity, you do not need distributed orchestration.

**Fire-and-forget messaging.** If you just need to publish an event to a queue and do not care about the outcome, a message broker is simpler.

## Series Overview

This series walks through Temporal from local setup to production patterns:

1. **Introduction to Temporal** -- this article
2. [Running Temporal Server on Minikube](../temporal-minikube-setup/) -- deploy Temporal on local Kubernetes
3. [Temporal High Availability](../temporal-ha-cluster/) -- multi-replica production cluster
4. [Namespaces and Task Queues](../temporal-namespaces-task-queues/) -- organizing workflows and routing work
5. [Your First Temporal Workflow in Go](../temporal-go-workflow-basics/) -- DI, idempotency, and the worker pattern

All code examples reference the companion repository at [github.com/statherm/temporal-examples](https://github.com/statherm/temporal-examples). Clone it to follow along:

```bash
git clone https://github.com/statherm/temporal-examples.git
cd temporal-examples
```

The repository includes a Makefile that automates cluster setup, Temporal deployment, and running example workflows. Start with `make help` to see available targets.

## Next Steps

If you already understand the concepts and want to get Temporal running, proceed to [Running Temporal Server on Minikube](../temporal-minikube-setup/). If you want to jump straight to writing Go workflows, see [Your First Temporal Workflow in Go](../temporal-go-workflow-basics/).