# shuqi2077/ruda architecture

> Architecture diagram of the GitHub repository shuqi2077/ruda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shuqi2077/ruda
- Repository: https://github.com/shuqi2077/ruda

## Overview

Ruda is a Rust HPC stack spanning tensor data, compilation, device execution, numerical libraries, distributed collectives, and model/data tooling. Its principal workflow is an application submitting tensor or kernel work to the runtime, which selects a compilation path and dispatches execution to a hardware backend, producing results accessible to the application. The README documents the broader library capabilities and backend paths; sampled source confirms tensor storage, compiler argument handling, CUDA execution, WGPU pipelines/storage, and tuning behavior, but not every subsystem’s internal wiring.

Main entry points: [`ruda/src/runtime/tune/stack/engine.rs`](https://github.com/shuqi2077/ruda/blob/main/ruda/src/runtime/tune/stack/engine.rs) (Runtime Tuning), [`ruda-core/src/tensor/data/storage.rs`](https://github.com/shuqi2077/ruda/blob/main/ruda-core/src/tensor/data/storage.rs) (Tensor Data), [`ruda-compiler/src/mlir/visitor/args_manager.rs`](https://github.com/shuqi2077/ruda/blob/main/ruda-compiler/src/mlir/visitor/args_manager.rs) (Kernel Arguments), [`ruda-compiler/src/cpp/shared/pipeline.rs`](https://github.com/shuqi2077/ruda/blob/main/ruda-compiler/src/cpp/shared/pipeline.rs) (CUDA Pipeline IR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Runtime"]
  node_tensor_data["Tensor Data<br/>[storage.rs]"]
  node_host_storage["Host Storage<br/>[storage.rs]"]
  node_runtime_tune["Runtime Tuning<br/>[engine.rs]"]
end

subgraph group_compile["Compilation"]
  node_compiler_args["Kernel Arguments<br/>[args_manager.rs]"]
  node_cpp_pipeline["CUDA Pipeline IR<br/>[pipeline.rs]"]
end

subgraph group_backends["Execution Backends"]
  node_cuda_execution["CUDA Execution<br/>[server.rs]"]
  node_wgpu_pipeline["WGPU Pipeline<br/>[pipeline.rs]"]
  node_wgpu_storage["WGPU Storage<br/>[storage.rs]"]
end

subgraph group_compute["Compute Libraries"]
  node_rublas["Linear Algebra<br/>[mod.rs]"]
  node_rudnn_attention["Attention<br/>[mod.rs]"]
  node_rudnn_convolution["Convolution<br/>[mod.rs]"]
  node_ruprim["Primitives"]
end

subgraph group_higher["Higher-Level Systems"]
  node_ruccl["Collectives<br/>[api.rs]"]
  node_llm["LLM Inference"]
  node_dataset["Dataset Storage<br/>[storage.rs]"]
end

node_application(("Application"))
node_sqlite[("SQLite")]
node_nvidia_driver["NVIDIA Driver"]
node_wgpu_device["WGPU Device"]

node_application -->|"submits work"| node_runtime_tune
node_application -->|"uses tensors"| node_tensor_data
node_tensor_data -->|"stores data"| node_host_storage
node_runtime_tune -->|"selects kernels"| node_compiler_args
node_compiler_args -->|"builds arguments"| node_cpp_pipeline
node_cpp_pipeline -->|"generates execution"| node_cuda_execution
node_cuda_execution -->|"dispatches to"| node_nvidia_driver
node_runtime_tune -.->|"selects kernels"| node_wgpu_pipeline
node_wgpu_pipeline -->|"creates pipelines"| node_wgpu_device
node_wgpu_storage -->|"allocates buffers"| node_wgpu_device
node_application -->|"requests operations"| node_rublas
node_application -->|"requests attention"| node_rudnn_attention
node_application -->|"requests convolution"| node_rudnn_convolution
node_application -->|"uses primitives"| node_ruprim
node_application -->|"requests collectives"| node_ruccl
node_application -->|"runs inference"| node_llm
node_llm -->|"uses matrix operations"| node_rublas
node_llm -->|"uses attention"| node_rudnn_attention
node_application -->|"reads or writes"| node_dataset
node_dataset -->|"stores records"| node_sqlite

click node_tensor_data "https://github.com/shuqi2077/ruda/blob/main/ruda-core/src/tensor/data/storage.rs"
click node_host_storage "https://github.com/shuqi2077/ruda/blob/main/ruda-core/src/tensor/host/storage.rs"
click node_runtime_tune "https://github.com/shuqi2077/ruda/blob/main/ruda/src/runtime/tune/stack/engine.rs"
click node_compiler_args "https://github.com/shuqi2077/ruda/blob/main/ruda-compiler/src/mlir/visitor/args_manager.rs"
click node_cpp_pipeline "https://github.com/shuqi2077/ruda/blob/main/ruda-compiler/src/cpp/shared/pipeline.rs"
click node_cuda_execution "https://github.com/shuqi2077/ruda/blob/main/ruda-driver-cuda/src/execution/server.rs"
click node_wgpu_pipeline "https://github.com/shuqi2077/ruda/blob/main/ruda-driver-wgpu/src/backend/base/pipeline.rs"
click node_wgpu_storage "https://github.com/shuqi2077/ruda/blob/main/ruda-driver-wgpu/src/memory/storage.rs"
click node_rublas "https://github.com/shuqi2077/ruda/blob/main/ruBLAS/src/tensor_matmul/mod.rs"
click node_rudnn_attention "https://github.com/shuqi2077/ruda/blob/main/ruDNN/src/attention/mod.rs"
click node_rudnn_convolution "https://github.com/shuqi2077/ruda/blob/main/ruDNN/src/convolution/mod.rs"
click node_ruccl "https://github.com/shuqi2077/ruda/blob/main/ruCCL/src/api.rs"
click node_dataset "https://github.com/shuqi2077/ruda/blob/main/ruda-dataset/src/dataset/sqlite/storage.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tensor_data,node_host_storage,node_runtime_tune toneBlue
class node_compiler_args,node_cpp_pipeline,node_sqlite toneAmber
class node_cuda_execution,node_wgpu_pipeline,node_wgpu_storage toneMint
class node_rublas,node_rudnn_attention,node_rudnn_convolution,node_ruprim toneRose
class node_ruccl,node_llm,node_dataset,node_application,node_nvidia_driver,node_wgpu_device toneIndigo
```

## Components

### Core Runtime

- [Tensor Data](https://github.com/shuqi2077/ruda/blob/main/ruda-core/src/tensor/data/storage.rs): `ruda-core/src/tensor/data/storage.rs`
- [Host Storage](https://github.com/shuqi2077/ruda/blob/main/ruda-core/src/tensor/host/storage.rs): `ruda-core/src/tensor/host/storage.rs`
- [Runtime Tuning](https://github.com/shuqi2077/ruda/blob/main/ruda/src/runtime/tune/stack/engine.rs): `ruda/src/runtime/tune/stack/engine.rs`

### Compilation

- [Kernel Arguments](https://github.com/shuqi2077/ruda/blob/main/ruda-compiler/src/mlir/visitor/args_manager.rs): `ruda-compiler/src/mlir/visitor/args_manager.rs`
- [CUDA Pipeline IR](https://github.com/shuqi2077/ruda/blob/main/ruda-compiler/src/cpp/shared/pipeline.rs): `ruda-compiler/src/cpp/shared/pipeline.rs`

### Execution Backends

- [CUDA Execution](https://github.com/shuqi2077/ruda/blob/main/ruda-driver-cuda/src/execution/server.rs): `ruda-driver-cuda/src/execution/server.rs`
- [WGPU Pipeline](https://github.com/shuqi2077/ruda/blob/main/ruda-driver-wgpu/src/backend/base/pipeline.rs): `ruda-driver-wgpu/src/backend/base/pipeline.rs`
- [WGPU Storage](https://github.com/shuqi2077/ruda/blob/main/ruda-driver-wgpu/src/memory/storage.rs): `ruda-driver-wgpu/src/memory/storage.rs`

### Compute Libraries

- [Linear Algebra](https://github.com/shuqi2077/ruda/blob/main/ruBLAS/src/tensor_matmul/mod.rs): `ruBLAS/src/tensor_matmul/mod.rs`
- [Attention](https://github.com/shuqi2077/ruda/blob/main/ruDNN/src/attention/mod.rs): `ruDNN/src/attention/mod.rs`
- [Convolution](https://github.com/shuqi2077/ruda/blob/main/ruDNN/src/convolution/mod.rs): `ruDNN/src/convolution/mod.rs`
- **Primitives**

### Higher-Level Systems

- [Collectives](https://github.com/shuqi2077/ruda/blob/main/ruCCL/src/api.rs): `ruCCL/src/api.rs`
- **LLM Inference**
- [Dataset Storage](https://github.com/shuqi2077/ruda/blob/main/ruda-dataset/src/dataset/sqlite/storage.rs): `ruda-dataset/src/dataset/sqlite/storage.rs`

### Other components

- **Application**
- **SQLite**
- **NVIDIA Driver**
- **WGPU Device**

## Connections

- Application → Runtime Tuning: submits work
- Application → Tensor Data: uses tensors
- Tensor Data → Host Storage: stores data
- Runtime Tuning → Kernel Arguments: selects kernels
- Kernel Arguments → CUDA Pipeline IR: builds arguments
- CUDA Pipeline IR → CUDA Execution: generates execution
- CUDA Execution → NVIDIA Driver: dispatches to
- Runtime Tuning → WGPU Pipeline: selects kernels
- WGPU Pipeline → WGPU Device: creates pipelines
- WGPU Storage → WGPU Device: allocates buffers
- Application → Linear Algebra: requests operations
- Application → Attention: requests attention
- Application → Convolution: requests convolution
- Application → Primitives: uses primitives
- Application → Collectives: requests collectives
- Application → LLM Inference: runs inference
- LLM Inference → Linear Algebra: uses matrix operations
- LLM Inference → Attention: uses attention
- Application → Dataset Storage: reads or writes
- Dataset Storage → SQLite: stores records