# academysoftwarefoundation/opencue architecture

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

- Interactive diagram: https://gitdiagram.com/academysoftwarefoundation/opencue
- Repository: https://github.com/academysoftwarefoundation/opencue
- Video tour (about a minute): https://gitdiagram.com/academysoftwarefoundation/opencue/video

## Overview

OpenCue is a render-farm management system. Artists and operators submit and manage jobs through client tools; Cuebot tracks jobs, layers, frames, and dependencies, then dispatches eligible work to render machines and records their reports. The README documents queue-based resource allocation, multi-facility deployment, tagging, and automated booking. The graph also includes the REST/web and monitoring capabilities visible in the repository tree. Some internal components are unsampled, so their relationships are shown only where the README or excerpts support them.

Main entry points: [`cuebot/src/main/java/com/imageworks/spcue/dispatcher/DispatchSupportService.java`](https://github.com/academysoftwarefoundation/opencue/blob/master/cuebot/src/main/java/com/imageworks/spcue/dispatcher/DispatchSupportService.java) (Dispatch and Booking), [`cuebot/src/main/java/com/imageworks/spcue/servant`](https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue/servant) (Cuebot API), [`cuebot/src/main/java/com/imageworks/spcue/service/JobManagerService.java`](https://github.com/academysoftwarefoundation/opencue/blob/master/cuebot/src/main/java/com/imageworks/spcue/service/JobManagerService.java) (Job Management), [`pycue/opencue/api.py`](https://github.com/academysoftwarefoundation/opencue/blob/master/pycue/opencue/api.py) (Python API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and APIs"]
  node_submit["Job Submission<br/>[Widgets.py]"]
  node_pythonapi["Python API<br/>[api.py]"]
  node_cli["Admin CLI<br/>[main.py]"]
  node_gui["Desktop GUI<br/>[Main.py]"]
  node_gateway["REST Gateway<br/>[main.go]"]
  node_web["Web UI"]
end

subgraph group_control["Cuebot Control"]
  node_cuebot["Cuebot API"]
  node_jobmanager["Job Management"]
  node_dependmanager["Dependency Management"]
  node_dispatch["Dispatch and Booking"]
  node_domain["Job and Frame Model"]
end

subgraph group_execution["Render Execution"]
  node_rqd["Render Agent<br/>[rqdservicers.py]"]
  node_rust_rqd["Rust Render Agent<br/>[manager.rs]"]
  node_workers(("Render Machines"))
end

subgraph group_state["State and Monitoring"]
  node_database[("Farm Database")]
  node_dao["Persistence Access"]
  node_metrics["Metrics and Events"]
  node_monitoring["Monitoring Stack"]
end

node_artists(("Artists and Operators"))

node_artists -->|"submit jobs"| node_submit
node_artists -->|"manage farm"| node_cli
node_artists -.->|"manage farm"| node_gui
node_artists -.->|"view farm"| node_web
node_submit -.->|"uses API"| node_pythonapi
node_cli -->|"calls"| node_pythonapi
node_gui -.->|"uses API"| node_pythonapi
node_web -.->|"requests"| node_gateway
node_pythonapi -.->|"sends requests"| node_cuebot
node_gateway -.->|"routes requests"| node_cuebot
node_cuebot -.->|"routes management"| node_jobmanager
node_jobmanager -->|"creates dependencies"| node_dependmanager
node_jobmanager -->|"reads and writes"| node_dao
node_dependmanager -->|"reads and writes"| node_dao
node_dependmanager -->|"publishes events"| node_metrics
node_cuebot -.->|"dispatches work"| node_dispatch
node_dispatch -->|"reads and updates"| node_dao
node_dao -.->|"persists state"| node_database
node_dispatch -.->|"launches frames"| node_rqd
node_rqd -->|"runs frames"| node_workers
node_dispatch -.->|"launches frames"| node_rust_rqd
node_rqd -.->|"reports status"| node_dispatch
node_rust_rqd -.->|"reports status"| node_dispatch
node_dispatch -->|"records usage"| node_metrics
node_metrics -.->|"exports telemetry"| node_monitoring
node_domain -.->|"models job state"| node_jobmanager

click node_submit "https://github.com/academysoftwarefoundation/opencue/blob/master/cuesubmit/cuesubmit/ui/Widgets.py"
click node_pythonapi "https://github.com/academysoftwarefoundation/opencue/blob/master/pycue/opencue/api.py"
click node_cli "https://github.com/academysoftwarefoundation/opencue/blob/master/cueman/cueman/main.py"
click node_gui "https://github.com/academysoftwarefoundation/opencue/blob/master/cuegui/cuegui/Main.py"
click node_gateway "https://github.com/academysoftwarefoundation/opencue/blob/master/rest_gateway/opencue_gateway/main.go"
click node_web "https://github.com/academysoftwarefoundation/opencue/tree/master/cueweb/app"
click node_cuebot "https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue/servant"
click node_jobmanager "https://github.com/academysoftwarefoundation/opencue/blob/master/cuebot/src/main/java/com/imageworks/spcue/service/JobManagerService.java"
click node_dependmanager "https://github.com/academysoftwarefoundation/opencue/blob/master/cuebot/src/main/java/com/imageworks/spcue/service/DependManagerService.java"
click node_dispatch "https://github.com/academysoftwarefoundation/opencue/blob/master/cuebot/src/main/java/com/imageworks/spcue/dispatcher/DispatchSupportService.java"
click node_domain "https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue"
click node_rqd "https://github.com/academysoftwarefoundation/opencue/blob/master/rqd/rqd/rqdservicers.py"
click node_rust_rqd "https://github.com/academysoftwarefoundation/opencue/blob/master/rust/crates/rqd/src/frame/manager.rs"
click node_dao "https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue/dao"
click node_metrics "https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue/monitoring"

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_submit,node_pythonapi,node_cli,node_gui,node_gateway,node_web toneBlue
class node_cuebot,node_jobmanager,node_dependmanager,node_dispatch,node_domain toneAmber
class node_rqd,node_rust_rqd,node_workers toneMint
class node_database,node_dao,node_metrics,node_monitoring toneRose
class node_artists toneIndigo
```

## Components

### Clients and APIs

- [Job Submission](https://github.com/academysoftwarefoundation/opencue/blob/master/cuesubmit/cuesubmit/ui/Widgets.py): `cuesubmit/cuesubmit/ui/Widgets.py`
- [Python API](https://github.com/academysoftwarefoundation/opencue/blob/master/pycue/opencue/api.py): `pycue/opencue/api.py`
- [Admin CLI](https://github.com/academysoftwarefoundation/opencue/blob/master/cueman/cueman/main.py): `cueman/cueman/main.py`
- [Desktop GUI](https://github.com/academysoftwarefoundation/opencue/blob/master/cuegui/cuegui/Main.py): `cuegui/cuegui/Main.py`
- [REST Gateway](https://github.com/academysoftwarefoundation/opencue/blob/master/rest_gateway/opencue_gateway/main.go): `rest_gateway/opencue_gateway/main.go`
- [Web UI](https://github.com/academysoftwarefoundation/opencue/tree/master/cueweb/app): `cueweb/app`

### Cuebot Control

- [Cuebot API](https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue/servant): `cuebot/src/main/java/com/imageworks/spcue/servant`
- [Job Management](https://github.com/academysoftwarefoundation/opencue/blob/master/cuebot/src/main/java/com/imageworks/spcue/service/JobManagerService.java): `cuebot/src/main/java/com/imageworks/spcue/service/JobManagerService.java`
- [Dependency Management](https://github.com/academysoftwarefoundation/opencue/blob/master/cuebot/src/main/java/com/imageworks/spcue/service/DependManagerService.java): `cuebot/src/main/java/com/imageworks/spcue/service/DependManagerService.java`
- [Dispatch and Booking](https://github.com/academysoftwarefoundation/opencue/blob/master/cuebot/src/main/java/com/imageworks/spcue/dispatcher/DispatchSupportService.java): `cuebot/src/main/java/com/imageworks/spcue/dispatcher/DispatchSupportService.java`
- [Job and Frame Model](https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue): `cuebot/src/main/java/com/imageworks/spcue`

### Render Execution

- [Render Agent](https://github.com/academysoftwarefoundation/opencue/blob/master/rqd/rqd/rqdservicers.py): `rqd/rqd/rqdservicers.py`
- [Rust Render Agent](https://github.com/academysoftwarefoundation/opencue/blob/master/rust/crates/rqd/src/frame/manager.rs): `rust/crates/rqd/src/frame/manager.rs`
- **Render Machines**

### State and Monitoring

- **Farm Database**
- [Persistence Access](https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue/dao): `cuebot/src/main/java/com/imageworks/spcue/dao`
- [Metrics and Events](https://github.com/academysoftwarefoundation/opencue/tree/master/cuebot/src/main/java/com/imageworks/spcue/monitoring): `cuebot/src/main/java/com/imageworks/spcue/monitoring`
- **Monitoring Stack**

### Other components

- **Artists and Operators**

## Connections

- Artists and Operators → Job Submission: submit jobs
- Artists and Operators → Admin CLI: manage farm
- Artists and Operators → Desktop GUI: manage farm
- Artists and Operators → Web UI: view farm
- Job Submission → Python API: uses API
- Admin CLI → Python API: calls (evidence: `cueman/cueman/main.py`)
- Desktop GUI → Python API: uses API
- Web UI → REST Gateway: requests
- Python API → Cuebot API: sends requests
- REST Gateway → Cuebot API: routes requests
- Cuebot API → Job Management: routes management
- Job Management → Dependency Management: creates dependencies (evidence: `cuebot/src/main/java/com/imageworks/spcue/service/JobManagerService.java`)
- Job Management → Persistence Access: reads and writes (evidence: `cuebot/src/main/java/com/imageworks/spcue/service/JobManagerService.java`)
- Dependency Management → Persistence Access: reads and writes (evidence: `cuebot/src/main/java/com/imageworks/spcue/service/DependManagerService.java`)
- Dependency Management → Metrics and Events: publishes events (evidence: `cuebot/src/main/java/com/imageworks/spcue/service/DependManagerService.java`)
- Cuebot API → Dispatch and Booking: dispatches work
- Dispatch and Booking → Persistence Access: reads and updates (evidence: `cuebot/src/main/java/com/imageworks/spcue/dispatcher/DispatchSupportService.java`)
- Persistence Access → Farm Database: persists state
- Dispatch and Booking → Render Agent: launches frames
- Render Agent → Render Machines: runs frames
- Dispatch and Booking → Rust Render Agent: launches frames
- Render Agent → Dispatch and Booking: reports status
- Rust Render Agent → Dispatch and Booking: reports status
- Dispatch and Booking → Metrics and Events: records usage (evidence: `cuebot/src/main/java/com/imageworks/spcue/dispatcher/DispatchSupportService.java`)
- Metrics and Events → Monitoring Stack: exports telemetry
- Job and Frame Model → Job Management: models job state (evidence: `cuebot/src/main/java/com/imageworks/spcue/service/JobManagerService.java`)
