# pytorch-labs/monarch architecture

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

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

## Overview

##### Project type and purpose
- From the README and file tree, Monarch is an open-source, multi-language (Python + Rust) distributed execution engine for PyTorch. It exposes a Python API and CLI (in python/monarch and hyper/) while orchestrating a Rust-powered actor system, mesh scheduler, and tensor workers under the hood.

##### File structure
- Top-level languages:
- python/monarch: Python front-end API, bindings, utilities, controller client, scheduler, simulator, telemetry, supervisor
- rust crates (Cargo.toml at root and subcrates): controller, hyper, hyperactor (core actor runtime), hyperactor_mesh (mesh topology), hyperactor_multiprocess (multi-process scheduler), monarch_extension (controller/mesh clients), monarch_hyperactor (higher-level actor abstractions), monarch_messages (wire protocols), monarch_simulator (simulation mode), monarch_tensor_worker (tensor compute workers), telemetry, plus torch-sys and torch-sys-cuda for PyTorch/CUDA interop
- Examples and tests:
- examples/ & python/tests/ show how users drive the system
- Config & build scripts:
- Dockerfile, build-requirements.txt, clippy.toml, rust-toolchain

##### README for additional insights
- Monarch aims to “deliver the high-quality UX of single-GPU PyTorch at cluster scale.”
- Users install via pip and invoke examples or notebooks.
- Under the hood: Python front end → FFI bindings → Rust core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python Layer"
        PYAPI["Python API Layer\n(python/monarch)"]:::python
        FFI["FFI Bindings\n(python/monarch/_rust_bindings)"]:::python
    end

    subgraph "CLI & TUI"
        CLI["CLI & TUI\n(hyper/)"]:::cli
    end

    subgraph "Rust Controller"
        CONT["Controller\n(controller)"]:::controller
    end

    subgraph "Actor Runtime"
        RUNTIME["Actor Runtime\n(hyperactor)"]:::runtime
    end

    subgraph "Mesh Scheduler"
        MESH["Mesh Scheduler\n(hyperactor_mesh)"]:::scheduler
        MULTI["Multi-process Scheduler\n(hyperactor_multiprocess)"]:::scheduler
    end

    subgraph "Extension & Client Libraries"
        EXT["Extension & Clients\n(monarch_extension)"]:::extension
        MSG["Wire Protocols\n(monarch_messages)"]:::extension
    end

    subgraph "Tensor Workers"
        TW["Tensor Workers\n(monarch_tensor_worker)"]:::workers
    end

    subgraph "Simulator"
        SIM["Simulator\n(monarch_simulator)"]:::simulator
    end

    subgraph "Telemetry"
        TELE_R["Telemetry (Rust)\n(hyperactor_telemetry)"]:::telemetry
        TELE_P["Telemetry (Python)\n(python/monarch/telemetry.py)"]:::telemetry
    end

    subgraph "Native Interop"
        NATIVE1["LibTorch Interop\n(torch-sys)"]:::native
        NATIVE2["CUDA/NCCL Interop\n(torch-sys-cuda)"]:::native
    end

    subgraph "External Dependencies"
        EXTD["External\n(NCCL, RDMA, CUDA Driver, Network)"]:::external
    end

    PYAPI -->|"calls via FFI"| FFI
    FFI -->|"invokes"| CONT
    CLI -->|"controls"| CONT
    CONT -->|"spawns actors"| RUNTIME
    RUNTIME -->|"uses mesh"| MESH
    RUNTIME -->|"uses multi-process"| MULTI
    RUNTIME -->|"dispatch ops"| TW
    TW -->|"calls libtorch"| NATIVE1
    TW -->|"calls cuda/nccl"| NATIVE2
    CONT -->|"simulated mode"| SIM
    SIM -->|"simulated runtime"| RUNTIME
    PYAPI -->|"logs spans"| TELE_P
    CONT -->|"exports spans"| TELE_R
    RUNTIME -->|"exports spans"| TELE_R
    TW -->|"exports metrics"| TELE_R
    EXT -->|"clients for"| CONT
    EXT -->|"clients for"| MESH
    MSG -->|"protocols for"| CONT
    NATIVE2 -->|"requires"| EXTD
    NATIVE1 -->|"requires"| EXTD

    click PYAPI "https://github.com/pytorch-labs/monarch/tree/main/python/monarch"
    click FFI "https://github.com/pytorch-labs/monarch/tree/main/python/monarch/_rust_bindings"
    click CLI "https://github.com/pytorch-labs/monarch/tree/main/hyper/"
    click CONT "https://github.com/pytorch-labs/monarch/blob/main/controller/src/bootstrap.rs"
    click RUNTIME "https://github.com/pytorch-labs/monarch/blob/main/hyperactor/src/lib.rs"
    click MESH "https://github.com/pytorch-labs/monarch/blob/main/hyperactor_mesh/src/mesh.rs"
    click MULTI "https://github.com/pytorch-labs/monarch/blob/main/hyperactor_multiprocess/src/scheduler.rs"
    click EXT "https://github.com/pytorch-labs/monarch/blob/main/monarch_extension/src/client.rs"
    click MSG "https://github.com/pytorch-labs/monarch/blob/main/monarch_messages/src/client.rs"
    click TW "https://github.com/pytorch-labs/monarch/blob/main/monarch_tensor_worker/src/bootstrap.rs"
    click SIM "https://github.com/pytorch-labs/monarch/blob/main/monarch_simulator/src/simulator.rs"
    click TELE_R "https://github.com/pytorch-labs/monarch/blob/main/hyperactor_telemetry/src/otel.rs"
    click TELE_P "https://github.com/pytorch-labs/monarch/blob/main/python/monarch/telemetry.py"
    click NATIVE1 "https://github.com/pytorch-labs/monarch/blob/main/torch-sys/src/lib.rs"
    click NATIVE2 "https://github.com/pytorch-labs/monarch/blob/main/torch-sys-cuda/src/cuda.rs"

    classDef python fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef cli fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef controller fill:#E8EAF6,stroke:#283593,color:#283593;
    classDef runtime fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A;
    classDef scheduler fill:#E1F5FE,stroke:#0277BD,color:#0277BD;
    classDef extension fill:#F1F8E9,stroke:#33691E,color:#33691E;
    classDef workers fill:#FFF8E1,stroke:#FF6F00,color:#FF6F00;
    classDef simulator fill:#ECEFF1,stroke:#37474F,color:#37474F;
    classDef telemetry fill:#EDE7F6,stroke:#512DA8,color:#512DA8;
    classDef native fill:#FBE9E7,stroke:#BF360C,color:#BF360C;
    classDef external fill:#CFD8DC,stroke:#455A64,color:#455A64;
```
