# raven-ml/raven architecture

> Architecture diagram of the GitHub repository raven-ml/raven, 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/raven-ml/raven
- Repository: https://github.com/raven-ml/raven

## Overview

Raven is an OCaml scientific-computing ecosystem. Its documented user-facing capabilities include arrays and ML compilation, tokenization, notebook-based interaction, and experiment tracking. The excerpts show internal detail chiefly for Nx’s CPU engine and codecs, Tolk’s CUDA runtime, and Quill’s notebook frontend; other package relationships are therefore kept separate rather than inferred. Several README-described capabilities have only partial source coverage in this tree.

Main entry points: [`packages/quill/lib/quill-server/frontend/src/app.js`](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/app.js) (Notebook interface), [`packages/nx/lib/cpu`](https://github.com/raven-ml/raven/tree/main/packages/nx/lib/cpu) (N-dimensional arrays), [`packages/quill/lib/quill-server/frontend/src/cell.js`](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/cell.js) (Cell rendering), [`packages/quill/lib/quill-server/frontend/src/notebook.js`](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/notebook.js) (Notebook renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_numerics["Arrays and numerics"]
  node_nx["N-dimensional arrays"]
  node_nxengine["CPU execution engine<br/>[nx_c_engine.c]"]
  node_nxkernels["CPU kernel families"]
  node_nxdtype["Low-precision types<br/>[nx_dtype.h]"]
  node_nxdevices["Device backends"]
  node_nxcodecs["Image and data codecs"]
end

subgraph group_compute["ML computation"]
  node_tolk["ML compiler"]
  node_tolkcpu["CPU runtime<br/>[tolk_cpu_stubs.c]"]
  node_tolkcuda["CUDA runtime<br/>[tolk_cuda_stubs.c]"]
  node_tolkdl["Dynamic library loader<br/>[tolk_dl.h]"]
  node_tolkother["Other device runtimes"]
end

subgraph group_notebooks["Interactive notebooks"]
  node_quill["Notebook interface<br/>[app.js]"]
  node_qstore["Notebook state<br/>[store.js]"]
  node_qws["WebSocket client<br/>[ws.js]"]
  node_qnotebook["Notebook renderer<br/>[notebook.js]"]
  node_qcell["Cell rendering<br/>[cell.js]"]
  node_qeditor["Code editor<br/>[editor.js]"]
  node_qoutput["Output rendering<br/>[output.js]"]
  node_qmath["Math rendering<br/>[math.js]"]
  node_qshortcuts["Keyboard shortcuts<br/>[shortcuts.js]"]
end

subgraph group_data["Data and tracking"]
  node_brot["Tokenizer<br/>[brot_kernels.c]"]
  node_munin["Experiment tracking<br/>[sysstat_stubs.c]"]
end

node_user(("OCaml user"))

node_user -->|"uses arrays"| node_nx
node_user -->|"uses compiler"| node_tolk
node_user -->|"opens notebooks"| node_quill
node_user -->|"tokenizes text"| node_brot
node_user -->|"tracks experiments"| node_munin
node_nx -.->|"runs CPU operations"| node_nxengine
node_nxengine -->|"dispatches kernels"| node_nxkernels
node_nx -->|"uses types"| node_nxdtype
node_nx -->|"uses devices"| node_nxdevices
node_quill -->|"creates state"| node_qstore
node_quill -->|"creates client"| node_qws
node_quill -->|"mounts renderer"| node_qnotebook
node_quill -->|"initializes shortcuts"| node_qshortcuts
node_qnotebook -->|"renders cells"| node_qcell
node_qnotebook -->|"appends output"| node_qoutput
node_qcell -->|"creates editors"| node_qeditor
node_qcell -->|"renders math"| node_qmath
node_qcell -->|"renders outputs"| node_qoutput
node_tolkcuda -->|"resolves symbols"| node_tolkdl

click node_nx "https://github.com/raven-ml/raven/tree/main/packages/nx/lib/cpu"
click node_nxengine "https://github.com/raven-ml/raven/blob/main/packages/nx/lib/cpu/nx_c_engine.c"
click node_nxkernels "https://github.com/raven-ml/raven/tree/main/packages/nx/lib/cpu"
click node_nxdtype "https://github.com/raven-ml/raven/blob/main/packages/nx/lib/dtype/nx_dtype.h"
click node_nxdevices "https://github.com/raven-ml/raven/tree/main/packages/nx/lib/device"
click node_nxcodecs "https://github.com/raven-ml/raven/tree/main/packages/nx/lib/io/codec"
click node_tolk "https://github.com/raven-ml/raven/tree/main/packages/tolk/lib"
click node_tolkcpu "https://github.com/raven-ml/raven/blob/main/packages/tolk/lib/runtime/cpu/tolk_cpu_stubs.c"
click node_tolkcuda "https://github.com/raven-ml/raven/blob/main/packages/tolk/lib/runtime/cuda/tolk_cuda_stubs.c"
click node_tolkdl "https://github.com/raven-ml/raven/blob/main/packages/tolk/lib/runtime/support/tolk_dl.h"
click node_tolkother "https://github.com/raven-ml/raven/tree/main/packages/tolk/lib/runtime"
click node_quill "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/app.js"
click node_qstore "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/store.js"
click node_qws "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/ws.js"
click node_qnotebook "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/notebook.js"
click node_qcell "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/cell.js"
click node_qeditor "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/editor.js"
click node_qoutput "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/output.js"
click node_qmath "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/math.js"
click node_qshortcuts "https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/shortcuts.js"
click node_brot "https://github.com/raven-ml/raven/blob/main/packages/brot/lib/brot_kernels.c"
click node_munin "https://github.com/raven-ml/raven/blob/main/packages/munin/lib/sys/sysstat_stubs.c"

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_nx,node_nxengine,node_nxkernels,node_nxdtype,node_nxdevices,node_nxcodecs,node_user toneBlue
class node_tolk,node_tolkcpu,node_tolkcuda,node_tolkdl,node_tolkother toneAmber
class node_quill,node_qstore,node_qws,node_qnotebook,node_qcell,node_qeditor,node_qoutput,node_qmath,node_qshortcuts toneMint
class node_brot,node_munin toneRose
```

## Components

### Arrays and numerics

- [N-dimensional arrays](https://github.com/raven-ml/raven/tree/main/packages/nx/lib/cpu): `packages/nx/lib/cpu`
- [CPU execution engine](https://github.com/raven-ml/raven/blob/main/packages/nx/lib/cpu/nx_c_engine.c): `packages/nx/lib/cpu/nx_c_engine.c`
- [CPU kernel families](https://github.com/raven-ml/raven/tree/main/packages/nx/lib/cpu): `packages/nx/lib/cpu`
- [Low-precision types](https://github.com/raven-ml/raven/blob/main/packages/nx/lib/dtype/nx_dtype.h): `packages/nx/lib/dtype/nx_dtype.h`
- [Device backends](https://github.com/raven-ml/raven/tree/main/packages/nx/lib/device): `packages/nx/lib/device`
- [Image and data codecs](https://github.com/raven-ml/raven/tree/main/packages/nx/lib/io/codec): `packages/nx/lib/io/codec`

### ML computation

- [ML compiler](https://github.com/raven-ml/raven/tree/main/packages/tolk/lib): `packages/tolk/lib`
- [CPU runtime](https://github.com/raven-ml/raven/blob/main/packages/tolk/lib/runtime/cpu/tolk_cpu_stubs.c): `packages/tolk/lib/runtime/cpu/tolk_cpu_stubs.c`
- [CUDA runtime](https://github.com/raven-ml/raven/blob/main/packages/tolk/lib/runtime/cuda/tolk_cuda_stubs.c): `packages/tolk/lib/runtime/cuda/tolk_cuda_stubs.c`
- [Dynamic library loader](https://github.com/raven-ml/raven/blob/main/packages/tolk/lib/runtime/support/tolk_dl.h): `packages/tolk/lib/runtime/support/tolk_dl.h`
- [Other device runtimes](https://github.com/raven-ml/raven/tree/main/packages/tolk/lib/runtime): `packages/tolk/lib/runtime`

### Interactive notebooks

- [Notebook interface](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/app.js): `packages/quill/lib/quill-server/frontend/src/app.js`
- [Notebook state](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/store.js): `packages/quill/lib/quill-server/frontend/src/store.js`
- [WebSocket client](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/ws.js): `packages/quill/lib/quill-server/frontend/src/ws.js`
- [Notebook renderer](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/notebook.js): `packages/quill/lib/quill-server/frontend/src/notebook.js`
- [Cell rendering](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/cell.js): `packages/quill/lib/quill-server/frontend/src/cell.js`
- [Code editor](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/editor.js): `packages/quill/lib/quill-server/frontend/src/editor.js`
- [Output rendering](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/output.js): `packages/quill/lib/quill-server/frontend/src/output.js`
- [Math rendering](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/math.js): `packages/quill/lib/quill-server/frontend/src/math.js`
- [Keyboard shortcuts](https://github.com/raven-ml/raven/blob/main/packages/quill/lib/quill-server/frontend/src/shortcuts.js): `packages/quill/lib/quill-server/frontend/src/shortcuts.js`

### Data and tracking

- [Tokenizer](https://github.com/raven-ml/raven/blob/main/packages/brot/lib/brot_kernels.c): `packages/brot/lib/brot_kernels.c`
- [Experiment tracking](https://github.com/raven-ml/raven/blob/main/packages/munin/lib/sys/sysstat_stubs.c): `packages/munin/lib/sys/sysstat_stubs.c`

### Other components

- **OCaml user**

## Connections

- OCaml user → N-dimensional arrays: uses arrays
- OCaml user → ML compiler: uses compiler
- OCaml user → Notebook interface: opens notebooks
- OCaml user → Tokenizer: tokenizes text
- OCaml user → Experiment tracking: tracks experiments
- N-dimensional arrays → CPU execution engine: runs CPU operations (evidence: `packages/nx/lib/cpu/nx_c_engine.c`)
- CPU execution engine → CPU kernel families: dispatches kernels (evidence: `packages/nx/lib/cpu/nx_c_engine.h`)
- N-dimensional arrays → Low-precision types: uses types (evidence: `packages/nx/lib/cpu/nx_c.h`)
- N-dimensional arrays → Device backends: uses devices (evidence: `packages/nx/lib/cpu/nx_c.h`)
- Notebook interface → Notebook state: creates state (evidence: `packages/quill/lib/quill-server/frontend/src/app.js`)
- Notebook interface → WebSocket client: creates client (evidence: `packages/quill/lib/quill-server/frontend/src/app.js`)
- Notebook interface → Notebook renderer: mounts renderer (evidence: `packages/quill/lib/quill-server/frontend/src/app.js`)
- Notebook interface → Keyboard shortcuts: initializes shortcuts (evidence: `packages/quill/lib/quill-server/frontend/src/app.js`)
- Notebook renderer → Cell rendering: renders cells (evidence: `packages/quill/lib/quill-server/frontend/src/notebook.js`)
- Notebook renderer → Output rendering: appends output (evidence: `packages/quill/lib/quill-server/frontend/src/notebook.js`)
- Cell rendering → Code editor: creates editors (evidence: `packages/quill/lib/quill-server/frontend/src/cell.js`)
- Cell rendering → Math rendering: renders math (evidence: `packages/quill/lib/quill-server/frontend/src/cell.js`)
- Cell rendering → Output rendering: renders outputs (evidence: `packages/quill/lib/quill-server/frontend/src/cell.js`)
- CUDA runtime → Dynamic library loader: resolves symbols (evidence: `packages/tolk/lib/runtime/cuda/tolk_cuda_stubs.c`)
