# dimitrijejankov/bbts architecture

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

- Interactive diagram: https://gitdiagram.com/dimitrijejankov/bbts
- Repository: https://github.com/dimitrijejankov/bbts

## Overview

BarbaTOS is a distributed tensor operating system. Its principal workflow starts with a client submitting tensor commands, which are compiled into node-specific work, coordinated across the cluster, and executed using registered tensor operations and storage. The tree also shows matrix-multiplication, feed-forward-network, and XLA-kernel applications. Relationships below are limited to those visible in sampled source, SOURCE INDEX references, or the README; some application internals and runtime wiring were not sampled.

Main entry points: [`main/ud_functions/udf_manager.h`](https://github.com/dimitrijejankov/bbts/blob/master/main/ud_functions/udf_manager.h) (Operation Registry), [`main/commands/command_runner.h`](https://github.com/dimitrijejankov/bbts/blob/master/main/commands/command_runner.h) (Command Runner), [`main/commands/two_layer_compiler.h`](https://github.com/dimitrijejankov/bbts/blob/master/main/commands/two_layer_compiler.h) (Two-Layer Compiler), [`applications/ffnn/generate_ffnn.cc`](https://github.com/dimitrijejankov/bbts/blob/master/applications/ffnn/generate_ffnn.cc) (Feed-Forward Workloads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Applications"]
  node_node_cli["Node CLI<br/>[node_cli.cc]"]
  node_matrix_apps["Matrix Workloads<br/>[generate_bmm.cc]"]
  node_ffnn_app["Feed-Forward Workloads<br/>[generate_ffnn.cc]"]
  node_xla_app["XLA Kernel App<br/>[main.cc]"]
end

subgraph group_planning["Command Planning"]
  node_parsed["Parsed Commands<br/>[parsed_command.h]"]
  node_compiler["Two-Layer Compiler"]
  node_commands["Execution Commands<br/>[command.h]"]
  node_runner["Command Runner<br/>[command_runner.h]"]
end

subgraph group_cluster["Cluster Execution"]
  node_station["Reservation Station"]
  node_handlers["Command Handlers"]
  node_coordinator["Coordinator<br/>[coordinator.cc]"]
  node_node["Compute Node<br/>[node.h]"]
  node_communicator["MPI Communication<br/>[communicator.h]"]
end

subgraph group_runtime["Tensor Runtime"]
  node_tensor["Tensor Model<br/>[tensor.h]"]
  node_factory["Tensor Factory<br/>[tensor_factory.h]"]
  node_udf_manager["Operation Registry<br/>[udf_manager.h]"]
  node_operations["Distributed Operations<br/>[reduce_op.h]"]
  node_storage["Storage Interface<br/>[storage.h]"]
  node_memory_store[("Memory Storage<br/>[memory_storage.h]")]
  node_nvme_store[("NVMe Storage<br/>[nvme_storage.h]")]
  node_gpu_scheduler["GPU Scheduler<br/>[scheduler.h]"]
  node_xla_base["XLA Kernel Base<br/>[xla_kernel_base.h]"]
end

node_user(("Client"))

node_user -.->|"submits commands"| node_node_cli
node_node_cli -->|"uses node"| node_node
node_node_cli -->|"uses factory"| node_factory
node_matrix_apps -->|"builds commands"| node_parsed
node_ffnn_app -->|"uses compiler"| node_compiler
node_ffnn_app -->|"uses command model"| node_parsed
node_ffnn_app -->|"uses tensors"| node_tensor
node_xla_app -->|"registers kernels"| node_udf_manager
node_xla_app -->|"uses base"| node_xla_base
node_parsed -.->|"compiled by"| node_compiler
node_compiler -->|"generates commands"| node_commands
node_compiler -.->|"plans tensor placement"| node_tensor
node_runner -->|"dispatches work"| node_station
node_runner -->|"uses registry"| node_udf_manager
node_runner -->|"uses communication"| node_communicator
node_station -->|"dispatches commands"| node_handlers
node_handlers -->|"handles commands"| node_commands
node_coordinator -.->|"coordinates nodes"| node_communicator
node_node -.->|"runs commands"| node_runner
node_operations -->|"communicates tensors"| node_communicator
node_operations -->|"accesses tensors"| node_storage
node_operations -->|"selects operation"| node_udf_manager
node_storage -->|"selects backend"| node_memory_store
node_storage -->|"selects backend"| node_nvme_store
node_factory -->|"creates tensors"| node_tensor
node_udf_manager -->|"resolves tensor types"| node_factory
node_udf_manager -->|"uses scheduler"| node_gpu_scheduler
node_xla_base -.->|"registered through"| node_udf_manager

click node_node_cli "https://github.com/dimitrijejankov/bbts/blob/master/applications/node/node_cli.cc"
click node_matrix_apps "https://github.com/dimitrijejankov/bbts/blob/master/applications/bmm/generate_bmm.cc"
click node_ffnn_app "https://github.com/dimitrijejankov/bbts/blob/master/applications/ffnn/generate_ffnn.cc"
click node_xla_app "https://github.com/dimitrijejankov/bbts/blob/master/applications/xla_kernel/main.cc"
click node_parsed "https://github.com/dimitrijejankov/bbts/blob/master/main/commands/parsed_command.h"
click node_compiler "https://github.com/dimitrijejankov/bbts/blob/master/main/commands/two_layer_compiler.h"
click node_commands "https://github.com/dimitrijejankov/bbts/blob/master/main/commands/command.h"
click node_runner "https://github.com/dimitrijejankov/bbts/blob/master/main/commands/command_runner.h"
click node_station "https://github.com/dimitrijejankov/bbts/blob/master/main/commands/reservation_station.h"
click node_handlers "https://github.com/dimitrijejankov/bbts/blob/master/main/commands/command_handlers/command_handler_apply.cc"
click node_coordinator "https://github.com/dimitrijejankov/bbts/blob/master/main/server/coordinator.cc"
click node_node "https://github.com/dimitrijejankov/bbts/blob/master/main/server/node.h"
click node_communicator "https://github.com/dimitrijejankov/bbts/blob/master/main/communication/communicator.h"
click node_tensor "https://github.com/dimitrijejankov/bbts/blob/master/main/tensor/tensor.h"
click node_factory "https://github.com/dimitrijejankov/bbts/blob/master/main/tensor/tensor_factory.h"
click node_udf_manager "https://github.com/dimitrijejankov/bbts/blob/master/main/ud_functions/udf_manager.h"
click node_operations "https://github.com/dimitrijejankov/bbts/blob/master/main/operations/reduce_op.h"
click node_storage "https://github.com/dimitrijejankov/bbts/blob/master/main/storage/storage.h"
click node_memory_store "https://github.com/dimitrijejankov/bbts/blob/master/main/storage/memory_storage.h"
click node_nvme_store "https://github.com/dimitrijejankov/bbts/blob/master/main/storage/nvme_storage.h"
click node_gpu_scheduler "https://github.com/dimitrijejankov/bbts/blob/master/main/gpu/scheduler.h"
click node_xla_base "https://github.com/dimitrijejankov/bbts/blob/master/main/ud_functions/xla_kernel_base.h"

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_node_cli,node_matrix_apps,node_ffnn_app,node_xla_app,node_user toneBlue
class node_parsed,node_compiler,node_commands,node_runner toneAmber
class node_station,node_handlers,node_coordinator,node_node,node_communicator toneMint
class node_tensor,node_factory,node_udf_manager,node_operations,node_storage,node_memory_store,node_nvme_store,node_gpu_scheduler,node_xla_base toneRose
```

## Components

### Client Applications

- [Node CLI](https://github.com/dimitrijejankov/bbts/blob/master/applications/node/node_cli.cc): `applications/node/node_cli.cc`
- [Matrix Workloads](https://github.com/dimitrijejankov/bbts/blob/master/applications/bmm/generate_bmm.cc): `applications/bmm/generate_bmm.cc`
- [Feed-Forward Workloads](https://github.com/dimitrijejankov/bbts/blob/master/applications/ffnn/generate_ffnn.cc): `applications/ffnn/generate_ffnn.cc`
- [XLA Kernel App](https://github.com/dimitrijejankov/bbts/blob/master/applications/xla_kernel/main.cc): `applications/xla_kernel/main.cc`

### Command Planning

- [Parsed Commands](https://github.com/dimitrijejankov/bbts/blob/master/main/commands/parsed_command.h): `main/commands/parsed_command.h`
- [Two-Layer Compiler](https://github.com/dimitrijejankov/bbts/blob/master/main/commands/two_layer_compiler.h): `main/commands/two_layer_compiler.h`
- [Execution Commands](https://github.com/dimitrijejankov/bbts/blob/master/main/commands/command.h): `main/commands/command.h`
- [Command Runner](https://github.com/dimitrijejankov/bbts/blob/master/main/commands/command_runner.h): `main/commands/command_runner.h`

### Cluster Execution

- [Reservation Station](https://github.com/dimitrijejankov/bbts/blob/master/main/commands/reservation_station.h): `main/commands/reservation_station.h`
- [Command Handlers](https://github.com/dimitrijejankov/bbts/blob/master/main/commands/command_handlers/command_handler_apply.cc): `main/commands/command_handlers/command_handler_apply.cc`
- [Coordinator](https://github.com/dimitrijejankov/bbts/blob/master/main/server/coordinator.cc): `main/server/coordinator.cc`
- [Compute Node](https://github.com/dimitrijejankov/bbts/blob/master/main/server/node.h): `main/server/node.h`
- [MPI Communication](https://github.com/dimitrijejankov/bbts/blob/master/main/communication/communicator.h): `main/communication/communicator.h`

### Tensor Runtime

- [Tensor Model](https://github.com/dimitrijejankov/bbts/blob/master/main/tensor/tensor.h): `main/tensor/tensor.h`
- [Tensor Factory](https://github.com/dimitrijejankov/bbts/blob/master/main/tensor/tensor_factory.h): `main/tensor/tensor_factory.h`
- [Operation Registry](https://github.com/dimitrijejankov/bbts/blob/master/main/ud_functions/udf_manager.h): `main/ud_functions/udf_manager.h`
- [Distributed Operations](https://github.com/dimitrijejankov/bbts/blob/master/main/operations/reduce_op.h): `main/operations/reduce_op.h`
- [Storage Interface](https://github.com/dimitrijejankov/bbts/blob/master/main/storage/storage.h): `main/storage/storage.h`
- [Memory Storage](https://github.com/dimitrijejankov/bbts/blob/master/main/storage/memory_storage.h): `main/storage/memory_storage.h`
- [NVMe Storage](https://github.com/dimitrijejankov/bbts/blob/master/main/storage/nvme_storage.h): `main/storage/nvme_storage.h`
- [GPU Scheduler](https://github.com/dimitrijejankov/bbts/blob/master/main/gpu/scheduler.h): `main/gpu/scheduler.h`
- [XLA Kernel Base](https://github.com/dimitrijejankov/bbts/blob/master/main/ud_functions/xla_kernel_base.h): `main/ud_functions/xla_kernel_base.h`

### Other components

- **Client**

## Connections

- Client → Node CLI: submits commands
- Node CLI → Compute Node: uses node (evidence: `applications/node/node_cli.cc`)
- Node CLI → Tensor Factory: uses factory (evidence: `applications/node/node_cli.cc`)
- Matrix Workloads → Parsed Commands: builds commands (evidence: `applications/bmm/generate_bmm.cc`)
- Feed-Forward Workloads → Two-Layer Compiler: uses compiler (evidence: `applications/ffnn/generate_ffnn.cc`)
- Feed-Forward Workloads → Parsed Commands: uses command model (evidence: `applications/ffnn/generate_ffnn.cc`)
- Feed-Forward Workloads → Tensor Model: uses tensors (evidence: `applications/ffnn/generate_ffnn.cc`)
- XLA Kernel App → Operation Registry: registers kernels (evidence: `applications/xla_kernel/main.cc`)
- XLA Kernel App → XLA Kernel Base: uses base (evidence: `applications/xla_kernel/main.cc`)
- Parsed Commands → Two-Layer Compiler: compiled by
- Two-Layer Compiler → Execution Commands: generates commands (evidence: `main/commands/two_layer_compiler.h`)
- Two-Layer Compiler → Tensor Model: plans tensor placement
- Command Runner → Reservation Station: dispatches work (evidence: `main/commands/command_runner.h`)
- Command Runner → Operation Registry: uses registry (evidence: `main/commands/command_runner.h`)
- Command Runner → MPI Communication: uses communication (evidence: `main/commands/command_runner.h`)
- Reservation Station → Command Handlers: dispatches commands (evidence: `main/commands/reservation_station.h`)
- Command Handlers → Execution Commands: handles commands (evidence: `main/commands/command_handlers/command_handler_apply.cc`)
- Coordinator → MPI Communication: coordinates nodes
- Compute Node → Command Runner: runs commands
- Distributed Operations → MPI Communication: communicates tensors (evidence: `main/operations/reduce_op.h`)
- Distributed Operations → Storage Interface: accesses tensors (evidence: `main/operations/reduce_op.h`)
- Distributed Operations → Operation Registry: selects operation (evidence: `main/operations/reduce_op.h`)
- Storage Interface → Memory Storage: selects backend (evidence: `main/storage/storage.h`)
- Storage Interface → NVMe Storage: selects backend (evidence: `main/storage/storage.h`)
- Tensor Factory → Tensor Model: creates tensors (evidence: `main/tensor/tensor_factory.h`)
- Operation Registry → Tensor Factory: resolves tensor types (evidence: `main/ud_functions/udf_manager.h`)
- Operation Registry → GPU Scheduler: uses scheduler (evidence: `main/ud_functions/udf_manager.h`)
- XLA Kernel Base → Operation Registry: registered through
