# temporalio/temporal architecture

> Architecture diagram of the GitHub repository temporalio/temporal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/temporalio/temporal
- Repository: https://github.com/temporalio/temporal

## Overview

Temporal is a server-side durable execution platform: clients submit workflow operations, the server coordinates persistent workflow state and task dispatch, and workers perform application logic before reporting results. The source map identifies frontend, history, matching, CHASM, visibility, and persistence as major runtime areas; the README also highlights retries and resilient execution. Several implementation paths are documented by sampled references, but unsampled runtime handoffs are shown only as unverified dashed links or omitted.

Main entry points: [`service/frontend/workflow_handler.go`](https://github.com/temporalio/temporal/blob/main/service/frontend/workflow_handler.go) (Frontend API), [`service/history/history_engine.go`](https://github.com/temporalio/temporal/blob/main/service/history/history_engine.go) (History engine), [`service/matching/matching_engine.go`](https://github.com/temporalio/temporal/blob/main/service/matching/matching_engine.go) (Matching engine), [`common/persistence/visibility/visibility_manager_impl.go`](https://github.com/temporalio/temporal/blob/main/common/persistence/visibility/visibility_manager_impl.go) (Visibility manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client-facing services"]
  node_frontend["Frontend API"]
end

subgraph group_execution["Durable execution"]
  node_history["History engine<br/>[history_engine.go]"]
  node_chasm_engine["CHASM engine<br/>[chasm_engine.go]"]
  node_chasm["CHASM framework<br/>[engine.go]"]
  node_workflow["Workflow runtime<br/>[workflow.go]"]
  node_activity["Activity runtime<br/>[activity.go]"]
  node_scheduler["Schedules<br/>[scheduler.go]"]
  node_callback["Callbacks<br/>[component.go]"]
  node_nexus["Nexus operations<br/>[operation.go]"]
end

subgraph group_dispatch["Task dispatch"]
  node_matching["Matching engine<br/>[matching_engine.go]"]
  node_worker_query["Worker queries"]
end

subgraph group_state["State and operations"]
  node_replication["Namespace replication"]
  node_versioning["Worker versioning"]
  node_visibility["Visibility manager"]
  node_search_attributes["Search attributes<br/>[manager.go]"]
  node_execution_store[("Execution persistence")]
end

node_client(("Temporal clients"))
node_worker(("Application workers"))
node_database[("Persistence database")]
node_nexus_endpoint{{"Nexus endpoint"}}

node_client -.->|"submits requests"| node_frontend
node_frontend -.->|"routes operations"| node_history
node_history -.->|"delegates CHASM"| node_chasm_engine
node_chasm_engine -->|"uses framework"| node_chasm
node_history -->|"uses runtime"| node_workflow
node_frontend -->|"integrates activity"| node_activity
node_frontend -->|"integrates schedules"| node_scheduler
node_frontend -->|"integrates operations"| node_nexus
node_frontend -->|"integrates replication"| node_replication
node_history -->|"requests matching"| node_matching
node_matching -.->|"dispatches tasks"| node_worker
node_worker -.->|"polls tasks"| node_matching
node_matching -.->|"evaluates filters"| node_worker_query
node_matching -->|"uses routing data"| node_versioning
node_history -.->|"persists executions"| node_execution_store
node_execution_store -.->|"reads and writes"| node_database
node_visibility -->|"maps attributes"| node_search_attributes
node_visibility -.->|"stores visibility"| node_database
node_nexus -.->|"invokes endpoint"| node_nexus_endpoint
node_history -.->|"coordinates replication"| node_replication

click node_frontend "https://github.com/temporalio/temporal/blob/main/service/frontend/workflow_handler.go"
click node_history "https://github.com/temporalio/temporal/blob/main/service/history/history_engine.go"
click node_chasm_engine "https://github.com/temporalio/temporal/blob/main/service/history/chasm_engine.go"
click node_chasm "https://github.com/temporalio/temporal/blob/main/chasm/engine.go"
click node_workflow "https://github.com/temporalio/temporal/blob/main/chasm/lib/workflow/workflow.go"
click node_activity "https://github.com/temporalio/temporal/blob/main/chasm/lib/activity/activity.go"
click node_scheduler "https://github.com/temporalio/temporal/blob/main/chasm/lib/scheduler/scheduler.go"
click node_callback "https://github.com/temporalio/temporal/blob/main/chasm/lib/callback/component.go"
click node_nexus "https://github.com/temporalio/temporal/blob/main/chasm/lib/nexusoperation/operation.go"
click node_matching "https://github.com/temporalio/temporal/blob/main/service/matching/matching_engine.go"
click node_worker_query "https://github.com/temporalio/temporal/blob/main/service/matching/workers/worker_query_engine.go"
click node_replication "https://github.com/temporalio/temporal/blob/main/common/namespace/nsreplication/transmission_task_handler.go"
click node_versioning "https://github.com/temporalio/temporal/blob/main/common/worker_versioning/worker_versioning.go"
click node_visibility "https://github.com/temporalio/temporal/blob/main/common/persistence/visibility/visibility_manager_impl.go"
click node_search_attributes "https://github.com/temporalio/temporal/blob/main/common/searchattribute/manager.go"
click node_execution_store "https://github.com/temporalio/temporal/blob/main/common/persistence/execution_manager.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_client toneBlue
class node_history,node_chasm_engine,node_chasm,node_workflow,node_activity,node_scheduler,node_callback,node_nexus,node_database toneAmber
class node_matching,node_worker_query toneMint
class node_replication,node_versioning,node_visibility,node_search_attributes,node_execution_store,node_worker toneRose
class node_nexus_endpoint toneIndigo
```

## Components

### Client-facing services

- [Frontend API](https://github.com/temporalio/temporal/blob/main/service/frontend/workflow_handler.go): `service/frontend/workflow_handler.go`

### Durable execution

- [History engine](https://github.com/temporalio/temporal/blob/main/service/history/history_engine.go): `service/history/history_engine.go`
- [CHASM engine](https://github.com/temporalio/temporal/blob/main/service/history/chasm_engine.go): `service/history/chasm_engine.go`
- [CHASM framework](https://github.com/temporalio/temporal/blob/main/chasm/engine.go): `chasm/engine.go`
- [Workflow runtime](https://github.com/temporalio/temporal/blob/main/chasm/lib/workflow/workflow.go): `chasm/lib/workflow/workflow.go`
- [Activity runtime](https://github.com/temporalio/temporal/blob/main/chasm/lib/activity/activity.go): `chasm/lib/activity/activity.go`
- [Schedules](https://github.com/temporalio/temporal/blob/main/chasm/lib/scheduler/scheduler.go): `chasm/lib/scheduler/scheduler.go`
- [Callbacks](https://github.com/temporalio/temporal/blob/main/chasm/lib/callback/component.go): `chasm/lib/callback/component.go`
- [Nexus operations](https://github.com/temporalio/temporal/blob/main/chasm/lib/nexusoperation/operation.go): `chasm/lib/nexusoperation/operation.go`

### Task dispatch

- [Matching engine](https://github.com/temporalio/temporal/blob/main/service/matching/matching_engine.go): `service/matching/matching_engine.go`
- [Worker queries](https://github.com/temporalio/temporal/blob/main/service/matching/workers/worker_query_engine.go): `service/matching/workers/worker_query_engine.go`

### State and operations

- [Namespace replication](https://github.com/temporalio/temporal/blob/main/common/namespace/nsreplication/transmission_task_handler.go): `common/namespace/nsreplication/transmission_task_handler.go`
- [Worker versioning](https://github.com/temporalio/temporal/blob/main/common/worker_versioning/worker_versioning.go): `common/worker_versioning/worker_versioning.go`
- [Visibility manager](https://github.com/temporalio/temporal/blob/main/common/persistence/visibility/visibility_manager_impl.go): `common/persistence/visibility/visibility_manager_impl.go`
- [Search attributes](https://github.com/temporalio/temporal/blob/main/common/searchattribute/manager.go): `common/searchattribute/manager.go`
- [Execution persistence](https://github.com/temporalio/temporal/blob/main/common/persistence/execution_manager.go): `common/persistence/execution_manager.go`

### Other components

- **Temporal clients**
- **Application workers**
- **Persistence database**
- **Nexus endpoint**

## Connections

- Temporal clients → Frontend API: submits requests
- Frontend API → History engine: routes operations
- History engine → CHASM engine: delegates CHASM
- CHASM engine → CHASM framework: uses framework (evidence: `service/history/chasm_engine.go`)
- History engine → Workflow runtime: uses runtime (evidence: `service/history/history_engine.go`)
- Frontend API → Activity runtime: integrates activity (evidence: `service/frontend/workflow_handler.go`)
- Frontend API → Schedules: integrates schedules (evidence: `service/frontend/workflow_handler.go`)
- Frontend API → Nexus operations: integrates operations (evidence: `service/frontend/workflow_handler.go`)
- Frontend API → Namespace replication: integrates replication (evidence: `service/frontend/workflow_handler.go`)
- History engine → Matching engine: requests matching (evidence: `service/history/history_engine.go`)
- Matching engine → Application workers: dispatches tasks
- Application workers → Matching engine: polls tasks
- Matching engine → Worker queries: evaluates filters
- Matching engine → Worker versioning: uses routing data (evidence: `service/matching/matching_engine.go`)
- History engine → Execution persistence: persists executions
- Execution persistence → Persistence database: reads and writes
- Visibility manager → Search attributes: maps attributes (evidence: `common/persistence/visibility/visibility_manager_impl.go`)
- Visibility manager → Persistence database: stores visibility
- Nexus operations → Nexus endpoint: invokes endpoint
- History engine → Namespace replication: coordinates replication
