# ray-project/ray architecture

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

- Interactive diagram: https://gitdiagram.com/ray-project/ray
- Repository: https://github.com/ray-project/ray

## Overview

Ray is a framework for scaling Python and AI workloads from a laptop to a cluster. The central workflow starts with an application submitting tasks or creating actors; Ray executes work across a cluster and makes immutable objects available to consumers. Around that runtime, the README identifies Data, Train, Tune, RLlib, and Serve as major AI libraries, with dashboard monitoring and distributed debugging. The graph preserves these documented branches; internal links for unsampled subsystems are omitted rather than inferred.

Main entry points: [`python/ray/_private/worker.py`](https://github.com/ray-project/ray/blob/master/python/ray/_private/worker.py) (Worker API), [`src/ray/raylet/node_manager.cc`](https://github.com/ray-project/ray/blob/master/src/ray/raylet/node_manager.cc) (Cluster scheduler), [`python/ray/data`](https://github.com/ray-project/ray/tree/master/python/ray/data) (Ray Data), [`rllib`](https://github.com/ray-project/ray/tree/master/rllib) (Reinforcement learning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Ray Core"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_worker["Worker API<br/>[worker.py]"]
  node_actors["Actors<br/>[actor.py]"]
  node_task_manager["Task manager<br/>[task_manager.cc]"]
  node_scheduler["Cluster scheduler<br/>[node_manager.cc]"]
  node_objects[("Distributed objects<br/>[object_manager.cc]")]
  node_gcs[("Global control store")]
end

subgraph group_data["Data Processing"]
  node_data["Ray Data"]
  node_data_collections["Data utilities<br/>[collections.py]"]
  node_torch_preprocess["Torch preprocessing<br/>[torch.py]"]
end

subgraph group_ml["AI Libraries"]
  node_train["Distributed training"]
  node_train_storage["Training storage<br/>[storage.py]"]
  node_tune["Hyperparameter tuning"]
  node_trial["Tune trials<br/>[trial.py]"]
  node_rllib["Reinforcement learning"]
  node_rllib_rollouts["RLlib rollouts<br/>[rollout_worker.py]"]
  node_rllib_actor_mgr["RLlib actor manager<br/>[actor_manager.py]"]
end

subgraph group_serve["Model Serving"]
  node_serve["Ray Serve"]
  node_serve_controller["Serve controller"]
  node_serve_router["Request routing<br/>[Router.java]"]
end

subgraph group_observe["Monitoring"]
  node_dashboard["Ray Dashboard"]
  node_task_events[("Task event storage")]
  node_debugger["Distributed debugger"]
end

node_developer(("Application developer"))

node_developer -->|"uses"| node_python_api
node_python_api -.->|"exposes runtime"| node_worker
node_worker -.->|"submits work"| node_task_manager
node_worker -.->|"creates actors"| node_actors
node_task_manager -.->|"schedules tasks"| node_scheduler
node_scheduler -.->|"coordinates objects"| node_objects
node_scheduler -.->|"uses cluster state"| node_gcs
node_developer -->|"uses"| node_data
node_developer -->|"uses"| node_train
node_developer -->|"uses"| node_tune
node_developer -->|"uses"| node_rllib
node_developer -->|"uses"| node_serve
node_developer -->|"monitors with"| node_dashboard
node_developer -->|"debugs with"| node_debugger
node_data -.->|"uses utilities"| node_data_collections
node_data -.->|"supports preprocessing"| node_torch_preprocess
node_train -.->|"persists state"| node_train_storage
node_tune -.->|"manages trials"| node_trial
node_rllib -.->|"collects rollouts"| node_rllib_rollouts
node_rllib -.->|"manages actors"| node_rllib_actor_mgr
node_serve -.->|"controls deployments"| node_serve_controller
node_serve -.->|"routes requests"| node_serve_router
node_dashboard -.->|"stores task events"| node_task_events

click node_python_api "https://github.com/ray-project/ray/blob/master/python/ray/__init__.py"
click node_worker "https://github.com/ray-project/ray/blob/master/python/ray/_private/worker.py"
click node_actors "https://github.com/ray-project/ray/blob/master/python/ray/actor.py"
click node_task_manager "https://github.com/ray-project/ray/blob/master/src/ray/core_worker/task_manager.cc"
click node_scheduler "https://github.com/ray-project/ray/blob/master/src/ray/raylet/node_manager.cc"
click node_objects "https://github.com/ray-project/ray/blob/master/src/ray/object_manager/object_manager.cc"
click node_gcs "https://github.com/ray-project/ray/blob/master/src/ray/gcs/gcs_table_storage.h"
click node_data "https://github.com/ray-project/ray/tree/master/python/ray/data"
click node_data_collections "https://github.com/ray-project/ray/blob/master/python/ray/data/_internal/collections.py"
click node_torch_preprocess "https://github.com/ray-project/ray/blob/master/python/ray/data/preprocessors/torch.py"
click node_train "https://github.com/ray-project/ray/tree/master/python/ray/train"
click node_train_storage "https://github.com/ray-project/ray/blob/master/python/ray/train/_internal/storage.py"
click node_tune "https://github.com/ray-project/ray/tree/master/python/ray/tune"
click node_trial "https://github.com/ray-project/ray/blob/master/python/ray/tune/experiment/trial.py"
click node_rllib "https://github.com/ray-project/ray/tree/master/rllib"
click node_rllib_rollouts "https://github.com/ray-project/ray/blob/master/rllib/evaluation/rollout_worker.py"
click node_rllib_actor_mgr "https://github.com/ray-project/ray/blob/master/rllib/utils/actor_manager.py"
click node_serve "https://github.com/ray-project/ray/tree/master/java/serve/src/main/java/io/ray/serve"
click node_serve_controller "https://github.com/ray-project/ray/blob/master/java/serve/src/main/java/io/ray/serve/controller/ServeController.java"
click node_serve_router "https://github.com/ray-project/ray/blob/master/java/serve/src/main/java/io/ray/serve/router/Router.java"
click node_dashboard "https://github.com/ray-project/ray/tree/master/python/ray/dashboard"
click node_task_events "https://github.com/ray-project/ray/blob/master/python/ray/dashboard/modules/task_events/task_event_storage.py"
click node_debugger "https://github.com/ray-project/ray/tree/master/python/ray/util"

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_python_api,node_worker,node_actors,node_task_manager,node_scheduler,node_objects,node_gcs toneBlue
class node_data,node_data_collections,node_torch_preprocess toneAmber
class node_train,node_train_storage,node_tune,node_trial,node_rllib,node_rllib_rollouts,node_rllib_actor_mgr toneMint
class node_serve,node_serve_controller,node_serve_router toneRose
class node_dashboard,node_task_events,node_debugger,node_developer toneIndigo
```

## Components

### Ray Core

- [Python API](https://github.com/ray-project/ray/blob/master/python/ray/__init__.py): `python/ray/__init__.py`
- [Worker API](https://github.com/ray-project/ray/blob/master/python/ray/_private/worker.py): `python/ray/_private/worker.py`
- [Actors](https://github.com/ray-project/ray/blob/master/python/ray/actor.py): `python/ray/actor.py`
- [Task manager](https://github.com/ray-project/ray/blob/master/src/ray/core_worker/task_manager.cc): `src/ray/core_worker/task_manager.cc`
- [Cluster scheduler](https://github.com/ray-project/ray/blob/master/src/ray/raylet/node_manager.cc): `src/ray/raylet/node_manager.cc`
- [Distributed objects](https://github.com/ray-project/ray/blob/master/src/ray/object_manager/object_manager.cc): `src/ray/object_manager/object_manager.cc`
- [Global control store](https://github.com/ray-project/ray/blob/master/src/ray/gcs/gcs_table_storage.h): `src/ray/gcs/gcs_table_storage.h`

### Data Processing

- [Ray Data](https://github.com/ray-project/ray/tree/master/python/ray/data): `python/ray/data`
- [Data utilities](https://github.com/ray-project/ray/blob/master/python/ray/data/_internal/collections.py): `python/ray/data/_internal/collections.py`
- [Torch preprocessing](https://github.com/ray-project/ray/blob/master/python/ray/data/preprocessors/torch.py): `python/ray/data/preprocessors/torch.py`

### AI Libraries

- [Distributed training](https://github.com/ray-project/ray/tree/master/python/ray/train): `python/ray/train`
- [Training storage](https://github.com/ray-project/ray/blob/master/python/ray/train/_internal/storage.py): `python/ray/train/_internal/storage.py`
- [Hyperparameter tuning](https://github.com/ray-project/ray/tree/master/python/ray/tune): `python/ray/tune`
- [Tune trials](https://github.com/ray-project/ray/blob/master/python/ray/tune/experiment/trial.py): `python/ray/tune/experiment/trial.py`
- [Reinforcement learning](https://github.com/ray-project/ray/tree/master/rllib): `rllib`
- [RLlib rollouts](https://github.com/ray-project/ray/blob/master/rllib/evaluation/rollout_worker.py): `rllib/evaluation/rollout_worker.py`
- [RLlib actor manager](https://github.com/ray-project/ray/blob/master/rllib/utils/actor_manager.py): `rllib/utils/actor_manager.py`

### Model Serving

- [Ray Serve](https://github.com/ray-project/ray/tree/master/java/serve/src/main/java/io/ray/serve): `java/serve/src/main/java/io/ray/serve`
- [Serve controller](https://github.com/ray-project/ray/blob/master/java/serve/src/main/java/io/ray/serve/controller/ServeController.java): `java/serve/src/main/java/io/ray/serve/controller/ServeController.java`
- [Request routing](https://github.com/ray-project/ray/blob/master/java/serve/src/main/java/io/ray/serve/router/Router.java): `java/serve/src/main/java/io/ray/serve/router/Router.java`

### Monitoring

- [Ray Dashboard](https://github.com/ray-project/ray/tree/master/python/ray/dashboard): `python/ray/dashboard`
- [Task event storage](https://github.com/ray-project/ray/blob/master/python/ray/dashboard/modules/task_events/task_event_storage.py): `python/ray/dashboard/modules/task_events/task_event_storage.py`
- [Distributed debugger](https://github.com/ray-project/ray/tree/master/python/ray/util): `python/ray/util`

### Other components

- **Application developer**

## Connections

- Application developer → Python API: uses (evidence: `README.rst`)
- Python API → Worker API: exposes runtime (evidence: `python/ray/__init__.py`)
- Worker API → Task manager: submits work
- Worker API → Actors: creates actors
- Task manager → Cluster scheduler: schedules tasks
- Cluster scheduler → Distributed objects: coordinates objects
- Cluster scheduler → Global control store: uses cluster state
- Application developer → Ray Data: uses (evidence: `README.rst`)
- Application developer → Distributed training: uses (evidence: `README.rst`)
- Application developer → Hyperparameter tuning: uses (evidence: `README.rst`)
- Application developer → Reinforcement learning: uses (evidence: `README.rst`)
- Application developer → Ray Serve: uses (evidence: `README.rst`)
- Application developer → Ray Dashboard: monitors with (evidence: `README.rst`)
- Application developer → Distributed debugger: debugs with (evidence: `README.rst`)
- Ray Data → Data utilities: uses utilities
- Ray Data → Torch preprocessing: supports preprocessing (evidence: `python/ray/data/preprocessors/torch.py`)
- Distributed training → Training storage: persists state (evidence: `python/ray/train/_internal/storage.py`)
- Hyperparameter tuning → Tune trials: manages trials (evidence: `python/ray/tune/experiment/__init__.py`)
- Reinforcement learning → RLlib rollouts: collects rollouts (evidence: `rllib/evaluation/rollout_worker.py`)
- Reinforcement learning → RLlib actor manager: manages actors (evidence: `rllib/utils/actor_manager.py`)
- Ray Serve → Serve controller: controls deployments (evidence: `java/serve/src/main/java/io/ray/serve/api/ServeControllerClient.java`)
- Ray Serve → Request routing: routes requests
- Ray Dashboard → Task event storage: stores task events (evidence: `python/ray/dashboard/modules/task_events/task_event_storage.py`)