# conductor-oss/conductor architecture

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

- Interactive diagram: https://gitdiagram.com/conductor-oss/conductor
- Repository: https://github.com/conductor-oss/conductor

## Overview

Conductor is a durable workflow and agent execution platform. Users define or update a workflow, start an execution, and inspect or recover its persisted progress; workers and built-in tasks perform the work. The map also preserves the documented agent, scheduling, API, and UI capabilities. Several relationships are documented in the README; source-level edges are limited to relationships visible in sampled excerpts or the SOURCE INDEX, so unsampled wiring is omitted.

Main entry points: [`agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java`](https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java) (Agent lifecycle), [`core/src/main/java/com/netflix/conductor/service/ExecutionService.java`](https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/com/netflix/conductor/service/ExecutionService.java) (Execution service), [`ai/src/main/java/org/conductoross/conductor/ai/tasks/mapper/ChatCompleteTaskMapper.java`](https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/tasks/mapper/ChatCompleteTaskMapper.java) (AI workflow tasks), [`common/src/main/java/com/netflix/conductor/common/run/Workflow.java`](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/run/Workflow.java) (Workflow state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow Runtime"]
  node_workflow_defs["Workflow definitions<br/>[WorkflowDef.java]"]
  node_execution_api["Execution service"]
  node_decider["Workflow decider"]
  node_workflow_state["Workflow state<br/>[Workflow.java]"]
  node_task_state["Task state<br/>[Task.java]"]
  node_workers["Workers and tasks<br/>[LLMWorkers.java]"]
end

subgraph group_agents["Agent and AI"]
  node_agent_api["Agent API"]
  node_agent_service["Agent lifecycle<br/>[AgentService.java]"]
  node_normalizers["SDK normalizers"]
  node_agent_compilers["Agent compilers<br/>[AgentCompiler.java]"]
  node_ai_tasks["AI workflow tasks"]
  node_ai_models["LLM providers<br/>[OpenAI.java]"]
  node_mcp["MCP tools<br/>[MCPService.java]"]
  node_a2a["A2A integration<br/>[A2AService.java]"]
end

subgraph group_operations["Operations"]
  node_scheduler["Workflow scheduler"]
  node_recovery["Execution recovery"]
  node_ui["Web UI"]
end

subgraph group_storage["Storage"]
  node_payload_storage[("External payload storage")]
  node_file_service["File service"]
  node_file_backend[("File backend")]
end

node_developer(("Developer / API user"))

node_developer -->|"defines workflows"| node_workflow_defs
node_developer -->|"starts executions"| node_execution_api
node_execution_api -.->|"runs workflow"| node_workflow_state
node_decider -.->|"orchestrates tasks"| node_task_state
node_workers -.->|"executes tasks"| node_task_state
node_scheduler -.->|"starts schedules"| node_execution_api
node_developer -->|"recovers execution"| node_recovery
node_developer -->|"inspects execution"| node_ui
node_agent_api -.->|"routes requests"| node_agent_service
node_agent_service -->|"normalizes configs"| node_normalizers
node_agent_service -->|"compiles agents"| node_agent_compilers
node_agent_compilers -.->|"creates definitions"| node_workflow_defs
node_ai_tasks -.->|"calls providers"| node_ai_models
node_ai_tasks -.->|"calls tools"| node_mcp
node_developer -.->|"connects agents"| node_a2a
node_workflow_state -.->|"externalizes payloads"| node_payload_storage
node_developer -.->|"uploads files"| node_file_service
node_file_service -.->|"stores content"| node_file_backend

click node_workflow_defs "https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/workflow/WorkflowDef.java"
click node_execution_api "https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/com/netflix/conductor/service/ExecutionService.java"
click node_decider "https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/com/netflix/conductor/core/execution/DeciderService.java"
click node_workflow_state "https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/run/Workflow.java"
click node_task_state "https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java"
click node_workers "https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/tasks/worker/LLMWorkers.java"
click node_scheduler "https://github.com/conductor-oss/conductor/blob/main/scheduler/core/src/main/java/io/orkes/conductor/scheduler/service/SchedulerService.java"
click node_recovery "https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/com/netflix/conductor/core/reconciliation/WorkflowRepairService.java"
click node_ui "https://github.com/conductor-oss/conductor/blob/main/ui-next/src/pages/execution/RightPanel/useFullWorkflowQuery.ts"
click node_agent_api "https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/controller/AgentController.java"
click node_agent_service "https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java"
click node_normalizers "https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/normalizer/NormalizerRegistry.java"
click node_agent_compilers "https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java"
click node_ai_tasks "https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/tasks/mapper/ChatCompleteTaskMapper.java"
click node_ai_models "https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/providers/openai/OpenAI.java"
click node_mcp "https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/mcp/MCPService.java"
click node_a2a "https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/a2a/A2AService.java"
click node_payload_storage "https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/utils/ExternalPayloadStorage.java"
click node_file_service "https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/org/conductoross/conductor/core/storage/FileStorageService.java"
click node_file_backend "https://github.com/conductor-oss/conductor/blob/main/file-storage/src/main/java/org/conductoross/conductor/filestorage/storage/ConductorFileStorage.java"

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_workflow_defs,node_execution_api,node_decider,node_workflow_state,node_task_state,node_workers,node_developer toneBlue
class node_agent_api,node_agent_service,node_normalizers,node_agent_compilers,node_ai_tasks,node_ai_models,node_mcp,node_a2a toneAmber
class node_scheduler,node_recovery,node_ui toneMint
class node_payload_storage,node_file_service,node_file_backend toneRose
```

## Components

### Workflow Runtime

- [Workflow definitions](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/workflow/WorkflowDef.java): `common/src/main/java/com/netflix/conductor/common/metadata/workflow/WorkflowDef.java`
- [Execution service](https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/com/netflix/conductor/service/ExecutionService.java): `core/src/main/java/com/netflix/conductor/service/ExecutionService.java`
- [Workflow decider](https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/com/netflix/conductor/core/execution/DeciderService.java): `core/src/main/java/com/netflix/conductor/core/execution/DeciderService.java`
- [Workflow state](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/run/Workflow.java): `common/src/main/java/com/netflix/conductor/common/run/Workflow.java`
- [Task state](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java): `common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java`
- [Workers and tasks](https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/tasks/worker/LLMWorkers.java): `ai/src/main/java/org/conductoross/conductor/ai/tasks/worker/LLMWorkers.java`

### Agent and AI

- [Agent API](https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/controller/AgentController.java): `agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/controller/AgentController.java`
- [Agent lifecycle](https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java): `agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java`
- [SDK normalizers](https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/normalizer/NormalizerRegistry.java): `agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/normalizer/NormalizerRegistry.java`
- [Agent compilers](https://github.com/conductor-oss/conductor/blob/main/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java): `agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java`
- [AI workflow tasks](https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/tasks/mapper/ChatCompleteTaskMapper.java): `ai/src/main/java/org/conductoross/conductor/ai/tasks/mapper/ChatCompleteTaskMapper.java`
- [LLM providers](https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/providers/openai/OpenAI.java): `ai/src/main/java/org/conductoross/conductor/ai/providers/openai/OpenAI.java`
- [MCP tools](https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/mcp/MCPService.java): `ai/src/main/java/org/conductoross/conductor/ai/mcp/MCPService.java`
- [A2A integration](https://github.com/conductor-oss/conductor/blob/main/ai/src/main/java/org/conductoross/conductor/ai/a2a/A2AService.java): `ai/src/main/java/org/conductoross/conductor/ai/a2a/A2AService.java`

### Operations

- [Workflow scheduler](https://github.com/conductor-oss/conductor/blob/main/scheduler/core/src/main/java/io/orkes/conductor/scheduler/service/SchedulerService.java): `scheduler/core/src/main/java/io/orkes/conductor/scheduler/service/SchedulerService.java`
- [Execution recovery](https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/com/netflix/conductor/core/reconciliation/WorkflowRepairService.java): `core/src/main/java/com/netflix/conductor/core/reconciliation/WorkflowRepairService.java`
- [Web UI](https://github.com/conductor-oss/conductor/blob/main/ui-next/src/pages/execution/RightPanel/useFullWorkflowQuery.ts): `ui-next/src/pages/execution/RightPanel/useFullWorkflowQuery.ts`

### Storage

- [External payload storage](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/utils/ExternalPayloadStorage.java): `common/src/main/java/com/netflix/conductor/common/utils/ExternalPayloadStorage.java`
- [File service](https://github.com/conductor-oss/conductor/blob/main/core/src/main/java/org/conductoross/conductor/core/storage/FileStorageService.java): `core/src/main/java/org/conductoross/conductor/core/storage/FileStorageService.java`
- [File backend](https://github.com/conductor-oss/conductor/blob/main/file-storage/src/main/java/org/conductoross/conductor/filestorage/storage/ConductorFileStorage.java): `file-storage/src/main/java/org/conductoross/conductor/filestorage/storage/ConductorFileStorage.java`

### Other components

- **Developer / API user**

## Connections

- Developer / API user → Workflow definitions: defines workflows (evidence: `README.md`)
- Developer / API user → Execution service: starts executions (evidence: `README.md`)
- Execution service → Workflow state: runs workflow (evidence: `core/src/main/java/com/netflix/conductor/service/ExecutionService.java`)
- Workflow decider → Task state: orchestrates tasks (evidence: `core/src/main/java/com/netflix/conductor/core/execution/DeciderService.java`)
- Workers and tasks → Task state: executes tasks (evidence: `README.md`)
- Workflow scheduler → Execution service: starts schedules
- Developer / API user → Execution recovery: recovers execution (evidence: `README.md`)
- Developer / API user → Web UI: inspects execution (evidence: `README.md`)
- Agent API → Agent lifecycle: routes requests
- Agent lifecycle → SDK normalizers: normalizes configs (evidence: `agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java`)
- Agent lifecycle → Agent compilers: compiles agents (evidence: `agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java`)
- Agent compilers → Workflow definitions: creates definitions
- AI workflow tasks → LLM providers: calls providers
- AI workflow tasks → MCP tools: calls tools (evidence: `README.md`)
- Developer / API user → A2A integration: connects agents
- Workflow state → External payload storage: externalizes payloads (evidence: `common/src/main/java/com/netflix/conductor/common/utils/ExternalPayloadStorage.java`)
- Developer / API user → File service: uploads files
- File service → File backend: stores content (evidence: `core/src/main/java/org/conductoross/conductor/core/storage/FileStorageService.java`)
