# bibek198/computeedge architecture

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

- Interactive diagram: https://gitdiagram.com/bibek198/computeedge
- Repository: https://github.com/bibek198/computeedge

## Overview

ComputeEdge is an instrumented C++ tensor engine for measuring CPU–GPU execution costs on Apple Silicon. A client creates tensors, invokes matrix multiplication, and can run it through the CPU implementations or the Metal backend; instrumentation records allocations and execution events. The benchmark harness and documented comparisons measure performance and environment details. The README also identifies storage-mode and dispatch/synchronization characterization as planned work, not a completed dispatch subsystem. Several benchmark and Metal implementation files were not sampled, so those relationships are included only where documented.

Main entry points: [`src/cpu/matmul.cpp`](https://github.com/bibek198/computeedge/blob/main/src/cpu/matmul.cpp) (CPU matmul entry), [`include/computeedge/tensor.h`](https://github.com/bibek198/computeedge/blob/main/include/computeedge/tensor.h) (Tensor API), [`src/benchmark/benchmark.cpp`](https://github.com/bibek198/computeedge/blob/main/src/benchmark/benchmark.cpp) (Benchmark runner), [`src/core/tensor.cpp`](https://github.com/bibek198/computeedge/blob/main/src/core/tensor.cpp) (Tensor storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tensor_core["Tensor core"]
  node_tensor_api["Tensor API<br/>[tensor.h]"]
  node_tensor_storage["Tensor storage<br/>[tensor.cpp]"]
  node_host_allocator["Host allocator<br/>[allocator.cpp]"]
  node_validation["Matmul validation<br/>[validate.cpp]"]
end

subgraph group_cpu_backend["CPU backend"]
  node_cpu_entry["CPU matmul entry<br/>[matmul.cpp]"]
  node_cpu_accelerate["Accelerate kernel"]
  node_cpu_naive["Naive kernel<br/>[matmul_naive.cpp]"]
end

subgraph group_metal_backend["Metal backend"]
  node_metal_api["Metal API<br/>[metal.h]"]
  node_metal_impl["Metal backend<br/>[metal_backend.mm]"]
  node_metal_kernel["Matmul shader<br/>[matmul.metal]"]
end

subgraph group_measurement["Measurement"]
  node_event_log[("Event log")]
  node_benchmark_runner["Benchmark runner<br/>[benchmark.cpp]"]
  node_benchmark_stats["Benchmark statistics<br/>[stats.cpp]"]
  node_environment["Environment recorder<br/>[env_recorder.mm]"]
  node_comparison_refs["MPS and MLX"]
end

node_client(("Library client"))

node_client -->|"uses"| node_tensor_api
node_tensor_api -->|"calls matmul"| node_cpu_entry
node_tensor_api -->|"calls matmul"| node_metal_api
node_tensor_api -->|"creates storage"| node_tensor_storage
node_tensor_storage -->|"allocates through"| node_host_allocator
node_host_allocator -->|"emits events"| node_event_log
node_cpu_entry -->|"validates with"| node_validation
node_cpu_entry -->|"dispatches to"| node_cpu_accelerate
node_cpu_entry -->|"dispatches to"| node_cpu_naive
node_cpu_entry -->|"emits events"| node_event_log
node_metal_api -->|"implemented by"| node_metal_impl
node_metal_impl -->|"runs shader"| node_metal_kernel
node_client -->|"runs benchmark"| node_benchmark_runner
node_benchmark_runner -.->|"reports statistics"| node_benchmark_stats
node_benchmark_runner -.->|"records environment"| node_environment
node_benchmark_runner -->|"compares against"| node_comparison_refs

click node_tensor_api "https://github.com/bibek198/computeedge/blob/main/include/computeedge/tensor.h"
click node_tensor_storage "https://github.com/bibek198/computeedge/blob/main/src/core/tensor.cpp"
click node_host_allocator "https://github.com/bibek198/computeedge/blob/main/src/core/allocator.cpp"
click node_validation "https://github.com/bibek198/computeedge/blob/main/src/core/validate.cpp"
click node_event_log "https://github.com/bibek198/computeedge/blob/main/src/core/instrumentation.cpp"
click node_cpu_entry "https://github.com/bibek198/computeedge/blob/main/src/cpu/matmul.cpp"
click node_cpu_accelerate "https://github.com/bibek198/computeedge/blob/main/src/cpu/matmul_accelerate.cpp"
click node_cpu_naive "https://github.com/bibek198/computeedge/blob/main/src/cpu/matmul_naive.cpp"
click node_metal_api "https://github.com/bibek198/computeedge/blob/main/include/computeedge/metal.h"
click node_metal_impl "https://github.com/bibek198/computeedge/blob/main/src/metal/metal_backend.mm"
click node_metal_kernel "https://github.com/bibek198/computeedge/blob/main/src/metal/kernels/matmul.metal"
click node_benchmark_runner "https://github.com/bibek198/computeedge/blob/main/src/benchmark/benchmark.cpp"
click node_benchmark_stats "https://github.com/bibek198/computeedge/blob/main/src/benchmark/stats.cpp"
click node_environment "https://github.com/bibek198/computeedge/blob/main/src/benchmark/env_recorder.mm"
click node_comparison_refs "https://github.com/bibek198/computeedge/tree/main/benchmarks"

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_api,node_tensor_storage,node_host_allocator,node_validation,node_client toneBlue
class node_cpu_entry,node_cpu_accelerate,node_cpu_naive toneAmber
class node_metal_api,node_metal_impl,node_metal_kernel toneMint
class node_event_log,node_benchmark_runner,node_benchmark_stats,node_environment,node_comparison_refs toneRose
```

## Components

### Tensor core

- [Tensor API](https://github.com/bibek198/computeedge/blob/main/include/computeedge/tensor.h): `include/computeedge/tensor.h`
- [Tensor storage](https://github.com/bibek198/computeedge/blob/main/src/core/tensor.cpp): `src/core/tensor.cpp`
- [Host allocator](https://github.com/bibek198/computeedge/blob/main/src/core/allocator.cpp): `src/core/allocator.cpp`
- [Matmul validation](https://github.com/bibek198/computeedge/blob/main/src/core/validate.cpp): `src/core/validate.cpp`

### CPU backend

- [CPU matmul entry](https://github.com/bibek198/computeedge/blob/main/src/cpu/matmul.cpp): `src/cpu/matmul.cpp`
- [Accelerate kernel](https://github.com/bibek198/computeedge/blob/main/src/cpu/matmul_accelerate.cpp): `src/cpu/matmul_accelerate.cpp`
- [Naive kernel](https://github.com/bibek198/computeedge/blob/main/src/cpu/matmul_naive.cpp): `src/cpu/matmul_naive.cpp`

### Metal backend

- [Metal API](https://github.com/bibek198/computeedge/blob/main/include/computeedge/metal.h): `include/computeedge/metal.h`
- [Metal backend](https://github.com/bibek198/computeedge/blob/main/src/metal/metal_backend.mm): `src/metal/metal_backend.mm`
- [Matmul shader](https://github.com/bibek198/computeedge/blob/main/src/metal/kernels/matmul.metal): `src/metal/kernels/matmul.metal`

### Measurement

- [Event log](https://github.com/bibek198/computeedge/blob/main/src/core/instrumentation.cpp): `src/core/instrumentation.cpp`
- [Benchmark runner](https://github.com/bibek198/computeedge/blob/main/src/benchmark/benchmark.cpp): `src/benchmark/benchmark.cpp`
- [Benchmark statistics](https://github.com/bibek198/computeedge/blob/main/src/benchmark/stats.cpp): `src/benchmark/stats.cpp`
- [Environment recorder](https://github.com/bibek198/computeedge/blob/main/src/benchmark/env_recorder.mm): `src/benchmark/env_recorder.mm`
- [MPS and MLX](https://github.com/bibek198/computeedge/tree/main/benchmarks): `benchmarks`

### Other components

- **Library client**

## Connections

- Library client → Tensor API: uses (evidence: `README.md`)
- Tensor API → CPU matmul entry: calls matmul
- Tensor API → Metal API: calls matmul (evidence: `README.md`)
- Tensor API → Tensor storage: creates storage (evidence: `src/core/tensor.cpp`)
- Tensor storage → Host allocator: allocates through (evidence: `src/core/tensor.cpp`)
- Host allocator → Event log: emits events (evidence: `src/core/allocator.cpp`)
- CPU matmul entry → Matmul validation: validates with (evidence: `src/cpu/matmul.cpp`)
- CPU matmul entry → Accelerate kernel: dispatches to (evidence: `src/cpu/matmul.cpp`)
- CPU matmul entry → Naive kernel: dispatches to (evidence: `src/cpu/matmul.cpp`)
- CPU matmul entry → Event log: emits events (evidence: `src/cpu/matmul.cpp`)
- Metal API → Metal backend: implemented by (evidence: `README.md`)
- Metal backend → Matmul shader: runs shader
- Library client → Benchmark runner: runs benchmark (evidence: `README.md`)
- Benchmark runner → Benchmark statistics: reports statistics
- Benchmark runner → Environment recorder: records environment
- Benchmark runner → MPS and MLX: compares against (evidence: `README.md`)