# youcef3939/cml architecture

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

- Interactive diagram: https://gitdiagram.com/youcef3939/cml
- Repository: https://github.com/youcef3939/cml

## Overview

1. **What this repo is**
   - CML is a small machine-learning framework written in pure C.
   - It is organized as a layered system: low-level tensor/autograd primitives at the bottom, neural-network modules above that, then training utilities and an example program on top.

2. **Top-level runtime flow**
   - The main execution path is: load CSV data → wrap it as tensors → run a model forward pass → compute loss → call backward/autograd → update parameters with SGD.
   - The example in `examples/mlp_train.c` is the best entry point for understanding how the pieces connect.

3. **Tensor subsystem**
   - `tensor/tensor.c`, `tensor/tensor.h` define the core `Tensor` type.
   - This layer is responsible for N-dimensional float32 storage, shape/stride tracking, contiguous layout, views such as reshape/slice without copying, and gradient buffers.
   - This is the foundational boundary: everything else in the repo consumes or produces `Tensor*`.

4. **Tensor operations**
   - `tensor/ops.c` contains the forward implementations of math primitives such as elementwise arithmetic, matrix multiplication, reduction, and broadcasting behavior.
   - These ops are the basic computational units that model code builds from.

5. **Autograd / backward pass**
   - `tensor/backward.c` and `autograd/engine.c` implement reverse-mode automatic differentiation.
   - The architecture is dynamic graph-based: each tensor can remember its parents and a backward function, and the backward pass walks the graph in reverse topological order.
   - Gradients are accumulated explicitly into tensor-owned gradient buffers.

6. **Neural network layer boundary**
   - `nn/linear.c`, `nn/linear.h` implement dense layers with explicit weight and bias tensors.
   - `nn/activations.c`, `nn/activations.h` provide activation functions such as ReLU, sigmoid, and tanh.
   - These modules are thin wrappers over tensor ops plus autograd-enabled composition, so they are a higher-level modeling layer rather than a separate runtime.

7. **Loss functions**
   - `nn/loss.c`, `nn/loss.h` define training objectives such as MSE and BCE.
   - Loss is the bridge between model outputs and backpropagation: the computed scalar loss is what triggers gradient propagation through the graph.

8. **Optimizer subsystem**
   - `optim/sgd.c`, `optim/sgd.h` implement stochastic gradient descent.
   - This layer reads accumulated parameter gradients and applies in-place parameter updates, forming the “learning” step after backprop.

9. **Data ingestion**
   - `data/csv.c`, `data/csv.h` load tabular data from CSV files into the program.
   - The included `data/train_X.csv` and `data/train_y.csv` are sample training inputs and targets used by the example pipeline.
   - This is the only explicit dataset boundary in the repo; there is no broader data pipeline or storage layer.

10. **Example application**
   - `examples/mlp_train.c` ties all subsystems together into a minimal training loop for an MLP.
   - It demonstrates how the repo expects to be used: read data, build tensors, instantiate a model, compute loss, backpropagate, and step the optimizer.

11. **Main architectural boundaries**
   - The repo is intentionally split into four concentric layers:
     - **Core math/runtime**: `tensor/` and `autograd/`
     - **Modeling primitives**: `nn/`
     - **Training logic**: `optim/`
     - **I/O and orchestration**: `data/` and `examples/`
   - This separation keeps the tensor engine independent from the neural-network and training code.

12. **Technology profile**
   - The project is C-only, with no Python, CUDA, BLAS/LAPACK, or external ML framework dependency.
   - Build is done by compiling the C sources directly with `gcc` and linking the math library (`-lm`).
   - The architecture therefore emphasizes explicit memory management, explicit graph construction, and explicit training control.

13. **What an architecture diagram should emphasize**
   - Put `Tensor` at the center as the shared data structure.
   - Show forward computation flowing from CSV data through tensor ops into linear layers/activations and then loss.
   - Show backward computation flowing from loss back through the autograd engine into parameter gradients.
   - Show SGD consuming those gradients to mutate the model parameters.

Main entry points: [`examples/mlp_train.c`](https://github.com/youcef3939/cml/blob/main/examples/mlp_train.c) (MLP Train), [`tensor/tensor.c`](https://github.com/youcef3939/cml/blob/main/tensor/tensor.c) (Tensor), [`data/csv.c`](https://github.com/youcef3939/cml/blob/main/data/csv.c) (CSV Loader), [`nn/linear.c`](https://github.com/youcef3939/cml/blob/main/nn/linear.c) (Linear)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data I/O"]
  node_csv["CSV Loader<br/>input parser<br/>[csv.c]"]
  node_train_x["Train X<br/>sample data<br/>[train_X.csv]"]
  node_train_y["Train Y<br/>sample data<br/>[train_y.csv]"]
end

subgraph group_core["Core Runtime"]
  node_tensor["Tensor<br/>core data structure<br/>[tensor.c]"]
  node_ops["Ops<br/>math kernels<br/>[ops.c]"]
  node_backward["Backward<br/>grad propagation<br/>[backward.c]"]
  node_engine["Autograd<br/>engine<br/>[engine.c]"]
end

subgraph group_nn["Neural Net"]
  node_linear["Linear<br/>dense layer<br/>[linear.c]"]
  node_activations["Activations<br/>nonlinear ops<br/>[activations.c]"]
end

subgraph group_train["Training"]
  node_loss["Losses<br/>objectives<br/>[loss.c]"]
  node_sgd["SGD<br/>optimizer<br/>[sgd.c]"]
end

subgraph group_app["Example"]
  node_mlp_train["MLP Train<br/>example app<br/>[mlp_train.c]"]
end

node_train_x -->|"read"| node_csv
node_train_y -->|"read"| node_csv
node_csv -->|"wrap"| node_tensor
node_tensor -->|"compute"| node_ops
node_ops -->|"feed"| node_linear
node_linear -->|"transform"| node_activations
node_activations -->|"score"| node_loss
node_loss -->|"backprop"| node_engine
node_engine -->|"dispatch"| node_backward
node_backward -->|"accumulate"| node_tensor
node_tensor -->|"params"| node_sgd
node_sgd -->|"update"| node_linear
node_mlp_train -->|"load"| node_csv
node_mlp_train -->|"build"| node_tensor
node_mlp_train -->|"model"| node_linear
node_mlp_train -->|"loss"| node_loss
node_mlp_train -->|"train"| node_engine
node_mlp_train -->|"step"| node_sgd

click node_tensor "https://github.com/youcef3939/cml/blob/main/tensor/tensor.c"
click node_ops "https://github.com/youcef3939/cml/blob/main/tensor/ops.c"
click node_backward "https://github.com/youcef3939/cml/blob/main/tensor/backward.c"
click node_engine "https://github.com/youcef3939/cml/blob/main/autograd/engine.c"
click node_csv "https://github.com/youcef3939/cml/blob/main/data/csv.c"
click node_linear "https://github.com/youcef3939/cml/blob/main/nn/linear.c"
click node_activations "https://github.com/youcef3939/cml/blob/main/nn/activations.c"
click node_loss "https://github.com/youcef3939/cml/blob/main/nn/loss.c"
click node_sgd "https://github.com/youcef3939/cml/blob/main/optim/sgd.c"
click node_mlp_train "https://github.com/youcef3939/cml/blob/main/examples/mlp_train.c"
click node_train_x "https://github.com/youcef3939/cml/blob/main/data/train_X.csv"
click node_train_y "https://github.com/youcef3939/cml/blob/main/data/train_y.csv"

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_csv,node_train_x,node_train_y toneBlue
class node_tensor,node_ops,node_backward,node_engine toneAmber
class node_linear,node_activations toneMint
class node_loss,node_sgd toneRose
class node_mlp_train toneIndigo
```

## Components

### Data I/O

CSV ingestion and sample training files.

- [CSV Loader](https://github.com/youcef3939/cml/blob/main/data/csv.c): input parser · Loads tabular training data into memory for the example pipeline. · `data/csv.c`
- [Train X](https://github.com/youcef3939/cml/blob/main/data/train_X.csv): sample data · Example feature matrix used by the training demo. · `data/train_X.csv`
- [Train Y](https://github.com/youcef3939/cml/blob/main/data/train_y.csv): sample data · Example target values used by the training demo. · `data/train_y.csv`

### Core Runtime

Tensor storage, math ops, and autograd.

- [Tensor](https://github.com/youcef3939/cml/blob/main/tensor/tensor.c): core data structure · N-D float32 tensors with shape, strides, views, and gradients. · `tensor/tensor.c`
- [Ops](https://github.com/youcef3939/cml/blob/main/tensor/ops.c): math kernels · Forward tensor math such as elementwise ops, matmul, reduction, and broadcasting. · `tensor/ops.c`
- [Backward](https://github.com/youcef3939/cml/blob/main/tensor/backward.c): grad propagation · Tensor-level backward helpers for reverse-mode autodiff. · `tensor/backward.c`
- [Autograd](https://github.com/youcef3939/cml/blob/main/autograd/engine.c): engine · Walks the dynamic computation graph in reverse topological order and accumulates gradients. · `autograd/engine.c`

### Neural Net

Modeling primitives built on tensors.

- [Linear](https://github.com/youcef3939/cml/blob/main/nn/linear.c): dense layer · Fully connected layer with explicit weight and bias tensors. · `nn/linear.c`
- [Activations](https://github.com/youcef3939/cml/blob/main/nn/activations.c): nonlinear ops · ReLU, sigmoid, and tanh wrappers built on tensor primitives. · `nn/activations.c`

### Training

Optimization and loss computation.

- [Losses](https://github.com/youcef3939/cml/blob/main/nn/loss.c): objectives · Training objectives such as MSE and BCE that produce scalar loss values. · `nn/loss.c`
- [SGD](https://github.com/youcef3939/cml/blob/main/optim/sgd.c): optimizer · Applies in-place parameter updates from accumulated gradients. · `optim/sgd.c`

### Example

End-to-end training entry point.

- [MLP Train](https://github.com/youcef3939/cml/blob/main/examples/mlp_train.c): example app · Minimal end-to-end training loop demonstrating data loading, forward pass, backprop, and optimization. · `examples/mlp_train.c`

## Connections

- Train X → CSV Loader: read · Feature data is loaded from CSV.
- Train Y → CSV Loader: read · Target data is loaded from CSV.
- CSV Loader → Tensor: wrap · Parsed values are wrapped as tensors.
- Tensor → Ops: compute · Tensor operations build the forward computation.
- Ops → Linear: feed · Linear layers consume tensor math outputs.
- Linear → Activations: transform · Activations are applied after affine transforms.
- Activations → Losses: score · Model outputs are compared to targets via loss functions.
- Losses → Autograd: backprop · Scalar loss triggers reverse-mode differentiation.
- Autograd → Backward: dispatch · Autograd engine coordinates backward functions.
- Backward → Tensor: accumulate · Gradients are accumulated into tensor-owned buffers.
- Tensor → SGD: params · Parameter tensors with gradients are updated in place.
- SGD → Linear: update · Optimizer mutates layer weights and biases.
- MLP Train → CSV Loader: load · Example starts by loading the CSV dataset.
- MLP Train → Tensor: build · Example converts data into tensors and creates model state.
- MLP Train → Linear: model · Example instantiates and runs the MLP layers.
- MLP Train → Losses: loss · Example computes the training objective.
- MLP Train → Autograd: train · Example invokes backward propagation.
- MLP Train → SGD: step · Example applies optimizer updates after gradients are computed.
