# frikallo/axiom architecture

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

- Interactive diagram: https://gitdiagram.com/frikallo/axiom
- Repository: https://github.com/frikallo/axiom

## Overview

Axiom is a native C++ tensor library. A caller creates tensors and chains tensor or operation APIs; lazy operations form a graph, which is compiled and executed on CPU or Metal, and results can be serialized. The graph emphasizes documented capabilities and relationships visible in the README, excerpts, or SOURCE INDEX. Several backend and neural-network implementations were not sampled, so their internal call relationships are omitted where evidence is insufficient.

Main entry points: [`include/axiom/tensor.hpp`](https://github.com/frikallo/axiom/blob/main/include/axiom/tensor.hpp) (Tensor API), [`src/tensor/operations.cpp`](https://github.com/frikallo/axiom/blob/main/src/tensor/operations.cpp) (Tensor operations), [`src/graph/graph_registry.cpp`](https://github.com/frikallo/axiom/blob/main/src/graph/graph_registry.cpp) (Graph registry), [`src/graph/graph_executor.cpp`](https://github.com/frikallo/axiom/blob/main/src/graph/graph_executor.cpp) (Graph executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Tensor API"]
  node_tensor["Tensor API<br/>[tensor.hpp]"]
  node_ops["Tensor operations<br/>[operations.cpp]"]
  node_shape["Shape utilities<br/>[shape.hpp]"]
  node_dtype["Data types<br/>[dtype.hpp]"]
end

subgraph group_compute["Lazy Compute"]
  node_graph_registry["Graph registry<br/>[graph_registry.cpp]"]
  node_graph_node["Graph nodes<br/>[graph_node.hpp]"]
  node_graph_compiler["Graph compiler<br/>[graph_compiler.cpp]"]
  node_compiled_graph["Compiled graph<br/>[compiled_graph.hpp]"]
  node_graph_executor["Graph executor<br/>[graph_executor.cpp]"]
  node_graph_cache["Graph cache<br/>[graph_cache.cpp]"]
  node_fusion["Kernel fusion<br/>[fused_kernel.cpp]"]
end

subgraph group_backend["Devices &amp; Storage"]
  node_cpu_ops["CPU operations<br/>[cpu_operations.cpp]"]
  node_metal_ops["Metal operations"]
  node_cpu_storage["CPU storage<br/>[cpu_storage.cpp]"]
  node_metal_storage["Metal storage<br/>[metal_storage.hpp]"]
  node_unified_storage["Unified storage"]
end

subgraph group_features["Library Features"]
  node_nn["Neural networks"]
  node_linalg["Linear algebra<br/>[linalg.cpp]"]
  node_io["Tensor I/O<br/>[io.cpp]"]
  node_parallel["Parallel execution<br/>[parallel.cpp]"]
end

node_user(("C++ caller"))

node_user -->|"creates and chains"| node_tensor
node_user -->|"loads or saves"| node_io
node_tensor -->|"invokes operations"| node_ops
node_ops -->|"creates lazy graphs"| node_graph_registry
node_graph_registry -->|"builds graph nodes"| node_graph_node
node_graph_registry -->|"uses compiled graphs"| node_compiled_graph
node_graph_registry -->|"uses executor"| node_graph_executor
node_graph_registry -->|"uses cache"| node_graph_cache
node_graph_compiler -->|"reads graph nodes"| node_graph_node
node_graph_compiler -->|"uses fusion patterns"| node_fusion
node_graph_executor -->|"executes graph nodes"| node_graph_node
node_graph_executor -->|"runs fused kernels"| node_fusion
node_graph_executor -->|"dispatches operations"| node_ops
node_ops -->|"dispatches CPU work"| node_cpu_ops
node_ops -->|"dispatches GPU work"| node_metal_ops
node_tensor -.->|"uses storage"| node_cpu_storage
node_tensor -.->|"uses storage"| node_metal_storage
node_metal_storage -.->|"offers unified memory"| node_unified_storage
node_tensor -->|"supports model APIs"| node_nn
node_tensor -->|"supports linear algebra"| node_linalg
node_tensor -->|"uses shape metadata"| node_shape
node_tensor -->|"uses dtype metadata"| node_dtype
node_ops -.->|"uses parallel runtime"| node_parallel

click node_tensor "https://github.com/frikallo/axiom/blob/main/include/axiom/tensor.hpp"
click node_ops "https://github.com/frikallo/axiom/blob/main/src/tensor/operations.cpp"
click node_shape "https://github.com/frikallo/axiom/blob/main/include/axiom/shape.hpp"
click node_dtype "https://github.com/frikallo/axiom/blob/main/include/axiom/dtype.hpp"
click node_graph_registry "https://github.com/frikallo/axiom/blob/main/src/graph/graph_registry.cpp"
click node_graph_node "https://github.com/frikallo/axiom/blob/main/include/axiom/graph/graph_node.hpp"
click node_graph_compiler "https://github.com/frikallo/axiom/blob/main/src/graph/graph_compiler.cpp"
click node_compiled_graph "https://github.com/frikallo/axiom/blob/main/include/axiom/graph/compiled_graph.hpp"
click node_graph_executor "https://github.com/frikallo/axiom/blob/main/src/graph/graph_executor.cpp"
click node_graph_cache "https://github.com/frikallo/axiom/blob/main/src/graph/graph_cache.cpp"
click node_fusion "https://github.com/frikallo/axiom/blob/main/src/graph/fused_kernel.cpp"
click node_cpu_ops "https://github.com/frikallo/axiom/blob/main/src/backends/cpu/cpu_operations.cpp"
click node_metal_ops "https://github.com/frikallo/axiom/blob/main/src/backends/metal/metal_operations.hpp"
click node_cpu_storage "https://github.com/frikallo/axiom/blob/main/src/backends/cpu/cpu_storage.cpp"
click node_metal_storage "https://github.com/frikallo/axiom/blob/main/src/backends/metal/metal_storage.hpp"
click node_unified_storage "https://github.com/frikallo/axiom/blob/main/src/backends/metal/unified_storage.hpp"
click node_nn "https://github.com/frikallo/axiom/tree/main/src/nn"
click node_linalg "https://github.com/frikallo/axiom/blob/main/src/tensor/linalg.cpp"
click node_io "https://github.com/frikallo/axiom/blob/main/src/io/io.cpp"
click node_parallel "https://github.com/frikallo/axiom/blob/main/src/parallel/parallel.cpp"

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,node_ops,node_shape,node_dtype toneBlue
class node_graph_registry,node_graph_node,node_graph_compiler,node_compiled_graph,node_graph_executor,node_graph_cache,node_fusion toneAmber
class node_cpu_ops,node_metal_ops,node_cpu_storage,node_metal_storage,node_unified_storage toneMint
class node_nn,node_linalg,node_io,node_parallel toneRose
class node_user toneIndigo
```

## Components

### Tensor API

- [Tensor API](https://github.com/frikallo/axiom/blob/main/include/axiom/tensor.hpp): `include/axiom/tensor.hpp`
- [Tensor operations](https://github.com/frikallo/axiom/blob/main/src/tensor/operations.cpp): `src/tensor/operations.cpp`
- [Shape utilities](https://github.com/frikallo/axiom/blob/main/include/axiom/shape.hpp): `include/axiom/shape.hpp`
- [Data types](https://github.com/frikallo/axiom/blob/main/include/axiom/dtype.hpp): `include/axiom/dtype.hpp`

### Lazy Compute

- [Graph registry](https://github.com/frikallo/axiom/blob/main/src/graph/graph_registry.cpp): `src/graph/graph_registry.cpp`
- [Graph nodes](https://github.com/frikallo/axiom/blob/main/include/axiom/graph/graph_node.hpp): `include/axiom/graph/graph_node.hpp`
- [Graph compiler](https://github.com/frikallo/axiom/blob/main/src/graph/graph_compiler.cpp): `src/graph/graph_compiler.cpp`
- [Compiled graph](https://github.com/frikallo/axiom/blob/main/include/axiom/graph/compiled_graph.hpp): `include/axiom/graph/compiled_graph.hpp`
- [Graph executor](https://github.com/frikallo/axiom/blob/main/src/graph/graph_executor.cpp): `src/graph/graph_executor.cpp`
- [Graph cache](https://github.com/frikallo/axiom/blob/main/src/graph/graph_cache.cpp): `src/graph/graph_cache.cpp`
- [Kernel fusion](https://github.com/frikallo/axiom/blob/main/src/graph/fused_kernel.cpp): `src/graph/fused_kernel.cpp`

### Devices & Storage

- [CPU operations](https://github.com/frikallo/axiom/blob/main/src/backends/cpu/cpu_operations.cpp): `src/backends/cpu/cpu_operations.cpp`
- [Metal operations](https://github.com/frikallo/axiom/blob/main/src/backends/metal/metal_operations.hpp): `src/backends/metal/metal_operations.hpp`
- [CPU storage](https://github.com/frikallo/axiom/blob/main/src/backends/cpu/cpu_storage.cpp): `src/backends/cpu/cpu_storage.cpp`
- [Metal storage](https://github.com/frikallo/axiom/blob/main/src/backends/metal/metal_storage.hpp): `src/backends/metal/metal_storage.hpp`
- [Unified storage](https://github.com/frikallo/axiom/blob/main/src/backends/metal/unified_storage.hpp): `src/backends/metal/unified_storage.hpp`

### Library Features

- [Neural networks](https://github.com/frikallo/axiom/tree/main/src/nn): `src/nn`
- [Linear algebra](https://github.com/frikallo/axiom/blob/main/src/tensor/linalg.cpp): `src/tensor/linalg.cpp`
- [Tensor I/O](https://github.com/frikallo/axiom/blob/main/src/io/io.cpp): `src/io/io.cpp`
- [Parallel execution](https://github.com/frikallo/axiom/blob/main/src/parallel/parallel.cpp): `src/parallel/parallel.cpp`

### Other components

- **C++ caller**

## Connections

- C++ caller → Tensor API: creates and chains (evidence: `README.md`)
- C++ caller → Tensor I/O: loads or saves (evidence: `README.md`)
- Tensor API → Tensor operations: invokes operations (evidence: `README.md`)
- Tensor operations → Graph registry: creates lazy graphs (evidence: `src/tensor/operations.cpp`)
- Graph registry → Graph nodes: builds graph nodes
- Graph registry → Compiled graph: uses compiled graphs (evidence: `src/graph/graph_registry.cpp`)
- Graph registry → Graph executor: uses executor (evidence: `src/graph/graph_registry.cpp`)
- Graph registry → Graph cache: uses cache (evidence: `src/graph/graph_registry.cpp`)
- Graph compiler → Graph nodes: reads graph nodes (evidence: `src/graph/graph_compiler.cpp`)
- Graph compiler → Kernel fusion: uses fusion patterns (evidence: `src/graph/graph_compiler.cpp`)
- Graph executor → Graph nodes: executes graph nodes (evidence: `src/graph/graph_executor.cpp`)
- Graph executor → Kernel fusion: runs fused kernels (evidence: `src/graph/graph_executor.cpp`)
- Graph executor → Tensor operations: dispatches operations (evidence: `src/graph/graph_executor.cpp`)
- Tensor operations → CPU operations: dispatches CPU work (evidence: `src/tensor/operations.cpp`)
- Tensor operations → Metal operations: dispatches GPU work (evidence: `src/tensor/operations.cpp`)
- Tensor API → CPU storage: uses storage
- Tensor API → Metal storage: uses storage
- Metal storage → Unified storage: offers unified memory
- Tensor API → Neural networks: supports model APIs (evidence: `README.md`)
- Tensor API → Linear algebra: supports linear algebra (evidence: `README.md`)
- Tensor API → Shape utilities: uses shape metadata (evidence: `include/axiom/tensor.hpp`)
- Tensor API → Data types: uses dtype metadata (evidence: `include/axiom/tensor.hpp`)
- Tensor operations → Parallel execution: uses parallel runtime
