Temporal Server

Temporal is a durable execution platform that runs application logic — Workflows — reliably in the face of process crashes, network partitions, and other intermittent failures. This repository is the Go implementation of the Temporal Server: the backend cluster that durably persists workflow state, dispatches tasks to user-hosted workers, and exposes a gRPC and HTTP API consumed by SDKs in many languages.

This wiki is generated from the source code at commit 458f2238b on the main branch and is structured for engineers contributing to the server itself, not for application developers using a Temporal SDK. For end-user docs see docs.temporal.io.

What this server does

A Temporal cluster runs four cooperating gRPC services:

Service	Role
Frontend (service/frontend)	Public API gateway: authenticates, rate-limits, routes RPCs to the right backend service.
History (service/history)	Owns workflow state. Persists History Events, mutable state, and timer/transfer/visibility task queues.
Matching (service/matching)	Owns user-facing Task Queues. Buffers Workflow / Activity tasks until a worker polls.
Worker (service/worker)	Internal worker host that runs system workflows: replication, batch jobs, scheduling, scanners, DLQ, etc.

These four services are normally co-deployed, but each can be scaled and upgraded independently. The cluster is fronted by a pluggable persistence layer (Cassandra, MySQL, PostgreSQL, or SQLite) and an optional visibility store (Elasticsearch or SQL).

graph TD
    SDK[User Application / Worker<br/>using Temporal SDK]
    UI[Web UI / Temporal CLI]
    FE[Frontend Service]
    H[History Service]
    M[Matching Service]
    W[Worker Service]
    DB[(Persistence:<br/>Cassandra / MySQL /<br/>PostgreSQL / SQLite)]
    ES[(Visibility:<br/>Elasticsearch / SQL)]

    SDK -->|gRPC| FE
    UI -->|gRPC / HTTP| FE
    FE -->|gRPC| H
    FE -->|gRPC| M
    FE -->|gRPC| W
    H <-->|gRPC| M
    H -->|persistence iface| DB
    H -->|visibility iface| ES
    W -->|internal SDK| FE
    M --> DB

Repository layout at a glance

Top-level path	Purpose
cmd/server/	The temporal-server binary entry point — see cmd/server/main.go.
temporal/	The Server struct, fx wiring, top-level lifecycle.
service/	The four service implementations: frontend, history, matching, worker.
common/	Shared infrastructure: persistence, RPC, dynamic config, metrics, logging, archiver, namespace cache.
chasm/	The CHASM framework — a generalised state-machine runtime that workflows, schedulers, and Nexus build on.
components/	Concrete CHASM components shipped with the server (callbacks, nexusoperations).
client/	Inter-service gRPC clients used by Frontend ↔ History ↔ Matching.
api/	Generated Go code for internal proto services (historyservice, matchingservice, etc.).
proto/internal/	Source .proto files for internal services; the public API protos live in go.temporal.io/api.
schema/	Database schema files for Cassandra, MySQL, Postgres, SQLite, Elasticsearch.
config/	Example YAML configs for the various development environments.
tests/	Functional / E2E tests that spin up an in-process cluster.
tools/	Operator CLI (tdbg), schema migration tools, code generators.
docs/architecture/	Hand-written architecture notes maintained by the team.

Where to start reading

If you want to…	Start here
Understand the request lifecycle	Architecture, then Workflow lifecycle
Build the server locally	Getting started
Submit a PR	How to contribute
Learn the CHASM state-machine framework	Systems → CHASM
Add a new gRPC API	API reference, Frontend service
Add a new persistence backend	Systems → Persistence
Operate Temporal in production	Deployment, How to monitor

Project facts

• Language: Go (go 1.26.2, see go.mod)
• Module: go.temporal.io/server
• License: MIT
• Origin: Forked from Uber's Cadence in 2019 and continuously rewritten — see Lore.
• Current maintainer: Temporal Technologies