# hyperionaidev/smolmaxxing architecture

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

- Interactive diagram: https://gitdiagram.com/hyperionaidev/smolmaxxing
- Repository: https://github.com/hyperionaidev/smolmaxxing

## Overview

smolmaxxing is a low-memory LLM experimentation project: it prepares model files and demonstrates chat/inference on constrained devices, with device-specific kernels and performance probes. The README documents expert paging, dense-model flash streaming, and vocabulary-head pruning as major techniques, though their llama.cpp patch implementations are not in the supplied tree. The graph also captures the iPad chat and tiny story-model server, plus model-file tooling and hardware measurement. Relationships are limited to excerpted calls/import references or README statements; unsampled implementations are not treated as inspected.

Main entry points: [`tools/gguf_split_adb.py`](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_split_adb.py) (ADB GGUF splitter), [`ipad-air/smolchat.cpp`](https://github.com/hyperionaidev/smolmaxxing/blob/main/ipad-air/smolchat.cpp) (iPad chat), [`tiny-llm-web/server.c`](https://github.com/hyperionaidev/smolmaxxing/blob/main/tiny-llm-web/server.c) (Tiny LLM server), [`tools/gguf_remote.py`](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_remote.py) (Remote GGUF ranges)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Chat runtimes"]
  node_ipad_chat["iPad chat<br/>[smolchat.cpp]"]
  node_ipad_web["Safari chat server<br/>[web.h]"]
  node_tiny_server["Tiny LLM server<br/>[server.c]"]
  node_llama2_runtime["llama2.c inference<br/>[server.c]"]
end

subgraph group_models["Model preparation"]
  node_gguf_assemble["MoE assembler"]
  node_gguf_remote["Remote GGUF ranges<br/>[gguf_remote.py]"]
  node_gguf_recut["Head recutter<br/>[gguf_recut.c]"]
  node_gguf_split["ADB GGUF splitter<br/>[gguf_split_adb.py]"]
  node_range_reader["Range reader<br/>[rangecat.c]"]
  node_gguf_build["GGUF builder<br/>[gguf_build.py]"]
  node_vocab_select["Vocabulary selector<br/>[vocab_select.py]"]
end

subgraph group_device["Device techniques"]
  node_expert_paging["Expert paging"]
  node_flash_stream["Flash streaming"]
  node_vkgemv["Vulkan GEMV probe<br/>[vkgemv.c]"]
  node_gemv_shader["GEMV shader data<br/>[gemv.spv.h]"]
  node_vkprobe["Vulkan bandwidth probe<br/>[vkprobe.c]"]
  node_bandwidth_shader["Bandwidth shader data<br/>[bw.spv.h]"]
end

subgraph group_measurement["Hardware measurement"]
  node_kernel_bench["Kernel benchmarks<br/>[kbench_tq.c]"]
  node_ipad_bench["iPad device probes<br/>[kbench.c]"]
  node_membw_bench["Memory bandwidth probe<br/>[membw.c]"]
end

node_person(("Device user"))

node_person -->|"chats with"| node_ipad_chat
node_ipad_chat -->|"serves through"| node_ipad_web
node_person -->|"requests generation"| node_tiny_server
node_tiny_server -->|"invokes inference"| node_llama2_runtime
node_gguf_assemble -->|"fetches ranges"| node_gguf_remote
node_gguf_split -->|"uses range helpers"| node_gguf_remote
node_gguf_split -->|"reads device ranges"| node_range_reader
node_vkgemv -->|"loads shader data"| node_gemv_shader
node_vkprobe -->|"loads shader data"| node_bandwidth_shader
node_person -.->|"runs models with"| node_expert_paging
node_person -.->|"runs models with"| node_flash_stream

click node_ipad_chat "https://github.com/hyperionaidev/smolmaxxing/blob/main/ipad-air/smolchat.cpp"
click node_ipad_web "https://github.com/hyperionaidev/smolmaxxing/blob/main/ipad-air/web.h"
click node_tiny_server "https://github.com/hyperionaidev/smolmaxxing/blob/main/tiny-llm-web/server.c"
click node_llama2_runtime "https://github.com/hyperionaidev/smolmaxxing/blob/main/tiny-llm-web/server.c"
click node_gguf_assemble "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_moe_assemble.py"
click node_gguf_remote "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_remote.py"
click node_gguf_recut "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf-recut/gguf_recut.c"
click node_gguf_split "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_split_adb.py"
click node_range_reader "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/rangecat/rangecat.c"
click node_gguf_build "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_build.py"
click node_vocab_select "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vocab_select.py"
click node_expert_paging "https://github.com/hyperionaidev/smolmaxxing/tree/main/patches"
click node_flash_stream "https://github.com/hyperionaidev/smolmaxxing/tree/main/patches"
click node_vkgemv "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vkgemv/vkgemv.c"
click node_gemv_shader "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vkgemv/gemv.spv.h"
click node_vkprobe "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vkprobe/vkprobe.c"
click node_bandwidth_shader "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vkprobe/bw.spv.h"
click node_kernel_bench "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/kbench/kbench_tq.c"
click node_ipad_bench "https://github.com/hyperionaidev/smolmaxxing/blob/main/ipad-air/kbench.c"
click node_membw_bench "https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/membw/membw.c"

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_ipad_chat,node_ipad_web,node_tiny_server,node_llama2_runtime,node_person toneBlue
class node_gguf_assemble,node_gguf_remote,node_gguf_recut,node_gguf_split,node_range_reader,node_gguf_build,node_vocab_select toneAmber
class node_expert_paging,node_flash_stream,node_vkgemv,node_gemv_shader,node_vkprobe,node_bandwidth_shader toneMint
class node_kernel_bench,node_ipad_bench,node_membw_bench toneRose
```

## Components

### Chat runtimes

- [iPad chat](https://github.com/hyperionaidev/smolmaxxing/blob/main/ipad-air/smolchat.cpp): `ipad-air/smolchat.cpp`
- [Safari chat server](https://github.com/hyperionaidev/smolmaxxing/blob/main/ipad-air/web.h): `ipad-air/web.h`
- [Tiny LLM server](https://github.com/hyperionaidev/smolmaxxing/blob/main/tiny-llm-web/server.c): `tiny-llm-web/server.c`
- [llama2.c inference](https://github.com/hyperionaidev/smolmaxxing/blob/main/tiny-llm-web/server.c): `tiny-llm-web/server.c`

### Model preparation

- [MoE assembler](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_moe_assemble.py): `tools/gguf_moe_assemble.py`
- [Remote GGUF ranges](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_remote.py): `tools/gguf_remote.py`
- [Head recutter](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf-recut/gguf_recut.c): `tools/gguf-recut/gguf_recut.c`
- [ADB GGUF splitter](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_split_adb.py): `tools/gguf_split_adb.py`
- [Range reader](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/rangecat/rangecat.c): `tools/rangecat/rangecat.c`
- [GGUF builder](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/gguf_build.py): `tools/gguf_build.py`
- [Vocabulary selector](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vocab_select.py): `tools/vocab_select.py`

### Device techniques

- [Expert paging](https://github.com/hyperionaidev/smolmaxxing/tree/main/patches): `patches`
- [Flash streaming](https://github.com/hyperionaidev/smolmaxxing/tree/main/patches): `patches`
- [Vulkan GEMV probe](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vkgemv/vkgemv.c): `tools/vkgemv/vkgemv.c`
- [GEMV shader data](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vkgemv/gemv.spv.h): `tools/vkgemv/gemv.spv.h`
- [Vulkan bandwidth probe](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vkprobe/vkprobe.c): `tools/vkprobe/vkprobe.c`
- [Bandwidth shader data](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/vkprobe/bw.spv.h): `tools/vkprobe/bw.spv.h`

### Hardware measurement

- [Kernel benchmarks](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/kbench/kbench_tq.c): `tools/kbench/kbench_tq.c`
- [iPad device probes](https://github.com/hyperionaidev/smolmaxxing/blob/main/ipad-air/kbench.c): `ipad-air/kbench.c`
- [Memory bandwidth probe](https://github.com/hyperionaidev/smolmaxxing/blob/main/tools/membw/membw.c): `tools/membw/membw.c`

### Other components

- **Device user**

## Connections

- Device user → iPad chat: chats with (evidence: `ipad-air/smolchat.cpp`)
- iPad chat → Safari chat server: serves through (evidence: `ipad-air/smolchat.cpp`)
- Device user → Tiny LLM server: requests generation (evidence: `tiny-llm-web/server.c`)
- Tiny LLM server → llama2.c inference: invokes inference (evidence: `tiny-llm-web/server.c`)
- MoE assembler → Remote GGUF ranges: fetches ranges (evidence: `tools/gguf_moe_assemble.py`)
- ADB GGUF splitter → Remote GGUF ranges: uses range helpers (evidence: `tools/gguf_split_adb.py`)
- ADB GGUF splitter → Range reader: reads device ranges (evidence: `tools/gguf_split_adb.py`)
- Vulkan GEMV probe → GEMV shader data: loads shader data (evidence: `tools/vkgemv/vkgemv.c`)
- Vulkan bandwidth probe → Bandwidth shader data: loads shader data (evidence: `tools/vkprobe/vkprobe.c`)
- Device user → Expert paging: runs models with (evidence: `README.md`)
- Device user → Flash streaming: runs models with (evidence: `README.md`)
