# marco-christiani/zigrad architecture

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

- Interactive diagram: https://gitdiagram.com/marco-christiani/zigrad
- Repository: https://github.com/marco-christiani/zigrad

## Overview

##### Project type and purpose
- Zigrad is a high-performance machine learning framework written in Zig.
- It provides an automatic differentiation engine, eager execution with optional graph tracing, and backends for CPU (BLAS) and CUDA.
- It integrates with TensorBoard for visualization and ships example applications (DQN, MNIST, CartPole).

##### File structure
- Top-level “src” folder: core Zig code, subdivided into modules for device abstractions, ndarray/ndtensor, automatic differentiation, graph manager, neural-network layers, and TensorBoard logger.
- “src/cuda”: CUDA kernels and helpers for GPU BLAS, convolutions, neural-network primitives.
- “tensorboard”: Proto definitions + Zig code to emit TensorBoard events.
- “examples”: Standalone demos (hello-world, DQN, MNIST).
- “scripts”: Python/Lua helpers for build or CUDA setup.
- Build/config files: build.zig, zon files, Dockerfile, flake.nix, CI workflows.
- “docs”: Architecture proposals, device design, demos.

a. Main components
- API & Core Engine (Zig):
– ndarray + ndtensor modules
– Autograd engine (backward_context, graph_manager)
– Neural-network modules (nn/layer, loss, optim)
- Device backends:
– CPU (calls BLAS/OpenBLAS or MKL)
– CUDA (src/cuda/*.cu)
- TensorBoard Logger (tensorboard/src)
- Examples & Scripts (entry points, wrappers)
- External Libraries: BLAS, CUDA Toolkit, Python (for examples and scripts)
- Build & Deployment: Zig build, Docker, Nix/Flake, CI

b. Relationships & data flow
1. User code (examples or research scripts) → calls Zigrad API
2. API creates Tensors (ndarray) → records operations in Autograd Context
3. GraphManager optionally traces static graph → emits protobuf events → TensorBoardLogger
4. During forward/backward: operations dispatched to CPU or CUDA backend
5. CPU backend links with external BLAS (MKL/OpenBLAS)
6. CUDA backend launches custom kernels via CUDA Toolkit
7. Optimizer updates parameters in host or device memory

c. Architectural patterns & design principles
- Layered architecture: API → core engine → device abstraction → hardware
- Opt-in graph tracing: supports both eager and graph modes
- Plugin-style backends: separate CPU and GPU implementations
- Event/Logging subsystem decoupled via TensorBoard protobufs

d. Key technologies & frameworks
- Zig language & build system
- BLAS (MKL/OpenBLAS)
- NVIDIA CUDA (kernels in .cu)
- Protocol Buffers for TensorBoard events
- CI/CD: GitHub Actions, Docker, Nix flakes

##### Detail
- CUDA sub-directory as a composite component with kernels (BLAS, nn primitives).
- Proto folder under TensorBoard as part of event serialization.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Examples & Scripts
    subgraph "Examples & Scripts"
        DQN["DQN Demo"]:::doc
        MNIST["MNIST Demo"]:::doc
        Hello["Hello World"]:::doc
        Scripts["Helper Scripts"]:::doc
    end

    %% API & Core Engine
    subgraph "API & Core Engine"
        NDArray["ndarray.zig"]:::blue
        NDTensor["ndtensor.zig"]:::blue
        Layer["nn layer.zig"]:::blue
        Loss["nn loss.zig"]:::blue
        Optim["nn optim.zig"]:::blue
        MLP["nn mlp.zig"]:::blue
        Trainer["nn trainer.zig"]:::blue
        Utils["nn utils.zig"]:::blue
        WInit["nn winit.zig"]:::blue
    end

    %% Autograd Engine
    subgraph "Autograd Engine"
        BackCtx["backward_context.zig"]:::blue
        GraphMgr["graph_manager.zig"]:::blue
    end

    %% Device Backends
    subgraph "Device Backends"
        subgraph "CPU Backend"
            DevCommon["device_common.zig"]:::green
            HostDev["host_device.zig"]:::green
            DevRef["device_reference.zig"]:::green
            Alloc["caching_allocator.zig"]:::green
            OpSpec["opspec.zig"]:::green
            Reduce["reduce.zig"]:::green
            DimMap["dimension_map.zig"]:::green
        end
        subgraph "CUDA Backend"
            CUDARoot["root.zig"]:::green
            CudaFiles["CUDA Kernels"]:::green
        end
    end

    %% TensorBoard Logger
    subgraph "TensorBoard Logger"
        TBLogger["TensorboardLogger.zig"]:::yellow
        CRC["crc.zig"]:::yellow
        TBRoot["root.zig"]:::yellow
        Proto[".proto definitions"]:::cylinder
    end

    %% External Dependencies
    BLAS["BLAS/OpenBLAS MKL"]:::cylinder
    CUDAKit["CUDA Toolkit"]:::cylinder

    %% Build & Deployment
    subgraph "Build & Deployment"
        BuildZig["build.zig"]:::orange
        BuildZon["build.zig.zon"]:::orange
        Docker["Dockerfile"]:::orange
        Nix["flake.nix"]:::orange
        Lock["flake.lock"]:::orange
        CI["CI Workflows"]:::orange
    end

    %% Connections
    DQN --> NDArray
    MNIST --> NDArray
    Hello --> NDArray
    Scripts -.-> BuildZig

    NDArray --> BackCtx
    NDTensor --> BackCtx
    NDArray --> GraphMgr
    NDTensor --> GraphMgr

    BackCtx --> DevCommon
    BackCtx --> CUDARoot
    GraphMgr --> DevCommon
    GraphMgr --> CUDARoot
    GraphMgr --> TBLogger

    DevCommon --> BLAS
    HostDev --> BLAS
    DevRef --> BLAS
    Alloc --> BLAS
    OpSpec --> BLAS
    Reduce --> BLAS
    DimMap --> BLAS

    CUDARoot --> CUDAKit
    CudaFiles --> CUDAKit

    TBLogger --> Proto
    TBLogger --> CRC
    TBLogger --> TBRoot

    BuildZig --> BuildZon
    BuildZig --> Docker
    BuildZig --> Nix
    BuildZig --> CI
    Nix --> Lock

    %% Click Events
    click DQN "https://github.com/marco-christiani/zigrad/tree/main/examples/dqn/"
    click MNIST "https://github.com/marco-christiani/zigrad/tree/main/examples/mnist/"
    click Hello "https://github.com/marco-christiani/zigrad/tree/main/examples/hello-world/"
    click Scripts "https://github.com/marco-christiani/zigrad/tree/main/scripts/"

    click NDArray "https://github.com/marco-christiani/zigrad/blob/main/src/ndarray.zig"
    click NDTensor "https://github.com/marco-christiani/zigrad/blob/main/src/ndtensor.zig"
    click Layer "https://github.com/marco-christiani/zigrad/blob/main/src/nn/layer.zig"
    click Loss "https://github.com/marco-christiani/zigrad/blob/main/src/nn/loss.zig"
    click Optim "https://github.com/marco-christiani/zigrad/blob/main/src/nn/optim.zig"
    click MLP "https://github.com/marco-christiani/zigrad/blob/main/src/nn/mlp.zig"
    click Trainer "https://github.com/marco-christiani/zigrad/blob/main/src/nn/trainer.zig"
    click Utils "https://github.com/marco-christiani/zigrad/blob/main/src/nn/utils.zig"
    click WInit "https://github.com/marco-christiani/zigrad/blob/main/src/nn/winit.zig"
    click BackCtx "https://github.com/marco-christiani/zigrad/blob/main/src/backward_context.zig"
    click GraphMgr "https://github.com/marco-christiani/zigrad/blob/main/src/graph_manager.zig"

    click DevCommon "https://github.com/marco-christiani/zigrad/blob/main/src/device/device_common.zig"
    click HostDev "https://github.com/marco-christiani/zigrad/blob/main/src/device/host_device.zig"
    click DevRef "https://github.com/marco-christiani/zigrad/blob/main/src/device/device_reference.zig"
    click Alloc "https://github.com/marco-christiani/zigrad/blob/main/src/device/caching_allocator.zig"
    click OpSpec "https://github.com/marco-christiani/zigrad/blob/main/src/device/opspec.zig"
    click Reduce "https://github.com/marco-christiani/zigrad/blob/main/src/device/reduce.zig"
    click DimMap "https://github.com/marco-christiani/zigrad/blob/main/src/device/dimension_map.zig"

    click CUDARoot "https://github.com/marco-christiani/zigrad/blob/main/src/cuda/root.zig"
    click CudaFiles "https://github.com/marco-christiani/zigrad/tree/main/src/cuda/"

    click TBLogger "https://github.com/marco-christiani/zigrad/blob/main/tensorboard/src/TensorboardLogger.zig"
    click CRC "https://github.com/marco-christiani/zigrad/blob/main/tensorboard/src/crc.zig"
    click TBRoot "https://github.com/marco-christiani/zigrad/blob/main/tensorboard/src/root.zig"
    click Proto "https://github.com/marco-christiani/zigrad/tree/main/tensorboard/proto/"

    click BuildZig "https://github.com/marco-christiani/zigrad/blob/main/build.zig"
    click BuildZon "https://github.com/marco-christiani/zigrad/blob/main/build.zig.zon"
    click Docker "https://github.com/marco-christiani/zigrad/tree/main/Dockerfile"
    click Nix "https://github.com/marco-christiani/zigrad/blob/main/flake.nix"
    click Lock "https://github.com/marco-christiani/zigrad/blob/main/flake.lock"
    click CI "https://github.com/marco-christiani/zigrad/tree/main/.github/workflows/"

    %% Styles
    classDef blue fill:#D0E6FF,stroke:#02488D,stroke-width:1px
    classDef green fill:#D0FFD6,stroke:#02712E,stroke-width:1px
    classDef yellow fill:#FFF9C4,stroke:#A18800,stroke-width:1px
    classDef orange fill:#FFE0B2,stroke:#E65100,stroke-width:1px
    classDef doc fill:#E3F2FD,stroke:#64B5F6,stroke-width:1px,stroke-dasharray: 5 5
    classDef cylinder shape:cylinder,fill:#FFF9C4,stroke:#A18800,stroke-width:1px
```
