# slexisvn/mlfw architecture

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

- Interactive diagram: https://gitdiagram.com/slexisvn/mlfw
- Repository: https://github.com/slexisvn/mlfw

## Overview

MLFW is a TypeScript machine-learning framework with tensor operations, neural-network and training APIs, and a multi-target compiler/runtime; the tree also contains a native Tera compiler and a compiler visualizer. The main execution path is tensor work through graph and tensor-level compilation, backend code generation, and runtime execution. Eager/autograd, training/data, and higher-level ML utilities are distinct capabilities. README content was absent, and source excerpts were selective, so uncertain call wiring is omitted; paths for unsampled subsystems identify only their existing directories.

Main entry points: [`src/tensor/ops/ops.ts`](https://github.com/slexisvn/mlfw/blob/main/src/tensor/ops/ops.ts) (Tensor Operations), [`src/index.ts`](https://github.com/slexisvn/mlfw/blob/main/src/index.ts) (Public Entry), [`src/compiler/pipeline/graph_pipeline.ts`](https://github.com/slexisvn/mlfw/blob/main/src/compiler/pipeline/graph_pipeline.ts) (Graph Pipeline), [`src/compiler/pipeline/tir_pipeline.ts`](https://github.com/slexisvn/mlfw/blob/main/src/compiler/pipeline/tir_pipeline.ts) (TIR Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["ML APIs"]
  node_entry["Public Entry<br/>[index.ts]"]
  node_nn["Neural Networks<br/>[index.ts]"]
  node_ml["ML Utilities<br/>[index.ts]"]
end

subgraph group_tensor["Tensor Runtime"]
  node_tensor["Tensor Core<br/>[tensor.ts]"]
  node_storage[("Tensor Storage<br/>[storage.ts]")]
  node_ops["Tensor Operations<br/>[ops.ts]"]
  node_dispatch["Operator Dispatch<br/>[dispatcher.ts]"]
  node_autograd["Backward Engine<br/>[engine.ts]"]
end

subgraph group_compiler["Compiler"]
  node_tracing["Program Tracing<br/>[trace_core.ts]"]
  node_graphpipe["Graph Pipeline<br/>[graph_pipeline.ts]"]
  node_tirpipe["TIR Pipeline<br/>[tir_pipeline.ts]"]
  node_analysis["Compiler Analysis"]
  node_visualizer["Compiler Visualizer<br/>[App.tsx]"]
end

subgraph group_execution["Execution Backends"]
  node_codegen["Backend Codegen<br/>[pipeline.ts]"]
  node_runtime["Runtime Selection<br/>[runtime.ts]"]
  node_kernels["Device Kernels<br/>[host_ops.ts]"]
  node_terac["Tera Native Backend<br/>[Pipelines.cpp]"]
end

subgraph group_training["Training And ML"]
  node_data["Data Loading<br/>[index.ts]"]
  node_trainer["Trainer<br/>[trainer.ts]"]
  node_optim["Optimizers<br/>[index.ts]"]
end

node_user(("Framework User"))

node_user -->|"uses"| node_entry
node_entry -->|"exposes"| node_nn
node_entry -->|"exposes"| node_ml
node_user -->|"creates tensors"| node_tensor
node_nn -->|"uses operations"| node_ops
node_ml -->|"uses operations"| node_ops
node_tensor -->|"owns storage"| node_storage
node_ops -->|"dispatches operators"| node_dispatch
node_autograd -->|"computes gradients"| node_ops
node_user -->|"traces programs"| node_tracing
node_tracing -->|"builds graph IR"| node_graphpipe
node_graphpipe -->|"lowers IR"| node_tirpipe
node_graphpipe -->|"queries analyses"| node_analysis
node_tirpipe -->|"uses analyses"| node_analysis
node_tirpipe -->|"produces functions"| node_codegen
node_codegen -->|"provides kernels"| node_runtime
node_runtime -->|"selects implementations"| node_kernels
node_codegen -.->|"optional native path"| node_terac
node_user -->|"loads batches"| node_data
node_data -->|"supplies data"| node_trainer
node_trainer -->|"runs modules"| node_nn
node_trainer -->|"updates parameters"| node_optim
node_user -->|"inspects compilation"| node_visualizer

click node_entry "https://github.com/slexisvn/mlfw/blob/main/src/index.ts"
click node_nn "https://github.com/slexisvn/mlfw/blob/main/src/nn/index.ts"
click node_ml "https://github.com/slexisvn/mlfw/blob/main/src/ml/index.ts"
click node_data "https://github.com/slexisvn/mlfw/blob/main/src/data/index.ts"
click node_trainer "https://github.com/slexisvn/mlfw/blob/main/src/lightning/core/trainer.ts"
click node_optim "https://github.com/slexisvn/mlfw/blob/main/src/optim/index.ts"
click node_tensor "https://github.com/slexisvn/mlfw/blob/main/src/tensor/core/tensor.ts"
click node_storage "https://github.com/slexisvn/mlfw/blob/main/src/tensor/core/storage.ts"
click node_ops "https://github.com/slexisvn/mlfw/blob/main/src/tensor/ops/ops.ts"
click node_dispatch "https://github.com/slexisvn/mlfw/blob/main/src/dispatcher/dispatcher.ts"
click node_autograd "https://github.com/slexisvn/mlfw/blob/main/src/autograd/engine.ts"
click node_tracing "https://github.com/slexisvn/mlfw/blob/main/src/tracing/trace_core.ts"
click node_graphpipe "https://github.com/slexisvn/mlfw/blob/main/src/compiler/pipeline/graph_pipeline.ts"
click node_tirpipe "https://github.com/slexisvn/mlfw/blob/main/src/compiler/pipeline/tir_pipeline.ts"
click node_analysis "https://github.com/slexisvn/mlfw/blob/main/src/compiler/analysis/analysis_manager.ts"
click node_codegen "https://github.com/slexisvn/mlfw/blob/main/src/backend/pipeline.ts"
click node_runtime "https://github.com/slexisvn/mlfw/blob/main/src/runtime/runtime.ts"
click node_kernels "https://github.com/slexisvn/mlfw/blob/main/src/kernels/defs/host_ops.ts"
click node_terac "https://github.com/slexisvn/mlfw/blob/main/terac/lib/Tera/Pipelines/Pipelines.cpp"
click node_visualizer "https://github.com/slexisvn/mlfw/blob/main/tools/visualizer/src/App.tsx"

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_entry,node_nn,node_ml,node_user toneBlue
class node_tensor,node_storage,node_ops,node_dispatch,node_autograd toneAmber
class node_tracing,node_graphpipe,node_tirpipe,node_analysis,node_visualizer toneMint
class node_codegen,node_runtime,node_kernels,node_terac toneRose
class node_data,node_trainer,node_optim toneIndigo
```

## Components

### ML APIs

- [Public Entry](https://github.com/slexisvn/mlfw/blob/main/src/index.ts): `src/index.ts`
- [Neural Networks](https://github.com/slexisvn/mlfw/blob/main/src/nn/index.ts): `src/nn/index.ts`
- [ML Utilities](https://github.com/slexisvn/mlfw/blob/main/src/ml/index.ts): `src/ml/index.ts`

### Tensor Runtime

- [Tensor Core](https://github.com/slexisvn/mlfw/blob/main/src/tensor/core/tensor.ts): `src/tensor/core/tensor.ts`
- [Tensor Storage](https://github.com/slexisvn/mlfw/blob/main/src/tensor/core/storage.ts): `src/tensor/core/storage.ts`
- [Tensor Operations](https://github.com/slexisvn/mlfw/blob/main/src/tensor/ops/ops.ts): `src/tensor/ops/ops.ts`
- [Operator Dispatch](https://github.com/slexisvn/mlfw/blob/main/src/dispatcher/dispatcher.ts): `src/dispatcher/dispatcher.ts`
- [Backward Engine](https://github.com/slexisvn/mlfw/blob/main/src/autograd/engine.ts): `src/autograd/engine.ts`

### Compiler

- [Program Tracing](https://github.com/slexisvn/mlfw/blob/main/src/tracing/trace_core.ts): `src/tracing/trace_core.ts`
- [Graph Pipeline](https://github.com/slexisvn/mlfw/blob/main/src/compiler/pipeline/graph_pipeline.ts): `src/compiler/pipeline/graph_pipeline.ts`
- [TIR Pipeline](https://github.com/slexisvn/mlfw/blob/main/src/compiler/pipeline/tir_pipeline.ts): `src/compiler/pipeline/tir_pipeline.ts`
- [Compiler Analysis](https://github.com/slexisvn/mlfw/blob/main/src/compiler/analysis/analysis_manager.ts): `src/compiler/analysis/analysis_manager.ts`
- [Compiler Visualizer](https://github.com/slexisvn/mlfw/blob/main/tools/visualizer/src/App.tsx): `tools/visualizer/src/App.tsx`

### Execution Backends

- [Backend Codegen](https://github.com/slexisvn/mlfw/blob/main/src/backend/pipeline.ts): `src/backend/pipeline.ts`
- [Runtime Selection](https://github.com/slexisvn/mlfw/blob/main/src/runtime/runtime.ts): `src/runtime/runtime.ts`
- [Device Kernels](https://github.com/slexisvn/mlfw/blob/main/src/kernels/defs/host_ops.ts): `src/kernels/defs/host_ops.ts`
- [Tera Native Backend](https://github.com/slexisvn/mlfw/blob/main/terac/lib/Tera/Pipelines/Pipelines.cpp): `terac/lib/Tera/Pipelines/Pipelines.cpp`

### Training And ML

- [Data Loading](https://github.com/slexisvn/mlfw/blob/main/src/data/index.ts): `src/data/index.ts`
- [Trainer](https://github.com/slexisvn/mlfw/blob/main/src/lightning/core/trainer.ts): `src/lightning/core/trainer.ts`
- [Optimizers](https://github.com/slexisvn/mlfw/blob/main/src/optim/index.ts): `src/optim/index.ts`

### Other components

- **Framework User**

## Connections

- Framework User → Public Entry: uses
- Public Entry → Neural Networks: exposes
- Public Entry → ML Utilities: exposes
- Framework User → Tensor Core: creates tensors
- Neural Networks → Tensor Operations: uses operations
- ML Utilities → Tensor Operations: uses operations
- Tensor Core → Tensor Storage: owns storage
- Tensor Operations → Operator Dispatch: dispatches operators
- Backward Engine → Tensor Operations: computes gradients
- Framework User → Program Tracing: traces programs
- Program Tracing → Graph Pipeline: builds graph IR
- Graph Pipeline → TIR Pipeline: lowers IR
- Graph Pipeline → Compiler Analysis: queries analyses
- TIR Pipeline → Compiler Analysis: uses analyses
- TIR Pipeline → Backend Codegen: produces functions
- Backend Codegen → Runtime Selection: provides kernels
- Runtime Selection → Device Kernels: selects implementations
- Backend Codegen → Tera Native Backend: optional native path
- Framework User → Data Loading: loads batches
- Data Loading → Trainer: supplies data
- Trainer → Neural Networks: runs modules
- Trainer → Optimizers: updates parameters
- Framework User → Compiler Visualizer: inspects compilation