# jax-ml/jax architecture

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

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

## Overview

##### Project type and purpose
- JAX is an open-source Python library for high-performance numerical computing.
- It provides composable transformations (grad, jit, vmap) on NumPy-style array code and compiles to XLA for execution on CPU, GPU, and TPU.

##### Top-level components (from file tree & README)
- Python-level interface (“jax” package)
– jax/api.py, jax/_src/api.py for user-facing functions (grad, jit, vmap)
– jax.numpy, jax.scipy, jax.lax, jax.experimental subpackages
- Core transformation engine
– interpreters (ad.py, batching.py, mlir.py, pxla.py under jax/_src/interpreters)
– jaxpr IR representation and passes (jax/core.py, jax/_src/jaxpr_util.py)
- XLA integration
– translation to XLA HLO (mlir bridge under jax/_src/compilation_cache, compiler.py, custom_partitioning)
- Runtime support (jaxlib C++ extensions)
– jaxlib/python entry points (py_array.cc, py_client.cc)
– device-specific kernels in jaxlib/cpu, jaxlib/gpu, jaxlib/rocm, jaxlib/triton
- Hardware backends
– CPU via Eigen/LAPACK
– NVIDIA GPU via CUDA/cuBLAS/cuDNN
– Google TPU via XLA TPU runtime
– AMD GPU via ROCm plugin
– Apple/Intel GPUs via community plugins
- Build & packaging
– Bazel and pyproject.toml / setup.py for source builds
– build_wheel.py, build/rocm Dockerfiles, jax_plugins for cuda/rocm
– CI/CD workflows (.github/workflows, ci/, build/rocm/)
- Examples, benchmarks, tutorials, docs, tests
– examples/ and benchmarks/ for usage patterns
– docs/, cloud_tpu_colabs/ for guidance
– tests/ and benchmarks/ for quality & performance

##### Relationships & data flow
3. Transformation engine converts functions to jaxpr IR, applies autodiff and vectorization passes
4. Transformed IR is lowered to XLA HLO via the MLIR bridge
5. XLA HLO is compiled just-in-time into device-specific machine code
6. jaxlib runtime loads and executes compiled binaries on target hardware (CPU/GPU/TPU)
7. Results are returned to Python and wrapped as DeviceArray objects

##### Architectural patterns & principles
- Layered architecture:
- Python frontend → transformation core → compiler → runtime → hardware
- Pluggable backends:
- Abstract dispatch in jax/_src/dispatch.py → concrete plugin in jaxlib
- Separation of concerns:
- Pure Python transformations and IR manipulation
- Low-level kernels and memory management in C++
- Build isolation:
- Bazel for C++ and Python integration
- Docker/rocm/CI scripts for multi-platform support

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User layer
    UserCode["User Code"]:::python
    subgraph "Python API Layer"
        direction TB
        JAX_API["jax/api.py"]:::python
        SRC_API["jax/_src/api.py"]:::python
        API_UTIL["jax/_src/api_util.py"]:::python
        NUMPY["jax/_src/numpy/"]:::python
        SCIPY["jax/_src/scipy/"]:::python
        LAX["jax/_src/lax/"]:::python
    end

    %% Transformation engine
    subgraph "Transformation Engine" 
        direction TB
        Interpreters["Interpreters\n(ad.py, batching.py,\nmlir.py, pxla.py)"]:::ir
        JAXPR_CORE["jax/_src/core.py"]:::ir
        JAXPR_UTIL["jax/_src/jaxpr_util.py"]:::ir
    end

    %% MLIR/XLA Bridge
    subgraph "MLIR / XLA Bridge & Compilation"
        direction TB
        CACHE["jax/_src/compilation_cache.py"]:::ir
        CACHE_IF["jax/_src/compilation_cache_interface.py"]:::ir
        COMPILER["jax/_src/compiler.py"]:::ir
        MLIR_LIB["jax/_src/lib/mlir/"]:::ir
        XLA["third_party/xla/"]:::ir
    end

    %% Runtime
    subgraph "jaxlib Runtime Support (C++)"
        direction TB
        PY_ARRAY["jaxlib/py_array.cc"]:::cpp
        PY_CLIENT["jaxlib/py_client.cc"]:::cpp
        PY_EXEC["jaxlib/py_executable.cc"]:::cpp
        PY_DEVICE["jaxlib/py_device.cc"]:::cpp
        PY_VALUES["jaxlib/py_values.cc"]:::cpp
    end

    %% Hardware backends
    subgraph "Hardware Backends"
        direction TB
        CPU["jaxlib/cpu/"]:::hardware
        GPU["jaxlib/gpu/"]:::hardware
        ROCM["jaxlib/rocm/"]:::hardware
        TRITON["jaxlib/triton/"]:::hardware
    end

    %% Plugins
    subgraph "Plugin Mechanism"
        direction TB
        CUDA_PLUGIN["jax_plugins/cuda/"]:::hardware
        ROCM_PLUGIN["jax_plugins/rocm/"]:::hardware
    end

    %% Build & CI
    subgraph "Build & Packaging / CI"
        direction TB
        BAZEL["BUILD.bazel & Bazel files"]:::build
        PKG["pyproject.toml & setup.py"]:::build
        DOCKER["build/rocm/"]:::build
        CICD[".github/workflows/ & ci/"]:::build
    end

    %% Examples / Docs / Tests
    Examples["examples/"]:::aux
    Benchmarks["benchmarks/"]:::aux
    Docs["docs/"]:::aux
    Tutorials["docs/_tutorials/"]:::aux
    Colabs["cloud_tpu_colabs/"]:::aux
    Tests["tests/"]:::aux
    FileCheck["tests/filecheck/"]:::aux

    %% Connections
    UserCode -->|"imports jax"| JAX_API
    JAX_API -->|"calls"| SRC_API
    SRC_API --> API_UTIL
    SRC_API --> NUMPY
    SRC_API --> SCIPY
    SRC_API --> LAX

    SRC_API -->|"invokes"| Interpreters
    Interpreters --> JAXPR_CORE
    JAXPR_CORE --> JAXPR_UTIL

    JAXPR_UTIL --> COMPILER
    Interpreters --> COMPILER
    COMPILER --> CACHE
    COMPILER --> CACHE_IF
    COMPILER --> MLIR_LIB
    MLIR_LIB --> XLA

    COMPILER -->|"generates HLO"| PY_EXEC
    PY_EXEC --> PY_ARRAY
    PY_EXEC --> PY_CLIENT
    PY_EXEC --> PY_DEVICE
    PY_EXEC --> PY_VALUES

    PY_VALUES --> CPU
    PY_VALUES --> GPU
    PY_VALUES --> ROCM
    PY_VALUES --> TRITON

    CPU -->|"kernel dispatch"| CPU
    GPU -->|"kernel dispatch"| GPU
    ROCM -->|"kernel dispatch"| ROCM
    TRITON -->|"kernel dispatch"| TRITON

    SRC_API --> CUDA_PLUGIN
    SRC_API --> ROCM_PLUGIN

    BAZEL --> PKG
    BAZEL --> DOCKER
    BAZEL --> CICD

    UserCode --> Examples
    UserCode --> Benchmarks
    Examples --> Docs
    Docs --> Tutorials
    Docs --> Colabs
    Tests --> FileCheck

    %% Click events
    click JAX_API "https://github.com/jax-ml/jax/blob/main/jax/api.py"
    click SRC_API "https://github.com/jax-ml/jax/blob/main/jax/_src/api.py"
    click API_UTIL "https://github.com/jax-ml/jax/blob/main/jax/_src/api_util.py"
    click NUMPY "https://github.com/jax-ml/jax/tree/main/jax/_src/numpy/"
    click SCIPY "https://github.com/jax-ml/jax/tree/main/jax/_src/scipy/"
    click LAX "https://github.com/jax-ml/jax/tree/main/jax/_src/lax/"
    click Interpreters "https://github.com/jax-ml/jax/blob/main/jax/_src/interpreters/ad.py"
    click JAXPR_CORE "https://github.com/jax-ml/jax/blob/main/jax/_src/core.py"
    click JAXPR_UTIL "https://github.com/jax-ml/jax/blob/main/jax/_src/jaxpr_util.py"
    click CACHE "https://github.com/jax-ml/jax/blob/main/jax/_src/compilation_cache.py"
    click CACHE_IF "https://github.com/jax-ml/jax/blob/main/jax/_src/compilation_cache_interface.py"
    click COMPILER "https://github.com/jax-ml/jax/blob/main/jax/_src/compiler.py"
    click MLIR_LIB "https://github.com/jax-ml/jax/tree/main/jax/_src/lib/mlir/"
    click XLA "https://github.com/jax-ml/jax/tree/main/third_party/xla/"
    click PY_ARRAY "https://github.com/jax-ml/jax/blob/main/jaxlib/py_array.cc"
    click PY_CLIENT "https://github.com/jax-ml/jax/blob/main/jaxlib/py_client.cc"
    click PY_EXEC "https://github.com/jax-ml/jax/blob/main/jaxlib/py_executable.cc"
    click PY_DEVICE "https://github.com/jax-ml/jax/blob/main/jaxlib/py_device.cc"
    click PY_VALUES "https://github.com/jax-ml/jax/blob/main/jaxlib/py_values.cc"
    click CPU "https://github.com/jax-ml/jax/tree/main/jaxlib/cpu/"
    click GPU "https://github.com/jax-ml/jax/tree/main/jaxlib/gpu/"
    click ROCM "https://github.com/jax-ml/jax/tree/main/jaxlib/rocm/"
    click TRITON "https://github.com/jax-ml/jax/tree/main/jaxlib/triton/"
    click CUDA_PLUGIN "https://github.com/jax-ml/jax/tree/main/jax_plugins/cuda/"
    click ROCM_PLUGIN "https://github.com/jax-ml/jax/tree/main/jax_plugins/rocm/"
    click BAZEL "https://github.com/jax-ml/jax/blob/main/BUILD.bazel"
    click PKG "https://github.com/jax-ml/jax/blob/main/pyproject.toml"
    click DOCKER "https://github.com/jax-ml/jax/tree/main/build/rocm/"
    click CICD "https://github.com/jax-ml/jax/tree/main/.github/workflows/"

    %% Styles
    classDef python fill:#E0F7FA,stroke:#006064,color:#006064
    classDef ir fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef cpp fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef hardware fill:#ECEFF1,stroke:#455A64,color:#455A64
    classDef build fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef aux fill:#FAFAFA,stroke:#9E9E9E,color:#9E9E9E
```
