# fff-rs/juice architecture

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

- Interactive diagram: https://gitdiagram.com/fff-rs/juice
- Repository: https://github.com/fff-rs/juice

## Overview

##### Project Type and Purpose
- This is a Rust “workspace” monorepo containing multiple crates that together form a modular machine‐learning ecosystem:
- juice: the high‐level ML framework (layers, solvers, network serialization)
- coaster: low‐level tensor and device abstraction (CPU, CUDA, OpenCL)
- coaster-nn: neural‐network operations built on coaster
- coaster-blas: BLAS bindings (via native/OpenCL/CUDA) for linear algebra
- greenglas: data‐preprocessing utilities (image/word transformations)
- juice-examples: CLI and sample applications (MNIST, RNN regression)
- Purpose: Provide end‐to‐end ML tooling for Rust users, from data prep through model definition, optimization, and execution on multiple hardware backends.

##### File Structure Analysis
- Top‐level workspace with Cargo.toml that aggregates subcrates.
- Each crate has standard Rust layout: /src, /tests, /benches, plus README, LICENSE, CI configs.
- “juice” crate contains layer definitions, solvers, Cap’n’Proto schemas, documentation.
- “coaster” crates implement a plugin‐style framework abstraction: dispatcher → framework modules (native, cuda, opencl).
- “greenglas” provides a transformer API around image/word pipelines.
- “juice-examples” contains CLI front end and example projects that depend on “juice” and lower crates.
- Build/deploy scripts: build.rs for codegen, perf scripts, CI configs in .github.

##### Key README Insights
- juice uses Cap’n’Proto for network serialization.
- GPU support via CUDA/cuDNN and OpenCL; native BLAS fallback via pkg-config.
- Examples must be built with appropriate environment variables for external libs.

##### Main Components and Their Relationships
a. Frontend / User Interface
- juice-examples (CLI)
b. High‐Level Framework
- juice crate: layers, solvers, network I/O (Cap’n’Proto)
c. Data Preprocessing
- greenglas crate: image & word transformers
d. Neural‐Network Ops
- coaster-nn crate: NN-specific abstractions (activations, convolutions, RNNs)
e. Linear Algebra / Tensor Abstraction
- coaster-blas crate: BLAS-based ops
- coaster crate: unified tensor, device, plugin interface
f. Hardware Backends (plugins)
- native framework (CPU + BLAS)
- CUDA framework (calls cuBLAS, cuDNN via rcublas/rcudnn crates)
- OpenCL framework (calls OpenCL API)
g. External Services / Libraries
- BLAS/OpenBLAS or system BLAS
- CUDA driver & runtime, cuDNN
- OpenCL ICD & device libs
- Cap’n’Proto runtime

##### Architectural Patterns and Design Principles
- Plugin architecture in “coaster”: a trait‐based dispatcher delegates to one of multiple “frameworks.”
- Layer → Solver separation in “juice”: clear single‐responsibility for network structure vs. optimization.
- Data‐flow pipeline in “greenglas”: chaining transformers.
- Monorepo workspace: crates with explicit inter‐crate dependencies.

- A single canvas with six tiers listed above.
- Directional edges annotated with API or data‐flow descriptors.
- A sidebar listing major config points (env vars for CUDA, BLAS).
- Footnotes calling out build scripts (build.rs, capnp codegen).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Tier 1: User / CLI
    subgraph "1. User / CLI"
        JUICE_EX["juice-examples"]:::crate
        JUICE_UTIL["juice-utils"]:::crate
        MNIST["MNIST Example"]:::crate
        RNN["RNN Regression Example"]:::crate
    end

    %% Tier 2: Application Layer
    subgraph "2. Application Layer"
        JUICE["juice"]:::crate
        JL_LAYERS["layers/"]:::crate
        JL_SOLVERS["solvers/"]:::crate
        JL_CAPNP_SCHEMA["juice.capnp"]:::external
        JL_CAPNP_UTIL["capnp_util.rs"]:::crate
        JL_BUILD["build.rs"]:::crate
        GREEN["greenglas"]:::crate
        GG_CORE["lib.rs"]:::crate
        GG_IMG_MOD["image/mod.rs"]:::crate
        GG_IMG_MODIF["image/modifiers.rs"]:::crate
        GG_WORD_MOD["word/mod.rs"]:::crate
        GG_WORD_MODIF["word/modifiers.rs"]:::crate
        GG_TRANSFORM["transformer.rs"]:::crate
    end

    %% Tier 3: Algorithm Layer
    subgraph "3. Algorithm Layer"
        NN["coaster-nn"]:::crate
        NN_CORE["lib.rs"]:::crate
        NN_PLUGIN["plugin.rs"]:::crate
        NN_FW_NATIVE["frameworks/native/"]:::crate
        NN_FW_CUDA["frameworks/cuda/"]:::crate
        NN_FW_OPENCL["frameworks/opencl.rs"]:::crate
        BLAS["coaster-blas"]:::crate
        BLAS_CORE["lib.rs"]:::crate
        BLAS_PLUGIN["plugin.rs"]:::crate
        BLAS_FW_NATIVE["frameworks/native.rs"]:::crate
        BLAS_FW_CUDA["frameworks/cuda/mod.rs"]:::crate
        BLAS_FW_OPENCL["frameworks/opencl.rs"]:::crate
    end

    %% Tier 4: Core Abstraction
    subgraph "4. Core Abstraction"
        COASTER["coaster"]:::crate
        CST_CORE["lib.rs"]:::crate
        CST_TENSOR["tensor.rs"]:::crate
        CST_PLUGIN["plugin.rs"]:::crate
        CST_FRAMEWORK["framework.rs"]:::crate
        CST_DEVICE["device.rs"]:::crate
    end

    %% Tier 5: Plugin Backends
    subgraph "5. Plugin Backends"
        NATIVE_BE["Native backend"]:::backend
        CUDA_BE["CUDA backend"]:::backend
        OPENCL_BE["OpenCL backend"]:::backend
    end

    %% Tier 6: External Systems
    subgraph "6. External Systems"
        SYS_BLAS[(System BLAS)]:::external
        CUDA_LIB[(CUDA/cuBLAS & cuDNN)]:::external
        OPENCL_LIB[(OpenCL)]:::external
        CAPNP[(Cap’n’Proto)]:::external
    end

    %% Connections
    JUICE_EX -->|"invokes"| JUICE
    JUICE_EX -->|"invokes"| GREEN
    JUICE_UTIL -->|uses| JUICE_EX
    MNIST -->|example for| JUICE_EX
    RNN -->|example for| JUICE_EX

    GREEN -->|"preprocessed data"| JUICE
    JUICE -->|"calls NN ops"| NN
    JUICE -->|"calls BLAS ops"| BLAS
    JUICE -->|"capnp load/save"| CAPNP
    NN -->|"Tensor::read/write"| COASTER
    BLAS -->|"Tensor::read/write"| COASTER
    COASTER -->|"dispatch to"| NATIVE_BE
    COASTER -->|"dispatch to"| CUDA_BE
    COASTER -->|"dispatch to"| OPENCL_BE
    NATIVE_BE -->|"links to"| SYS_BLAS
    CUDA_BE -->|"calls"| CUDA_LIB
    OPENCL_BE -->|"calls"| OPENCL_LIB

    %% Click Events
    click JUICE_EX "https://github.com/fff-rs/juice/tree/master/juice-examples/"
    click JUICE_UTIL "https://github.com/fff-rs/juice/blob/master/juice-examples/juice-utils/src/lib.rs"
    click MNIST "https://github.com/fff-rs/juice/blob/master/juice-examples/mnist-image-multiclass-classification/src/main.rs"
    click RNN "https://github.com/fff-rs/juice/blob/master/juice-examples/mackey-glass-rnn-regression/src/main.rs"
    click JUICE "https://github.com/fff-rs/juice/blob/master/juice/src/lib.rs"
    click JL_LAYERS "https://github.com/fff-rs/juice/tree/master/juice/src/layers/"
    click JL_SOLVERS "https://github.com/fff-rs/juice/tree/master/juice/src/solvers/"
    click JL_CAPNP_SCHEMA "https://github.com/fff-rs/juice/blob/master/juice/capnp/juice.capnp"
    click JL_CAPNP_UTIL "https://github.com/fff-rs/juice/blob/master/juice/src/capnp_util.rs"
    click JL_BUILD "https://github.com/fff-rs/juice/blob/master/juice/build.rs"
    click GG_CORE "https://github.com/fff-rs/juice/blob/master/greenglas/src/lib.rs"
    click GG_IMG_MOD "https://github.com/fff-rs/juice/blob/master/greenglas/src/image/mod.rs"
    click GG_IMG_MODIF "https://github.com/fff-rs/juice/blob/master/greenglas/src/image/modifiers.rs"
    click GG_WORD_MOD "https://github.com/fff-rs/juice/blob/master/greenglas/src/word/mod.rs"
    click GG_WORD_MODIF "https://github.com/fff-rs/juice/blob/master/greenglas/src/word/modifiers.rs"
    click GG_TRANSFORM "https://github.com/fff-rs/juice/blob/master/greenglas/src/transformer.rs"
    click NN_CORE "https://github.com/fff-rs/juice/blob/master/coaster-nn/src/lib.rs"
    click NN_PLUGIN "https://github.com/fff-rs/juice/blob/master/coaster-nn/src/plugin.rs"
    click NN_FW_NATIVE "https://github.com/fff-rs/juice/tree/master/coaster-nn/src/frameworks/native/"
    click NN_FW_CUDA "https://github.com/fff-rs/juice/tree/master/coaster-nn/src/frameworks/cuda/"
    click NN_FW_OPENCL "https://github.com/fff-rs/juice/blob/master/coaster-nn/src/frameworks/opencl.rs"
    click BLAS_CORE "https://github.com/fff-rs/juice/blob/master/coaster-blas/src/lib.rs"
    click BLAS_PLUGIN "https://github.com/fff-rs/juice/blob/master/coaster-blas/src/plugin.rs"
    click BLAS_FW_NATIVE "https://github.com/fff-rs/juice/blob/master/coaster-blas/src/frameworks/native.rs"
    click BLAS_FW_CUDA "https://github.com/fff-rs/juice/blob/master/coaster-blas/src/frameworks/cuda/mod.rs"
    click BLAS_FW_OPENCL "https://github.com/fff-rs/juice/blob/master/coaster-blas/src/frameworks/opencl.rs"
    click CST_CORE "https://github.com/fff-rs/juice/blob/master/coaster/src/lib.rs"
    click CST_TENSOR "https://github.com/fff-rs/juice/blob/master/coaster/src/tensor.rs"
    click CST_PLUGIN "https://github.com/fff-rs/juice/blob/master/coaster/src/plugin.rs"
    click CST_FRAMEWORK "https://github.com/fff-rs/juice/blob/master/coaster/src/framework.rs"
    click CST_DEVICE "https://github.com/fff-rs/juice/blob/master/coaster/src/device.rs"
    click NATIVE_BE "https://github.com/fff-rs/juice/tree/master/coaster/src/frameworks/native/"
    click CUDA_BE "https://github.com/fff-rs/juice/tree/master/coaster/src/frameworks/cuda/"
    click OPENCL_BE "https://github.com/fff-rs/juice/tree/master/coaster/src/frameworks/opencl/"

    %% Styles
    classDef crate fill:#FFD580,stroke:#333,stroke-width:1px
    classDef backend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#d5f5e3,stroke:#333,stroke-width:1px
```
