# buddend/jax architecture

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

- Interactive diagram: https://gitdiagram.com/buddend/jax
- Repository: https://github.com/buddend/jax

## Overview

##### Project type and purpose
- JAX is an open-source, high-performance numerical computing library combining Autograd (automatic differentiation) and XLA (Accelerated Linear Algebra) to run and compile Python+NumPy code on CPU, GPU, and TPU.
- It exposes a Python API for function transformations (`grad`, `jit`, `vmap`, `pmap`) and under the hood traces, lowers to an intermediate representation (jaxpr), hands off to XLA via C++ bindings, and executes optimized kernels on devices.

##### File structure
Top-level directories reveal a layered design:
­  • jax/ – pure-Python frontend: public API (`jax/api.py`), primitives (`jax/core.py`), transformation logic, interpreter modules (ad, batching, xla, parallel), experimental subpackages, NumPy-compat layers, nn/lax extensions.
­  • jaxlib/ – C++ and C bindings: XLA bridge, GPU helpers, PRNG kernels, Lapack, pybind11 integration, device-specific kernels.
­  • build/ & WORKSPACE & Bazel files – build orchestration: shell scripts, Dockerfiles, Bazel BUILD files, wheel‐packaging scripts.
­  • examples/ & cloud_tpu_colabs/ – sample notebooks and scripts demonstrating JAX at work.
­  • docs/ & design_notes/ – user and developer documentation, design rationales, cookbooks.
­  • tests/ & benchmarks/ – automated tests across interpreters and features; performance benchmarks.

##### Extract insights from the README
- Emphasis on composable transformations (grad, jit, vmap, pmap).
- Explanation of how JAX layers Python control flow → transformation/tracing → XLA compilation → device execution.
- Support for multiple backends (CPU, GPU, TPU) via jaxlib.
- Build-from-source instructions showing the separation between Python code and native libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code Layer
    subgraph "User Code Layer"
        direction TB
        UserCode["User Code / Client Scripts / Notebooks"]:::frontend
        CloudTPU["Cloud TPU Colabs (sample notebooks)"]:::frontend
    end

    %% Python Frontend Layer
    subgraph "Python Frontend" 
        direction TB
        PublicAPI["Public API (jax/api.py)"]:::frontend
        NumpyAPI["NumPy-compatible API (jax/numpy/)"]:::frontend
        Experimental["Experimental modules (jax/experimental/)"]:::frontend
        TransformEngine["Transformation Engine (grad, jit, vmap, pmap)"]:::frontend
        subgraph "Interpreters & IR Generator"
            direction TB
            AD["AD (jax/interpreters/ad.py)"]:::frontend
            Batching["Batching (jax/interpreters/batching.py)"]:::frontend
            Parallel["Parallel (jax/interpreters/parallel.py)"]:::frontend
            XLAInterp["XLA lowering (jax/interpreters/xla.py)"]:::frontend
            PartialEval["Partial Eval (jax/interpreters/partial_eval.py)"]:::frontend
        end
    end

    %% Native Backend Layer
    subgraph "Native Backend (jaxlib)"
        direction TB
        XLABridge["XLA Bridge (jax/lib/xla_bridge.py)"]:::native
        NativeBackend["C++/CUDA kernels & helpers (jaxlib/)"]:::native
    end

    %% Build & Packaging Layer
    subgraph "Build & Packaging"
        direction TB
        BuildLayer["Build Scripts & Bazel (build/)"]:::build
        Workspace["Workspace Config (WORKSPACE)"]:::build
    end

    %% Documentation & Tests
    subgraph "Docs & Tests"
        direction TB
        Docs["User & Developer Docs (docs/)"]:::docs
        DesignNotes["Design Notes (design_notes/)"]:::docs
        Tests["Automated Tests (tests/)"]:::test
        Benchmarks["Performance Benchmarks (benchmarks/)"]:::test
    end

    %% Hardware Devices
    subgraph "Hardware Devices"
        direction TB
        CPU["CPU"]:::hardware
        GPU["GPU (CUDA/cuDNN)"]:::hardware
        TPU["TPU"]:::hardware
    end

    %% Connections
    UserCode -->|"calls"| PublicAPI
    CloudTPU -->|"calls"| PublicAPI
    PublicAPI -->|"invokes"| TransformEngine
    TransformEngine -->|"generates jaxpr IR"| AD
    TransformEngine --> AD
    TransformEngine --> Batching
    TransformEngine --> Parallel
    TransformEngine --> XLAInterp
    TransformEngine --> PartialEval
    XLAInterp -->|"produces jaxpr"| XLABridge
    XLABridge -->|"compile via XLA"| NativeBackend
    NativeBackend -->|"executes kernels on"| CPU
    NativeBackend -->|"executes kernels on"| GPU
    NativeBackend -->|"executes kernels on"| TPU
    BuildLayer -.->|"produces wheel"| NativeBackend
    Workspace -.-> BuildLayer

    %% Click Events
    click UserCode "https://github.com/buddend/jax/tree/master/examples/"
    click CloudTPU "https://github.com/buddend/jax/tree/master/cloud_tpu_colabs/"
    click PublicAPI "https://github.com/buddend/jax/blob/master/jax/api.py"
    click NumpyAPI "https://github.com/buddend/jax/tree/master/jax/numpy/"
    click Experimental "https://github.com/buddend/jax/tree/master/jax/experimental/"
    click TransformEngine "https://github.com/buddend/jax/blob/master/jax/api.py"
    click AD "https://github.com/buddend/jax/blob/master/jax/interpreters/ad.py"
    click Batching "https://github.com/buddend/jax/blob/master/jax/interpreters/batching.py"
    click Parallel "https://github.com/buddend/jax/blob/master/jax/interpreters/parallel.py"
    click XLAInterp "https://github.com/buddend/jax/blob/master/jax/interpreters/xla.py"
    click PartialEval "https://github.com/buddend/jax/blob/master/jax/interpreters/partial_eval.py"
    click XLABridge "https://github.com/buddend/jax/blob/master/jax/lib/xla_bridge.py"
    click NativeBackend "https://github.com/buddend/jax/tree/master/jaxlib/"
    click BuildLayer "https://github.com/buddend/jax/tree/master/build/"
    click Workspace "https://github.com/buddend/jax/tree/master/WORKSPACE"
    click Docs "https://github.com/buddend/jax/tree/master/docs/"
    click DesignNotes "https://github.com/buddend/jax/tree/master/design_notes/"
    click Tests "https://github.com/buddend/jax/tree/master/tests/"
    click Benchmarks "https://github.com/buddend/jax/tree/master/benchmarks/"

    %% Styles
    classDef frontend fill:#a2d2ff,stroke:#000,color:#000;
    classDef native fill:#ffd6a5,stroke:#000,color:#000;
    classDef build fill:#cdb4db,stroke:#000,color:#000;
    classDef docs fill:#bde0fe,stroke:#000,color:#000;
    classDef test fill:#ffafcc,stroke:#000,color:#000;
    classDef hardware fill:#caffbf,stroke:#000,color:#000;
```
