# temporalio/omes architecture

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

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

## Overview

Omes drives Temporal load through registered scenarios and executors, with workers in multiple SDK languages consuming the resulting tasks. A separate project harness supports user-authored apps; worker metrics and Temporal integrations are additional runtime capabilities. The README documents the workflow and sidecar, while source excerpts and the index support only selected dispatch and worker links, so unsampled connections are omitted.

Main entry points: [`workers/python/apps/worker/app.py`](https://github.com/temporalio/omes/blob/main/workers/python/apps/worker/app.py) (Kitchen Sink Worker), [`cmd/omes/main.go`](https://github.com/temporalio/omes/blob/main/cmd/omes/main.go) (Omes CLI), [`internal/workerctl`](https://github.com/temporalio/omes/tree/main/internal/workerctl) (Worker Control), [`workers/python/harness/src/harness/main.py`](https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/main.py) (Harness Dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runner["Load Runner"]
  node_omes_cli["Omes CLI<br/>[main.go]"]
  node_scenario_registry["Scenario Registry"]
  node_scenario["Scenario Definitions"]
  node_loadgen["Load Executors"]
  node_kitchen_exec["Kitchen Sink Executor"]
  node_fuzz_gen["Action Generator<br/>[main.rs]"]
  node_worker_control["Worker Control"]
  node_worker_pool["Worker Pool<br/>[workerpool.go]"]
end

subgraph group_project["Project Harness"]
  node_project_scenario["Project Scenario"]
  node_project_runner["Project Runner<br/>[project.py]"]
  node_project_app["User Project App<br/>[app.py]"]
  node_harness_dispatch["Harness Dispatch<br/>[main.py]"]
end

subgraph group_workers["SDK Workers"]
  node_sdk_client["SDK Client<br/>[client.py]"]
  node_worker_harness["Worker Harness<br/>[worker.py]"]
  node_worker_app["Kitchen Sink Worker<br/>[app.py]"]
  node_workflow_actions["Workflow Actions<br/>[kitchen_sink.py]"]
  node_activity_actions["Activities<br/>[activities.py]"]
  node_nexus["Nexus Service<br/>[nexus_service.py]"]
end

subgraph group_telemetry["Metrics"]
  node_process_metrics["Process Metrics Sidecar"]
  node_prometheus["Prometheus Export<br/>[prometheus.go]"]
end

node_operator(("Operator"))
node_temporal{{"Temporal Server"}}
node_worker_process{{"Worker Process"}}

node_operator -->|"invokes"| node_omes_cli
node_omes_cli -->|"registers"| node_scenario_registry
node_scenario_registry -.->|"provides"| node_scenario
node_scenario -->|"starts"| node_loadgen
node_loadgen -.->|"selects"| node_kitchen_exec
node_kitchen_exec -.->|"produces load"| node_temporal
node_fuzz_gen -.->|"generates actions"| node_kitchen_exec
node_omes_cli -.->|"runs worker"| node_worker_control
node_worker_control -.->|"starts processes"| node_worker_pool
node_worker_pool -->|"manages"| node_worker_process
node_operator -->|"configures"| node_project_scenario
node_project_scenario -.->|"drives via gRPC"| node_project_runner
node_project_runner -.->|"dispatches load"| node_project_app
node_project_app -->|"registers with"| node_harness_dispatch
node_harness_dispatch -->|"dispatches mode"| node_project_runner
node_harness_dispatch -->|"dispatches mode"| node_worker_harness
node_worker_harness -.->|"creates client"| node_sdk_client
node_worker_harness -.->|"runs factory"| node_worker_app
node_worker_app -->|"registers workflow"| node_workflow_actions
node_worker_app -->|"registers activities"| node_activity_actions
node_worker_app -->|"registers handler"| node_nexus
node_sdk_client -.->|"connects"| node_temporal
node_worker_process -.->|"consumes tasks"| node_temporal
node_worker_control -->|"starts sidecar"| node_process_metrics
node_process_metrics -->|"monitors"| node_worker_process
node_process_metrics -.->|"exports metrics"| node_prometheus

click node_omes_cli "https://github.com/temporalio/omes/blob/main/cmd/omes/main.go"
click node_scenario_registry "https://github.com/temporalio/omes/tree/main/scenarios"
click node_scenario "https://github.com/temporalio/omes/tree/main/scenarios"
click node_loadgen "https://github.com/temporalio/omes/tree/main/loadgen"
click node_kitchen_exec "https://github.com/temporalio/omes/blob/main/loadgen/kitchensink/client_action_executor.go"
click node_fuzz_gen "https://github.com/temporalio/omes/blob/main/loadgen/kitchen-sink-gen/src/main.rs"
click node_worker_control "https://github.com/temporalio/omes/tree/main/internal/workerctl"
click node_worker_pool "https://github.com/temporalio/omes/blob/main/internal/workertest/workerpool.go"
click node_project_scenario "https://github.com/temporalio/omes/tree/main/scenarios/project"
click node_project_runner "https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/project.py"
click node_project_app "https://github.com/temporalio/omes/blob/main/workers/python/apps/helloworld/app.py"
click node_harness_dispatch "https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/main.py"
click node_sdk_client "https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/client.py"
click node_worker_harness "https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/worker.py"
click node_worker_app "https://github.com/temporalio/omes/blob/main/workers/python/apps/worker/app.py"
click node_workflow_actions "https://github.com/temporalio/omes/blob/main/workers/python/kitchen_sink.py"
click node_activity_actions "https://github.com/temporalio/omes/blob/main/workers/python/activities.py"
click node_nexus "https://github.com/temporalio/omes/blob/main/workers/python/nexus_service.py"
click node_process_metrics "https://github.com/temporalio/omes/tree/main/metrics"
click node_prometheus "https://github.com/temporalio/omes/blob/main/metrics/prometheus.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_omes_cli,node_scenario_registry,node_scenario,node_loadgen,node_kitchen_exec,node_fuzz_gen,node_worker_control,node_worker_pool toneBlue
class node_project_scenario,node_project_runner,node_project_app,node_harness_dispatch toneAmber
class node_sdk_client,node_worker_harness,node_worker_app,node_workflow_actions,node_activity_actions,node_nexus,node_temporal toneMint
class node_process_metrics,node_prometheus,node_worker_process toneRose
class node_operator toneIndigo
```

## Components

### Load Runner

- [Omes CLI](https://github.com/temporalio/omes/blob/main/cmd/omes/main.go): `cmd/omes/main.go`
- [Scenario Registry](https://github.com/temporalio/omes/tree/main/scenarios): `scenarios`
- [Scenario Definitions](https://github.com/temporalio/omes/tree/main/scenarios): `scenarios`
- [Load Executors](https://github.com/temporalio/omes/tree/main/loadgen): `loadgen`
- [Kitchen Sink Executor](https://github.com/temporalio/omes/blob/main/loadgen/kitchensink/client_action_executor.go): `loadgen/kitchensink/client_action_executor.go`
- [Action Generator](https://github.com/temporalio/omes/blob/main/loadgen/kitchen-sink-gen/src/main.rs): `loadgen/kitchen-sink-gen/src/main.rs`
- [Worker Control](https://github.com/temporalio/omes/tree/main/internal/workerctl): `internal/workerctl`
- [Worker Pool](https://github.com/temporalio/omes/blob/main/internal/workertest/workerpool.go): `internal/workertest/workerpool.go`

### Project Harness

- [Project Scenario](https://github.com/temporalio/omes/tree/main/scenarios/project): `scenarios/project`
- [Project Runner](https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/project.py): `workers/python/harness/src/harness/project.py`
- [User Project App](https://github.com/temporalio/omes/blob/main/workers/python/apps/helloworld/app.py): `workers/python/apps/helloworld/app.py`
- [Harness Dispatch](https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/main.py): `workers/python/harness/src/harness/main.py`

### SDK Workers

- [SDK Client](https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/client.py): `workers/python/harness/src/harness/client.py`
- [Worker Harness](https://github.com/temporalio/omes/blob/main/workers/python/harness/src/harness/worker.py): `workers/python/harness/src/harness/worker.py`
- [Kitchen Sink Worker](https://github.com/temporalio/omes/blob/main/workers/python/apps/worker/app.py): `workers/python/apps/worker/app.py`
- [Workflow Actions](https://github.com/temporalio/omes/blob/main/workers/python/kitchen_sink.py): `workers/python/kitchen_sink.py`
- [Activities](https://github.com/temporalio/omes/blob/main/workers/python/activities.py): `workers/python/activities.py`
- [Nexus Service](https://github.com/temporalio/omes/blob/main/workers/python/nexus_service.py): `workers/python/nexus_service.py`

### Metrics

- [Process Metrics Sidecar](https://github.com/temporalio/omes/tree/main/metrics): `metrics`
- [Prometheus Export](https://github.com/temporalio/omes/blob/main/metrics/prometheus.go): `metrics/prometheus.go`

### Other components

- **Operator**
- **Temporal Server**
- **Worker Process**

## Connections

- Operator → Omes CLI: invokes
- Omes CLI → Scenario Registry: registers (evidence: `cmd/omes/main.go`)
- Scenario Registry → Scenario Definitions: provides
- Scenario Definitions → Load Executors: starts
- Load Executors → Kitchen Sink Executor: selects
- Kitchen Sink Executor → Temporal Server: produces load
- Action Generator → Kitchen Sink Executor: generates actions
- Omes CLI → Worker Control: runs worker
- Worker Control → Worker Pool: starts processes (evidence: `internal/workertest/workerpool.go`)
- Worker Pool → Worker Process: manages (evidence: `internal/workertest/workerpool.go`)
- Operator → Project Scenario: configures
- Project Scenario → Project Runner: drives via gRPC
- Project Runner → User Project App: dispatches load
- User Project App → Harness Dispatch: registers with (evidence: `workers/python/apps/helloworld/app.py`)
- Harness Dispatch → Project Runner: dispatches mode (evidence: `workers/python/harness/src/harness/main.py`)
- Harness Dispatch → Worker Harness: dispatches mode (evidence: `workers/python/harness/src/harness/main.py`)
- Worker Harness → SDK Client: creates client (evidence: `workers/python/harness/src/harness/main.py`)
- Worker Harness → Kitchen Sink Worker: runs factory
- Kitchen Sink Worker → Workflow Actions: registers workflow (evidence: `workers/python/apps/worker/app.py`)
- Kitchen Sink Worker → Activities: registers activities (evidence: `workers/python/apps/worker/app.py`)
- Kitchen Sink Worker → Nexus Service: registers handler (evidence: `workers/python/apps/worker/app.py`)
- SDK Client → Temporal Server: connects
- Worker Process → Temporal Server: consumes tasks
- Worker Control → Process Metrics Sidecar: starts sidecar
- Process Metrics Sidecar → Worker Process: monitors
- Process Metrics Sidecar → Prometheus Export: exports metrics
