# staylamebro/backburner architecture

> Architecture diagram of the GitHub repository staylamebro/backburner, 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/staylamebro/backburner
- Repository: https://github.com/staylamebro/backburner

## Overview

Backburner splits local llama.cpp inference between a Mac and an iPhone: the Mac serves the model while the phone accelerates prefill and stores older KV context for attention. The primary workflow is to connect and configure the phone, establish a protected RPC path, then let the inference engine dispatch work and combine results. The graph also preserves the documented Wi-Fi tunnel and optional Neural Engine attention path. Engine internals and some RPC wiring are unsampled, so those links are shown only where README or excerpts establish them.

Main entry points: [`llama.cpp`](https://github.com/staylamebro/backburner/blob/main/llama.cpp) (Mac inference), [`ios/Backburner/Sidecar/ContentView.swift`](https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/ContentView.swift) (Sidecar UI), [`ios/Backburner/Sidecar/WifiTunnel.swift`](https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/WifiTunnel.swift) (Wi-Fi listener), [`phone-attn/phone-attn.h`](https://github.com/staylamebro/backburner/blob/main/phone-attn/phone-attn.h) (Attention server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Phone app"]
  node_sidecar_ui["Sidecar UI<br/>[ContentView.swift]"]
  node_rpc_bridge["RPC bridge<br/>[RPCBridge.mm]"]
end

subgraph group_transport["Phone connectivity"]
  node_cable_gate["Cable gate<br/>[CableOnly.h]"]
  node_wifi_listener["Wi-Fi listener<br/>[WifiTunnel.swift]"]
  node_noise_channel["Noise channel<br/>[Tunnel.swift]"]
  node_mac_tunnel["Mac tunnel<br/>[main.swift]"]
  node_wifi_phone["Phone server<br/>[WifiTunnel.swift]"]
end

subgraph group_inference["Inference engine"]
  node_mac_engine["Mac inference<br/>[llama.cpp]"]
  node_split_prefill["Split prefill<br/>[llama.cpp]"]
  node_spec_decode["DFlash2 decode<br/>[llama.cpp]"]
  node_prompt_cache[("Prompt cache<br/>[proxy.py]")]
end

subgraph group_attention["Phone attention"]
  node_kv_attention["Phone KV attention<br/>[phone-attn.h]"]
  node_pa_server["Attention server<br/>[phone-attn.h]"]
  node_pa_tool["Loopback server<br/>[pa-tool.cpp]"]
  node_ane_pages["ANE page engine<br/>[build.py]"]
end

node_user(("Operator"))
node_result["Generated output"]

node_user -->|"configures"| node_sidecar_ui
node_sidecar_ui -->|"starts RPC"| node_rpc_bridge
node_sidecar_ui -->|"starts paired tunnel"| node_wifi_listener
node_wifi_listener -->|"authenticates with"| node_noise_channel
node_wifi_listener -->|"forwards to loopback"| node_wifi_phone
node_mac_tunnel -->|"handshakes with"| node_noise_channel
node_mac_engine -.->|"dispatches layers"| node_split_prefill
node_mac_engine -.->|"requests old-key attention"| node_kv_attention
node_kv_attention -->|"serves attention protocol"| node_pa_server
node_pa_tool -->|"runs server"| node_pa_server
node_pa_server -.->|"optionally delegates pages"| node_ane_pages
node_mac_engine -.->|"uses decoding"| node_spec_decode
node_mac_engine -.->|"restores prompts"| node_prompt_cache
node_mac_engine -.->|"returns tokens"| node_result
node_wifi_phone -->|"protects server access"| node_cable_gate

click node_sidecar_ui "https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/ContentView.swift"
click node_rpc_bridge "https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/RPCBridge.mm"
click node_cable_gate "https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/CableOnly.h"
click node_wifi_listener "https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/WifiTunnel.swift"
click node_noise_channel "https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/Tunnel.swift"
click node_mac_tunnel "https://github.com/staylamebro/backburner/blob/main/tools/wifi-tunnel/main.swift"
click node_mac_engine "https://github.com/staylamebro/backburner/blob/main/llama.cpp"
click node_split_prefill "https://github.com/staylamebro/backburner/blob/main/llama.cpp"
click node_spec_decode "https://github.com/staylamebro/backburner/blob/main/llama.cpp"
click node_prompt_cache "https://github.com/staylamebro/backburner/blob/main/scripts/proxy.py"
click node_kv_attention "https://github.com/staylamebro/backburner/blob/main/phone-attn/phone-attn.h"
click node_pa_server "https://github.com/staylamebro/backburner/blob/main/phone-attn/phone-attn.h"
click node_pa_tool "https://github.com/staylamebro/backburner/blob/main/phone-attn/pa-tool.cpp"
click node_ane_pages "https://github.com/staylamebro/backburner/blob/main/phone-attn/ane-kv/build.py"
click node_wifi_phone "https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/WifiTunnel.swift"

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_sidecar_ui,node_rpc_bridge toneBlue
class node_cable_gate,node_wifi_listener,node_noise_channel,node_mac_tunnel,node_wifi_phone toneAmber
class node_mac_engine,node_split_prefill,node_spec_decode,node_prompt_cache toneMint
class node_kv_attention,node_pa_server,node_pa_tool,node_ane_pages toneRose
class node_user,node_result toneIndigo
```

## Components

### Phone app

- [Sidecar UI](https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/ContentView.swift): `ios/Backburner/Sidecar/ContentView.swift`
- [RPC bridge](https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/RPCBridge.mm): `ios/Backburner/Sidecar/RPCBridge.mm`

### Phone connectivity

- [Cable gate](https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/CableOnly.h): `ios/Backburner/Sidecar/CableOnly.h`
- [Wi-Fi listener](https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/WifiTunnel.swift): `ios/Backburner/Sidecar/WifiTunnel.swift`
- [Noise channel](https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/Tunnel.swift): `ios/Backburner/Sidecar/Tunnel.swift`
- [Mac tunnel](https://github.com/staylamebro/backburner/blob/main/tools/wifi-tunnel/main.swift): `tools/wifi-tunnel/main.swift`
- [Phone server](https://github.com/staylamebro/backburner/blob/main/ios/Backburner/Sidecar/WifiTunnel.swift): `ios/Backburner/Sidecar/WifiTunnel.swift`

### Inference engine

- [Mac inference](https://github.com/staylamebro/backburner/blob/main/llama.cpp): `llama.cpp`
- [Split prefill](https://github.com/staylamebro/backburner/blob/main/llama.cpp): `llama.cpp`
- [DFlash2 decode](https://github.com/staylamebro/backburner/blob/main/llama.cpp): `llama.cpp`
- [Prompt cache](https://github.com/staylamebro/backburner/blob/main/scripts/proxy.py): `scripts/proxy.py`

### Phone attention

- [Phone KV attention](https://github.com/staylamebro/backburner/blob/main/phone-attn/phone-attn.h): `phone-attn/phone-attn.h`
- [Attention server](https://github.com/staylamebro/backburner/blob/main/phone-attn/phone-attn.h): `phone-attn/phone-attn.h`
- [Loopback server](https://github.com/staylamebro/backburner/blob/main/phone-attn/pa-tool.cpp): `phone-attn/pa-tool.cpp`
- [ANE page engine](https://github.com/staylamebro/backburner/blob/main/phone-attn/ane-kv/build.py): `phone-attn/ane-kv/build.py`

### Other components

- **Operator**
- **Generated output**

## Connections

- Operator → Sidecar UI: configures (evidence: `ios/Backburner/Sidecar/ContentView.swift`)
- Sidecar UI → RPC bridge: starts RPC (evidence: `ios/Backburner/Sidecar/ContentView.swift`)
- Sidecar UI → Wi-Fi listener: starts paired tunnel (evidence: `ios/Backburner/Sidecar/ContentView.swift`)
- Wi-Fi listener → Noise channel: authenticates with (evidence: `ios/Backburner/Sidecar/WifiTunnel.swift`)
- Wi-Fi listener → Phone server: forwards to loopback (evidence: `ios/Backburner/Sidecar/WifiTunnel.swift`)
- Mac tunnel → Noise channel: handshakes with (evidence: `tools/wifi-tunnel/main.swift`)
- Mac inference → Split prefill: dispatches layers (evidence: `README.md`)
- Mac inference → Phone KV attention: requests old-key attention (evidence: `README.md`)
- Phone KV attention → Attention server: serves attention protocol (evidence: `phone-attn/phone-attn.h`)
- Loopback server → Attention server: runs server (evidence: `phone-attn/pa-tool.cpp`)
- Attention server → ANE page engine: optionally delegates pages (evidence: `phone-attn/phone-attn.h`)
- Mac inference → DFlash2 decode: uses decoding (evidence: `README.md`)
- Mac inference → Prompt cache: restores prompts (evidence: `README.md`)
- Mac inference → Generated output: returns tokens (evidence: `README.md`)
- Phone server → Cable gate: protects server access (evidence: `ios/Backburner/Sidecar/WifiTunnel.swift`)
