The Problem

Developers need a production‑grade, fault‑tolerant engine for long‑running business logic. Building that from scratch requires a durable workflow scheduler, state persistence, and a rich RPC API – all of which are non‑trivial to get right and to keep secure.

What This Does

The repository implements Temporal Server, a Go‑based execution platform that runs workflows and activities, stores state in a relational backend, and exposes gRPC services.

  • Core server code lives under cmd/server/main.go (the binary entry point) and the service/ package (≈ 1 k files).
  • API contracts are generated in api/ (protobuf files such as api/adminservice/v1/request_response.pb.go) and consumed by the server and client libraries.
  • Persistence schemas are defined in schema/ (SQL files) and the server uses the common/ utilities for logging, metrics, and retry logic.
  • Helper tools (e.g., tools/tdbg/, tools/check-dependencies/) aid development and CI.

How It Is Wired

  1. Process start – Execution begins in cmd/server/main.go. The main function creates a server instance, reads configuration files (via os.ReadFile in the init path), and calls Run on the server object.
  2. Server bootstrap – Run (called from ~117 places) wires together the gRPC listeners, metric collectors, and persistence layer. It eventually invokes startMetricsRecording (71 callers) and ThrottleRetryContext (72 callers) to set up retry policies.
  3. gRPC dispatch – Incoming RPCs hit the generated service stubs in api/adminservice/v1/service_grpc.pb.go. These stubs forward calls to concrete handlers in service/, which frequently use the ubiquitous helper Equal (247 callers) for protobuf equality checks and New (156 callers) for constructing request/response objects.
  4. Persistence – Handlers execute SQL defined in schema/ through the Go database/sql driver. The call graph shows many edges to Descriptor -> *rawDescGZIP (≈ 100+ calls) – the protobuf descriptor loader is a hot path for every RPC.
  5. External effects – Filesystem: main -> organizeBinaries → os.Chmod; init -> readFile → os.ReadFile; copyRecursive → os.Open. Network: downloadCLIForArch -> downloadFile → http.Get (used by the GitHub‑action build script). * No long‑running background processes are launched from the server binary itself.

The most “blast‑radius” symbols are Equal, append, and Invoke, each referenced from >200 distinct call sites, meaning a change there ripples through most of the codebase. The protobuf descriptor generation forms a dense hub; modifications to any .proto file will regenerate many of the 3 k functions listed under What Each File Is Responsible For.

How To Use It

# Clone the repo (use the exact URL required)
git clone https://github.com/moses-y/temporal
cd temporal

# Build the server binary
make build            # target defined in the Makefile

# Run a local dev cluster (Docker Compose)
docker compose -f develop/docker-compose/docker-compose.cdc.linux.yml up -d

Configuration – The server reads its YAML configuration from temporal/config.yaml (referenced in the init path). No environment variables are hard‑coded; the Docker compose files expose the usual ports (7233 for gRPC, 8233 for the Web UI).

Running – After the compose stack is up, start the binary:

./temporal-server start-dev   # binary produced by `make build`

The server will register its services, connect to the SQL persistence container, and listen for workflow submissions.

Real‑World Use

A typical client creates a workflow via the Go SDK:

c, _ := client.NewClient(client.Options{})
workflowID, err := client.ExecuteWorkflow(context.Background(),
    client.StartWorkflowOptions{ID: "order-123"},
    OrderWorkflow, orderID)

The SDK talks to the server’s gRPC endpoint (localhost:7233). The server routes the request through api/adminservice/v1/service_grpc.pb.go → service/ handlers → SQL persistence, guaranteeing exactly‑once execution even across crashes.

Code Health & Issues

  • Medium – Enable Dependabot – No .github/dependabot.yml present; 1 manifest (go.mod) lacks automated version updates.
  • Medium – Dependency‑vulnerability gate – CI workflows (.github/workflows/*.yml) do not run a vulnerability scanner. Add dependency-review-action or osv-scanner.
  • Low – Job timeouts – auto-approve-cicd-release-pr.yml defines three jobs without timeout-minutes. Set explicit limits to avoid overlapping runs.

Additional observations: a pair of PEM files (tools/tdbg/testdata/*.pem) are committed; they appear to be test certificates but should be reviewed for accidental secret leakage. CI runs, Dockerfile, and a LICENSE file are present, indicating a mature release process.

The Bottom Line

Temporal Server delivers a full‑featured, Go‑native workflow engine with a clear separation between API contracts, service logic, and persistence. The codebase is large (3 k Go files) and heavily centered on protobuf descriptors, so changes to core helpers (Equal, New) must be approached carefully. Automated dependency management and CI hardening are the most immediate gaps. Engineers familiar with Go, gRPC, and relational databases will find the project ready for extension or integration into production systems.