# canreader/fastnn architecture

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

- Interactive diagram: https://gitdiagram.com/canreader/fastnn
- Repository: https://github.com/canreader/fastnn

## Overview

FastNN is a Rust deep-learning library. Its principal workflow loads and batches data, runs a neural-network model through tensor operations to produce a loss, backpropagates gradients into shared parameter slots, then updates those parameters with an optimizer. Separate branches cover transformer generation, CUDA execution, data sources, schedules, and checkpoint interchange. Relationships among the main training stages are documented in the README; implementation-level links are included only where the supplied excerpts or source index support them.

Main entry points: [`src/tensor/ops`](https://github.com/canreader/fastnn/tree/master/src/tensor/ops) (Tensor operations), [`src/data/loader.rs`](https://github.com/canreader/fastnn/blob/master/src/data/loader.rs) (DataLoader), [`src/nn`](https://github.com/canreader/fastnn/tree/master/src/nn) (Neural layers), [`src/nn/loss.rs`](https://github.com/canreader/fastnn/blob/master/src/nn/loss.rs) (Loss functions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data input"]
  node_mnist["MNIST dataset<br/>[mnist.rs]"]
  node_dataset["Dataset interface<br/>[dataset.rs]"]
  node_loader["DataLoader<br/>[loader.rs]"]
end

subgraph group_model["Model and tensors"]
  node_layers["Neural layers"]
  node_transformers["Transformers and generation"]
  node_loss["Loss functions<br/>[loss.rs]"]
  node_tensor["Tensor operations"]
end

subgraph group_training["Training"]
  node_autograd["Reverse-mode autograd<br/>[engine.rs]"]
  node_rules["Backward rules"]
  node_params["Parameter slots<br/>[param.rs]"]
  node_optimizers["Optimizers"]
  node_schedules["Learning-rate schedules<br/>[schedule.rs]"]
end

subgraph group_compute["Compute backend"]
  node_storage["Tensor storage<br/>[storage.rs]"]
  node_cuda["CUDA kernels and bindings<br/>[kernels.rs]"]
  node_cudaffi["CUDA FFI<br/>[ffi.rs]"]
end

subgraph group_persistence["Persistence"]
  node_checkpoints["Native checkpoints<br/>[checkpoint.rs]"]
  node_trainingstate["Training-state checkpoints<br/>[training.rs]"]
  node_safetensors["Safetensors interchange<br/>[safetensors.rs]"]
  node_checkpointfiles["Checkpoint files"]
end

node_engineer(("Training caller"))
node_gpu(("CUDA device"))

node_engineer -->|"loads data"| node_mnist
node_mnist -->|"implements"| node_dataset
node_engineer -->|"batches data"| node_loader
node_loader -->|"reads samples"| node_dataset
node_loader -->|"places batches"| node_tensor
node_engineer -->|"runs model"| node_layers
node_layers -->|"computes with"| node_tensor
node_engineer -->|"computes loss"| node_loss
node_loss -->|"uses operations"| node_tensor
node_layers -->|"holds handles"| node_params
node_loss -->|"starts backward"| node_autograd
node_autograd -->|"applies rules"| node_rules
node_autograd -->|"accumulates gradients"| node_params
node_engineer -->|"updates parameters"| node_optimizers
node_optimizers -->|"reads and updates"| node_params
node_schedules -.->|"sets learning rate"| node_optimizers
node_engineer -->|"builds or generates"| node_transformers
node_tensor -->|"uses storage"| node_storage
node_storage -->|"allocates GPU buffers"| node_cuda
node_tensor -->|"dispatches GPU ops"| node_cuda
node_cuda -->|"calls bindings"| node_cudaffi
node_cudaffi -.->|"launches kernels"| node_gpu
node_engineer -->|"saves or loads"| node_checkpoints
node_engineer -->|"resumes training"| node_trainingstate
node_engineer -->|"imports or exports"| node_safetensors
node_checkpoints -.->|"reads and writes"| node_checkpointfiles
node_trainingstate -.->|"reads and writes"| node_checkpointfiles
node_safetensors -.->|"reads and writes"| node_checkpointfiles

click node_mnist "https://github.com/canreader/fastnn/blob/master/src/data/mnist.rs"
click node_dataset "https://github.com/canreader/fastnn/blob/master/src/data/dataset.rs"
click node_loader "https://github.com/canreader/fastnn/blob/master/src/data/loader.rs"
click node_layers "https://github.com/canreader/fastnn/tree/master/src/nn"
click node_transformers "https://github.com/canreader/fastnn/tree/master/src/nn"
click node_loss "https://github.com/canreader/fastnn/blob/master/src/nn/loss.rs"
click node_tensor "https://github.com/canreader/fastnn/tree/master/src/tensor/ops"
click node_storage "https://github.com/canreader/fastnn/blob/master/src/tensor/storage.rs"
click node_autograd "https://github.com/canreader/fastnn/blob/master/src/autograd/engine.rs"
click node_rules "https://github.com/canreader/fastnn/tree/master/src/autograd/ops"
click node_params "https://github.com/canreader/fastnn/blob/master/src/nn/param.rs"
click node_optimizers "https://github.com/canreader/fastnn/tree/master/src/optim"
click node_schedules "https://github.com/canreader/fastnn/blob/master/src/optim/schedule.rs"
click node_cuda "https://github.com/canreader/fastnn/blob/master/src/cuda/kernels.rs"
click node_cudaffi "https://github.com/canreader/fastnn/blob/master/src/cuda/ffi.rs"
click node_checkpoints "https://github.com/canreader/fastnn/blob/master/src/serialize/checkpoint.rs"
click node_trainingstate "https://github.com/canreader/fastnn/blob/master/src/serialize/training.rs"
click node_safetensors "https://github.com/canreader/fastnn/blob/master/src/serialize/safetensors.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_mnist,node_dataset,node_loader toneBlue
class node_layers,node_transformers,node_loss,node_tensor toneAmber
class node_autograd,node_rules,node_params,node_optimizers,node_schedules toneMint
class node_storage,node_cuda,node_cudaffi toneRose
class node_checkpoints,node_trainingstate,node_safetensors,node_checkpointfiles,node_engineer,node_gpu toneIndigo
```

## Components

### Data input

- [MNIST dataset](https://github.com/canreader/fastnn/blob/master/src/data/mnist.rs): `src/data/mnist.rs`
- [Dataset interface](https://github.com/canreader/fastnn/blob/master/src/data/dataset.rs): `src/data/dataset.rs`
- [DataLoader](https://github.com/canreader/fastnn/blob/master/src/data/loader.rs): `src/data/loader.rs`

### Model and tensors

- [Neural layers](https://github.com/canreader/fastnn/tree/master/src/nn): `src/nn`
- [Transformers and generation](https://github.com/canreader/fastnn/tree/master/src/nn): `src/nn`
- [Loss functions](https://github.com/canreader/fastnn/blob/master/src/nn/loss.rs): `src/nn/loss.rs`
- [Tensor operations](https://github.com/canreader/fastnn/tree/master/src/tensor/ops): `src/tensor/ops`

### Training

- [Reverse-mode autograd](https://github.com/canreader/fastnn/blob/master/src/autograd/engine.rs): `src/autograd/engine.rs`
- [Backward rules](https://github.com/canreader/fastnn/tree/master/src/autograd/ops): `src/autograd/ops`
- [Parameter slots](https://github.com/canreader/fastnn/blob/master/src/nn/param.rs): `src/nn/param.rs`
- [Optimizers](https://github.com/canreader/fastnn/tree/master/src/optim): `src/optim`
- [Learning-rate schedules](https://github.com/canreader/fastnn/blob/master/src/optim/schedule.rs): `src/optim/schedule.rs`

### Compute backend

- [Tensor storage](https://github.com/canreader/fastnn/blob/master/src/tensor/storage.rs): `src/tensor/storage.rs`
- [CUDA kernels and bindings](https://github.com/canreader/fastnn/blob/master/src/cuda/kernels.rs): `src/cuda/kernels.rs`
- [CUDA FFI](https://github.com/canreader/fastnn/blob/master/src/cuda/ffi.rs): `src/cuda/ffi.rs`

### Persistence

- [Native checkpoints](https://github.com/canreader/fastnn/blob/master/src/serialize/checkpoint.rs): `src/serialize/checkpoint.rs`
- [Training-state checkpoints](https://github.com/canreader/fastnn/blob/master/src/serialize/training.rs): `src/serialize/training.rs`
- [Safetensors interchange](https://github.com/canreader/fastnn/blob/master/src/serialize/safetensors.rs): `src/serialize/safetensors.rs`
- **Checkpoint files**

### Other components

- **Training caller**
- **CUDA device**

## Connections

- Training caller → MNIST dataset: loads data
- MNIST dataset → Dataset interface: implements (evidence: `src/data/mnist.rs`)
- Training caller → DataLoader: batches data
- DataLoader → Dataset interface: reads samples (evidence: `src/data/loader.rs`)
- DataLoader → Tensor operations: places batches
- Training caller → Neural layers: runs model
- Neural layers → Tensor operations: computes with (evidence: `src/tensor/ops/conv.rs`)
- Training caller → Loss functions: computes loss
- Loss functions → Tensor operations: uses operations (evidence: `src/nn/loss.rs`)
- Neural layers → Parameter slots: holds handles (evidence: `src/nn/module.rs`)
- Loss functions → Reverse-mode autograd: starts backward
- Reverse-mode autograd → Backward rules: applies rules (evidence: `src/autograd/engine.rs`)
- Reverse-mode autograd → Parameter slots: accumulates gradients (evidence: `src/autograd/engine.rs`)
- Training caller → Optimizers: updates parameters
- Optimizers → Parameter slots: reads and updates (evidence: `src/optim/mod.rs`)
- Learning-rate schedules → Optimizers: sets learning rate (evidence: `src/optim/mod.rs`)
- Training caller → Transformers and generation: builds or generates
- Tensor operations → Tensor storage: uses storage (evidence: `src/tensor/ops/mod.rs`)
- Tensor storage → CUDA kernels and bindings: allocates GPU buffers (evidence: `src/tensor/storage.rs`)
- Tensor operations → CUDA kernels and bindings: dispatches GPU ops (evidence: `src/tensor/ops/mod.rs`)
- CUDA kernels and bindings → CUDA FFI: calls bindings (evidence: `src/cuda/kernels.rs`)
- CUDA FFI → CUDA device: launches kernels
- Training caller → Native checkpoints: saves or loads
- Training caller → Training-state checkpoints: resumes training
- Training caller → Safetensors interchange: imports or exports
- Native checkpoints → Checkpoint files: reads and writes
- Training-state checkpoints → Checkpoint files: reads and writes
- Safetensors interchange → Checkpoint files: reads and writes
