# pytorch/torchx architecture

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

- Interactive diagram: https://gitdiagram.com/pytorch/torchx
- Repository: https://github.com/pytorch/torchx

## Overview

##### Project Type and Purpose
- TorchX is an open‐source SDK and CLI tool (a universal job launcher) for PyTorch workloads.
- It provides a high-level “Runner + Scheduler + Runtime” abstraction, letting users define ML jobs once and run them on Kubernetes, Slurm, AWS Batch, Docker, GCP Batch, or locally.
- Key use cases: fast iteration during research, end-to-end production ML pipelines.

##### File Structure (High-Level Layers)
- CLI Layer (torchx/cli): Handles user commands, parses arguments, invokes the Runner API.
- SDK / Core API (torchx/runner, torchx/specs, torchx/apps, torchx/components): Defines JobSpecs, component abstractions, and the Runner interface.
- Scheduling Layer (torchx/schedulers): A plugin model where each scheduler (AWS Batch, Kubernetes, Slurm, Docker, etc.) implements an API for launching jobs.
- Runtime Layer (torchx/runtime): Contains container build logic and tracking instrumentation.
- Workspace Layer (torchx/workspace): Manages code packaging/upload (e.g., Docker images, directory staging).
- Tracking Layer (torchx/tracker): Pluggable backends (e.g., MLflow, fsspec) for capturing metrics, logs, artifacts.
- Utility Modules (torchx/util): Shared helper functions (session, I/O, logging).
- Examples & Tests: Illustrate usage and verify correctness.

##### README for Insights
- Describes TorchX as a “universal job launcher.”
- Mentions supported schedulers, quickstart link, and dependencies.

##### Main Components and Their Interactions
a. Actors and Components
– User (CLI or Python SDK)
– CLI Frontend (torchx/cli)
– Runner API (torchx/runner + torchx/specs)
– Component Library (torchx/components + torchx/apps + torchx/pipelines)
– Scheduler Plugins (torchx/schedulers/*)
– Workspace (torchx/workspace)
– Runtime Container Builder (torchx/runtime)
– Tracking Backend (torchx/tracker)
– External Systems: Kubernetes cluster, Slurm cluster, AWS Batch, Docker daemon/registry, GCP Batch, Local OS
b. Data & Control Flows
1. User invokes `torchx run …` (CLI) or calls Runner.run(...) (Python).
2. CLI → Runner: parse args into a JobSpec.
3. Runner → Scheduler: select appropriate scheduler plugin based on `--scheduler` flag.
4. Scheduler → Workspace: stage code/artifacts (e.g., build Docker image or prepare directory).
5. Scheduler → Runtime: build container if needed, inject tracking hooks.
6. Scheduler → External System: submit job (K8s Job, Slurm sbatch, AWS Batch job, Docker container run).
7. External System → Tracker: emit status/events/metrics back to TorchX tracking layer.
8. CLI/SDK polls Tracker or watches logs for updates.
c. Architectural Patterns & Principles
– Plugin Architecture: schedulers and trackers are swappable modules following a common API.
– Separation of Concerns: CLI vs. Runner vs. Scheduler vs. Workspace vs. Runtime vs. Tracker.
– Declarative Specs: users define JobSpecs that the runner/scheduler materializes.
– Extensibility: new schedulers, new trackers, new components.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        U["User"]:::actor
    end

    %% CLI / SDK Layer
    subgraph "CLI / SDK Layer"
        CLI["CLI Layer"]:::internal
        SDK["Python SDK"]:::internal
    end

    %% Core / Spec Layer
    subgraph "Core / Spec Layer"
        Runner["Runner API"]:::internal
        Specs["Specs API"]:::internal
        subgraph "Component Library"
            Comp["torchx/components"]:::internal
            Apps["torchx/apps"]:::internal
            Pipes["torchx/pipelines"]:::internal
        end
        Util["Utility Modules"]:::internal
    end

    %% Plugin Layer
    subgraph "Plugin Layer"
        Schedulers["Scheduler Plugins"]:::plugin
        subgraph "Tracking Layer"
            TrackerAPI["Tracking API"]:::plugin
            TrackerBE["Tracker Backends"]:::plugin
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Workspace["Workspace"]:::internal
        Runtime["Runtime Container Builder"]:::internal
        subgraph "External Systems"
            K8s["Kubernetes"]:::external
            Slurm["Slurm"]:::external
            AWS["AWS Batch"]:::external
            Docker["Docker"]:::external
            GCP["GCP Batch"]:::external
            Local["Local OS"]:::external
        end
    end

    %% Connections
    U -->|"torchx run or Runner.run"| CLI
    U -->|"Runner.run()"| SDK
    CLI -->|"parse args into JobSpec"| Runner
    SDK -->|"direct API call"| Runner
    Runner -->|"uses"| Specs
    Runner -->|"loads components"| Comp
    Runner -->|"loads apps"| Apps
    Runner -->|"loads pipelines"| Pipes
    Runner -->|"calls util helpers"| Util
    Runner -->|"selects plugin"| Schedulers
    Schedulers -->|"stage code"| Workspace
    Schedulers -->|"build container"| Runtime
    Runtime -->|"returns image"| Schedulers
    Schedulers -->|"submit job"| K8s
    Schedulers -->|"submit job"| Slurm
    Schedulers -->|"submit job"| AWS
    Schedulers -->|"submit job"| Docker
    Schedulers -->|"submit job"| GCP
    Schedulers -->|"submit job"| Local
    ExternalSystems((External Systems)) -.->|"emit events/metrics"| TrackerAPI
    TrackerAPI -->|"uses backends"| TrackerBE
    TrackerAPI -->|"provides status"| CLI

    %% Click Events
    click CLI "https://github.com/pytorch/torchx/tree/main/torchx/cli"
    click Runner "https://github.com/pytorch/torchx/blob/main/torchx/runner/api.py"
    click Specs "https://github.com/pytorch/torchx/blob/main/torchx/specs/api.py"
    click Comp "https://github.com/pytorch/torchx/tree/main/torchx/components"
    click Apps "https://github.com/pytorch/torchx/tree/main/torchx/apps"
    click Pipes "https://github.com/pytorch/torchx/tree/main/torchx/pipelines"
    click Schedulers "https://github.com/pytorch/torchx/tree/main/torchx/schedulers"
    click Workspace "https://github.com/pytorch/torchx/tree/main/torchx/workspace"
    click Runtime "https://github.com/pytorch/torchx/tree/main/torchx/runtime/container"
    click TrackerAPI "https://github.com/pytorch/torchx/blob/main/torchx/tracker/api.py"
    click TrackerBE "https://github.com/pytorch/torchx/tree/main/torchx/tracker/backend"
    click Util "https://github.com/pytorch/torchx/tree/main/torchx/util"

    %% Styles
    classDef internal fill:#bfdbfe,stroke:#1e40af,color:#1e3a8a
    classDef plugin fill:#a7f3d0,stroke:#047857,color:#065f46
    classDef external fill:#e5e7eb,stroke:#374151,color:#1f2937
    classDef actor fill:#fde047,stroke:#92400e,color:#78350f
```
