# eukalpia/tensora architecture

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

- Interactive diagram: https://gitdiagram.com/eukalpia/tensora
- Repository: https://github.com/eukalpia/tensora

## Overview

Tensora is a native machine-learning runtime for Dart, exposing tensors and optional training and ONNX inference through a C ABI. The main workflow is a Dart application calling native entry points, which manage opaque handles and dispatch numerical work to CPU or optional LibTorch/ONNX implementations. Tensor shapes, storage, and device identity form shared runtime foundations. The README documents the public workflow and optional capabilities; source-index references and sampled headers support the native layers, but several backend implementations were not sampled, so their internal call details are not expanded.

Main entry points: [`native/src/c_api.cc`](https://github.com/eukalpia/tensora/blob/main/native/src/c_api.cc) (Core entry points), [`native/src/runtime/dispatcher.cc`](https://github.com/eukalpia/tensora/blob/main/native/src/runtime/dispatcher.cc) (Backend dispatcher), [`native/src/backends/cpu/cpu_backend.cc`](https://github.com/eukalpia/tensora/blob/main/native/src/backends/cpu/cpu_backend.cc) (CPU operations), [`native/src/training/training_bridge.h`](https://github.com/eukalpia/tensora/blob/main/native/src/training/training_bridge.h) (Training bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Native API"]
  node_cabi["C ABI<br/>[tensora.h]"]
  node_core_entry["Core entry points<br/>[c_api.cc]"]
  node_inference_entry["Inference entry points<br/>[inference_c_api.cc]"]
  node_training_entry["Training entry points<br/>[training_c_api.cc]"]
end

subgraph group_runtime["Tensor Runtime"]
  node_dispatcher["Backend dispatcher<br/>[dispatcher.cc]"]
  node_handles[("Opaque handles<br/>[handle_registry.cc]")]
  node_device_codec["Device codec<br/>[device_codec.cc]"]
  node_shape["Shape validation<br/>[shape.cc]"]
  node_tensor["Tensor object<br/>[tensor.cc]"]
  node_storage_contract["Storage contract<br/>[tensor_storage.h]"]
  node_cpu_storage[("CPU storage<br/>[cpu_storage.cc]")]
end

subgraph group_compute["Compute Backends"]
  node_cpu_backend["CPU operations<br/>[cpu_backend.cc]"]
end

subgraph group_training["Training"]
  node_autograd["Autograd<br/>[autograd.h]"]
  node_training_bridge["Training bridge<br/>[training_bridge.h]"]
  node_torch_backend["LibTorch backend<br/>[torch_backend.cc]"]
  node_torch_storage[("Torch storage<br/>[torch_storage.cc]")]
end

subgraph group_inference["ONNX Inference"]
  node_inference_bridge["Inference bridge<br/>[inference_bridge.h]"]
  node_onnx_runtime["ONNX implementation"]
end

node_dart(("Dart application"))

node_dart -->|"calls"| node_cabi
node_cabi -->|"exports through"| node_core_entry
node_core_entry -->|"dispatches"| node_dispatcher
node_core_entry -->|"manages handles"| node_handles
node_core_entry -->|"encodes devices"| node_device_codec
node_dispatcher -->|"selects"| node_cpu_backend
node_dispatcher -->|"selects"| node_torch_backend
node_cpu_backend -->|"records gradients"| node_autograd
node_cpu_backend -->|"allocates"| node_cpu_storage
node_tensor -->|"owns storage"| node_storage_contract
node_cpu_storage -->|"implements"| node_storage_contract
node_torch_storage -->|"implements"| node_storage_contract
node_core_entry -->|"validates shapes"| node_shape
node_training_entry -->|"invokes"| node_training_bridge
node_training_entry -->|"manages handles"| node_handles
node_training_bridge -->|"uses"| node_autograd
node_training_bridge -->|"delegates"| node_torch_backend
node_torch_backend -->|"uses"| node_torch_storage
node_inference_entry -->|"invokes"| node_inference_bridge
node_inference_entry -->|"manages sessions"| node_handles
node_inference_bridge -->|"implemented by"| node_onnx_runtime
node_inference_bridge -.->|"stub alternative"| node_onnx_runtime

click node_cabi "https://github.com/eukalpia/tensora/blob/main/native/include/tensora.h"
click node_core_entry "https://github.com/eukalpia/tensora/blob/main/native/src/c_api.cc"
click node_inference_entry "https://github.com/eukalpia/tensora/blob/main/native/src/inference/inference_c_api.cc"
click node_training_entry "https://github.com/eukalpia/tensora/blob/main/native/src/training/training_c_api.cc"
click node_dispatcher "https://github.com/eukalpia/tensora/blob/main/native/src/runtime/dispatcher.cc"
click node_handles "https://github.com/eukalpia/tensora/blob/main/native/src/runtime/handle_registry.cc"
click node_device_codec "https://github.com/eukalpia/tensora/blob/main/native/src/runtime/device_codec.cc"
click node_shape "https://github.com/eukalpia/tensora/blob/main/native/src/tensor/shape.cc"
click node_tensor "https://github.com/eukalpia/tensora/blob/main/native/src/tensor/tensor.cc"
click node_storage_contract "https://github.com/eukalpia/tensora/blob/main/native/src/memory/tensor_storage.h"
click node_cpu_storage "https://github.com/eukalpia/tensora/blob/main/native/src/memory/cpu_storage.cc"
click node_cpu_backend "https://github.com/eukalpia/tensora/blob/main/native/src/backends/cpu/cpu_backend.cc"
click node_autograd "https://github.com/eukalpia/tensora/blob/main/native/src/autograd/autograd.h"
click node_training_bridge "https://github.com/eukalpia/tensora/blob/main/native/src/training/training_bridge.h"
click node_torch_backend "https://github.com/eukalpia/tensora/blob/main/native/src/training/torch_backend.cc"
click node_torch_storage "https://github.com/eukalpia/tensora/blob/main/native/src/training/torch_storage.cc"
click node_inference_bridge "https://github.com/eukalpia/tensora/blob/main/native/src/inference/inference_bridge.h"
click node_onnx_runtime "https://github.com/eukalpia/tensora/blob/main/native/src/inference/inference_bridge_onnx.cc"

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_cabi,node_core_entry,node_inference_entry,node_training_entry toneBlue
class node_dispatcher,node_handles,node_device_codec,node_shape,node_tensor,node_storage_contract,node_cpu_storage toneAmber
class node_cpu_backend toneMint
class node_autograd,node_training_bridge,node_torch_backend,node_torch_storage toneRose
class node_inference_bridge,node_onnx_runtime,node_dart toneIndigo
```

## Components

### Native API

- [C ABI](https://github.com/eukalpia/tensora/blob/main/native/include/tensora.h): `native/include/tensora.h`
- [Core entry points](https://github.com/eukalpia/tensora/blob/main/native/src/c_api.cc): `native/src/c_api.cc`
- [Inference entry points](https://github.com/eukalpia/tensora/blob/main/native/src/inference/inference_c_api.cc): `native/src/inference/inference_c_api.cc`
- [Training entry points](https://github.com/eukalpia/tensora/blob/main/native/src/training/training_c_api.cc): `native/src/training/training_c_api.cc`

### Tensor Runtime

- [Backend dispatcher](https://github.com/eukalpia/tensora/blob/main/native/src/runtime/dispatcher.cc): `native/src/runtime/dispatcher.cc`
- [Opaque handles](https://github.com/eukalpia/tensora/blob/main/native/src/runtime/handle_registry.cc): `native/src/runtime/handle_registry.cc`
- [Device codec](https://github.com/eukalpia/tensora/blob/main/native/src/runtime/device_codec.cc): `native/src/runtime/device_codec.cc`
- [Shape validation](https://github.com/eukalpia/tensora/blob/main/native/src/tensor/shape.cc): `native/src/tensor/shape.cc`
- [Tensor object](https://github.com/eukalpia/tensora/blob/main/native/src/tensor/tensor.cc): `native/src/tensor/tensor.cc`
- [Storage contract](https://github.com/eukalpia/tensora/blob/main/native/src/memory/tensor_storage.h): `native/src/memory/tensor_storage.h`
- [CPU storage](https://github.com/eukalpia/tensora/blob/main/native/src/memory/cpu_storage.cc): `native/src/memory/cpu_storage.cc`

### Compute Backends

- [CPU operations](https://github.com/eukalpia/tensora/blob/main/native/src/backends/cpu/cpu_backend.cc): `native/src/backends/cpu/cpu_backend.cc`

### Training

- [Autograd](https://github.com/eukalpia/tensora/blob/main/native/src/autograd/autograd.h): `native/src/autograd/autograd.h`
- [Training bridge](https://github.com/eukalpia/tensora/blob/main/native/src/training/training_bridge.h): `native/src/training/training_bridge.h`
- [LibTorch backend](https://github.com/eukalpia/tensora/blob/main/native/src/training/torch_backend.cc): `native/src/training/torch_backend.cc`
- [Torch storage](https://github.com/eukalpia/tensora/blob/main/native/src/training/torch_storage.cc): `native/src/training/torch_storage.cc`

### ONNX Inference

- [Inference bridge](https://github.com/eukalpia/tensora/blob/main/native/src/inference/inference_bridge.h): `native/src/inference/inference_bridge.h`
- [ONNX implementation](https://github.com/eukalpia/tensora/blob/main/native/src/inference/inference_bridge_onnx.cc): `native/src/inference/inference_bridge_onnx.cc`

### Other components

- **Dart application**

## Connections

- Dart application → C ABI: calls (evidence: `README.md`)
- C ABI → Core entry points: exports through (evidence: `native/src/c_api.cc`)
- Core entry points → Backend dispatcher: dispatches (evidence: `native/src/c_api.cc`)
- Core entry points → Opaque handles: manages handles (evidence: `native/src/c_api.cc`)
- Core entry points → Device codec: encodes devices (evidence: `native/src/c_api.cc`)
- Backend dispatcher → CPU operations: selects (evidence: `native/src/runtime/dispatcher.cc`)
- Backend dispatcher → LibTorch backend: selects (evidence: `native/src/runtime/dispatcher.cc`)
- CPU operations → Autograd: records gradients (evidence: `native/src/backends/cpu/cpu_backend.cc`)
- CPU operations → CPU storage: allocates (evidence: `native/src/backends/cpu/cpu_backend.cc`)
- Tensor object → Storage contract: owns storage
- CPU storage → Storage contract: implements
- Torch storage → Storage contract: implements
- Core entry points → Shape validation: validates shapes (evidence: `native/src/c_api.cc`)
- Training entry points → Training bridge: invokes (evidence: `native/src/training/training_c_api.cc`)
- Training entry points → Opaque handles: manages handles (evidence: `native/src/training/training_c_api.cc`)
- Training bridge → Autograd: uses (evidence: `native/src/training/training_bridge.h`)
- Training bridge → LibTorch backend: delegates
- LibTorch backend → Torch storage: uses (evidence: `native/src/training/torch_storage.cc`)
- Inference entry points → Inference bridge: invokes (evidence: `native/src/inference/inference_c_api.cc`)
- Inference entry points → Opaque handles: manages sessions (evidence: `native/src/inference/inference_c_api.cc`)
- Inference bridge → ONNX implementation: implemented by (evidence: `native/src/inference/inference_bridge_onnx.cc`)
- Inference bridge → ONNX implementation: stub alternative (evidence: `native/src/inference/inference_bridge_onnx.cc`)
