# dzaczek/phoneborg architecture

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

- Interactive diagram: https://gitdiagram.com/dzaczek/phoneborg
- Repository: https://github.com/dzaczek/phoneborg

## Overview

PhoneBorg turns USB-connected Android phones—and optionally desktop inference engines—into a managed inference cluster behind compatible APIs. The main path provisions phones, has agents report inventory and health, plans model placement, and routes client requests with affinity and failover. The graph also preserves management, model catalog, external engines, usage, and observability capabilities. Source excerpts are partial; README statements support the product-level flows, while source-index references support only the listed module relationships.

Main entry points: [`controller/gateway/proxy.go`](https://github.com/dzaczek/phoneborg/blob/main/controller/gateway/proxy.go) (OpenAI gateway), [`controller/server.go`](https://github.com/dzaczek/phoneborg/blob/main/controller/server.go) (Controller HTTP server), [`node-agent/agent.go`](https://github.com/dzaczek/phoneborg/blob/main/node-agent/agent.go) (Phone agent), [`provisioner/provision.go`](https://github.com/dzaczek/phoneborg/blob/main/provisioner/provision.go) (ADB provisioning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provision["Provisioning and agents"]
  node_provisioner["ADB provisioning<br/>[provision.go]"]
  node_agent["Phone agent<br/>[agent.go]"]
  node_inventory["Device inventory<br/>[inventory.go]"]
  node_manager["Model manager<br/>[manager.go]"]
  node_runtime["Inference runtime<br/>[runtime.go]"]
end

subgraph group_control["Controller and placement"]
  node_controller["Controller HTTP server<br/>[server.go]"]
  node_registry[("Node registry<br/>[registry.go]")]
  node_catalog[("Model catalog<br/>[catalog.go]")]
  node_planner["Placement planner<br/>[planner.go]"]
  node_placement["Placement control<br/>[placement.go]"]
  node_pools[("Node pools<br/>[pools.go]")]
  node_proto["Wire protocol<br/>[v0.go]"]
  node_memplan["Memory sizing<br/>[memplan.go]"]
end

subgraph group_inference["Inference gateway"]
  node_gateway["OpenAI gateway<br/>[proxy.go]"]
  node_routing["Target selection<br/>[picker.go]"]
  node_auth["Gateway auth<br/>[auth.go]"]
  node_external["External node integration<br/>[external.go]"]
end

subgraph group_management["Management surfaces"]
  node_adminapi["Admin API<br/>[admin.go]"]
  node_pbctl["pbctl CLI<br/>[main.go]"]
  node_web["Web panel views"]
  node_uiapi["Panel API client<br/>[api.js]"]
  node_opencode["OpenCode bridge<br/>[opencode.go]"]
end

subgraph group_observability["Usage and observability"]
  node_usage[("Usage accounting<br/>[usage.go]")]
  node_metrics["Prometheus metrics<br/>[server.go]"]
end

node_client(("Inference clients"))
node_admin(("Operators"))
node_phones["Android phones"]
node_desktop["External engines"]
node_prometheus["Prometheus and Grafana"]

node_phones -->|"connects by USB"| node_provisioner
node_provisioner -->|"installs and starts"| node_agent
node_agent -->|"reports health"| node_controller
node_agent -->|"collects device data"| node_inventory
node_agent -->|"reconciles desired model"| node_manager
node_manager -->|"loads model into"| node_runtime
node_controller -->|"tracks nodes"| node_registry
node_controller -->|"serves catalog"| node_catalog
node_catalog -->|"triggers replanning"| node_planner
node_planner -->|"uses sizing"| node_memplan
node_controller -->|"registers routes"| node_gateway
node_gateway -->|"authenticates requests"| node_auth
node_gateway -->|"selects target"| node_routing
node_gateway -->|"routes to phones"| node_registry
node_gateway -->|"supports pool targets"| node_pools
node_gateway -->|"routes external nodes"| node_external
node_desktop -->|"registers as node"| node_external
node_admin -->|"manages cluster"| node_pbctl
node_pbctl -->|"calls admin API"| node_adminapi
node_admin -->|"uses panel"| node_web
node_web -->|"requests data through"| node_uiapi
node_uiapi -->|"calls admin endpoints"| node_adminapi
node_client -->|"sends inference requests"| node_gateway
node_admin -->|"configures subagents"| node_opencode
node_controller -->|"accounts usage"| node_usage
node_controller -->|"exports metrics"| node_metrics
node_metrics -->|"scraped by"| node_prometheus

click node_controller "https://github.com/dzaczek/phoneborg/blob/main/controller/server.go"
click node_registry "https://github.com/dzaczek/phoneborg/blob/main/controller/registry.go"
click node_catalog "https://github.com/dzaczek/phoneborg/blob/main/controller/models/catalog.go"
click node_planner "https://github.com/dzaczek/phoneborg/blob/main/controller/models/planner.go"
click node_placement "https://github.com/dzaczek/phoneborg/blob/main/controller/placement.go"
click node_pools "https://github.com/dzaczek/phoneborg/blob/main/controller/pools.go"
click node_gateway "https://github.com/dzaczek/phoneborg/blob/main/controller/gateway/proxy.go"
click node_routing "https://github.com/dzaczek/phoneborg/blob/main/controller/gateway/picker.go"
click node_auth "https://github.com/dzaczek/phoneborg/blob/main/controller/gateway/auth.go"
click node_external "https://github.com/dzaczek/phoneborg/blob/main/controller/external.go"
click node_provisioner "https://github.com/dzaczek/phoneborg/blob/main/provisioner/provision.go"
click node_agent "https://github.com/dzaczek/phoneborg/blob/main/node-agent/agent.go"
click node_inventory "https://github.com/dzaczek/phoneborg/blob/main/node-agent/inventory.go"
click node_manager "https://github.com/dzaczek/phoneborg/blob/main/node-agent/manager.go"
click node_runtime "https://github.com/dzaczek/phoneborg/blob/main/node-agent/runtime.go"
click node_proto "https://github.com/dzaczek/phoneborg/blob/main/proto/v0.go"
click node_memplan "https://github.com/dzaczek/phoneborg/blob/main/internal/memplan/memplan.go"
click node_adminapi "https://github.com/dzaczek/phoneborg/blob/main/controller/admin.go"
click node_pbctl "https://github.com/dzaczek/phoneborg/blob/main/controller/cmd/pbctl/main.go"
click node_web "https://github.com/dzaczek/phoneborg/tree/main/controller/ui/static/js/views"
click node_uiapi "https://github.com/dzaczek/phoneborg/blob/main/controller/ui/static/js/api.js"
click node_opencode "https://github.com/dzaczek/phoneborg/blob/main/controller/cmd/pbctl/opencode.go"
click node_usage "https://github.com/dzaczek/phoneborg/blob/main/controller/usage.go"
click node_metrics "https://github.com/dzaczek/phoneborg/blob/main/controller/server.go"

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_provisioner,node_agent,node_inventory,node_manager,node_runtime,node_client toneBlue
class node_controller,node_registry,node_catalog,node_planner,node_placement,node_pools,node_proto,node_memplan toneAmber
class node_gateway,node_routing,node_auth,node_external toneMint
class node_adminapi,node_pbctl,node_web,node_uiapi,node_opencode toneRose
class node_usage,node_metrics,node_admin,node_phones,node_desktop,node_prometheus toneIndigo
```

## Components

### Provisioning and agents

- [ADB provisioning](https://github.com/dzaczek/phoneborg/blob/main/provisioner/provision.go): `provisioner/provision.go`
- [Phone agent](https://github.com/dzaczek/phoneborg/blob/main/node-agent/agent.go): `node-agent/agent.go`
- [Device inventory](https://github.com/dzaczek/phoneborg/blob/main/node-agent/inventory.go): `node-agent/inventory.go`
- [Model manager](https://github.com/dzaczek/phoneborg/blob/main/node-agent/manager.go): `node-agent/manager.go`
- [Inference runtime](https://github.com/dzaczek/phoneborg/blob/main/node-agent/runtime.go): `node-agent/runtime.go`

### Controller and placement

- [Controller HTTP server](https://github.com/dzaczek/phoneborg/blob/main/controller/server.go): `controller/server.go`
- [Node registry](https://github.com/dzaczek/phoneborg/blob/main/controller/registry.go): `controller/registry.go`
- [Model catalog](https://github.com/dzaczek/phoneborg/blob/main/controller/models/catalog.go): `controller/models/catalog.go`
- [Placement planner](https://github.com/dzaczek/phoneborg/blob/main/controller/models/planner.go): `controller/models/planner.go`
- [Placement control](https://github.com/dzaczek/phoneborg/blob/main/controller/placement.go): `controller/placement.go`
- [Node pools](https://github.com/dzaczek/phoneborg/blob/main/controller/pools.go): `controller/pools.go`
- [Wire protocol](https://github.com/dzaczek/phoneborg/blob/main/proto/v0.go): `proto/v0.go`
- [Memory sizing](https://github.com/dzaczek/phoneborg/blob/main/internal/memplan/memplan.go): `internal/memplan/memplan.go`

### Inference gateway

- [OpenAI gateway](https://github.com/dzaczek/phoneborg/blob/main/controller/gateway/proxy.go): `controller/gateway/proxy.go`
- [Target selection](https://github.com/dzaczek/phoneborg/blob/main/controller/gateway/picker.go): `controller/gateway/picker.go`
- [Gateway auth](https://github.com/dzaczek/phoneborg/blob/main/controller/gateway/auth.go): `controller/gateway/auth.go`
- [External node integration](https://github.com/dzaczek/phoneborg/blob/main/controller/external.go): `controller/external.go`

### Management surfaces

- [Admin API](https://github.com/dzaczek/phoneborg/blob/main/controller/admin.go): `controller/admin.go`
- [pbctl CLI](https://github.com/dzaczek/phoneborg/blob/main/controller/cmd/pbctl/main.go): `controller/cmd/pbctl/main.go`
- [Web panel views](https://github.com/dzaczek/phoneborg/tree/main/controller/ui/static/js/views): `controller/ui/static/js/views`
- [Panel API client](https://github.com/dzaczek/phoneborg/blob/main/controller/ui/static/js/api.js): `controller/ui/static/js/api.js`
- [OpenCode bridge](https://github.com/dzaczek/phoneborg/blob/main/controller/cmd/pbctl/opencode.go): `controller/cmd/pbctl/opencode.go`

### Usage and observability

- [Usage accounting](https://github.com/dzaczek/phoneborg/blob/main/controller/usage.go): `controller/usage.go`
- [Prometheus metrics](https://github.com/dzaczek/phoneborg/blob/main/controller/server.go): `controller/server.go`

### Other components

- **Inference clients**
- **Operators**
- **Android phones**
- **External engines**
- **Prometheus and Grafana**

## Connections

- Android phones → ADB provisioning: connects by USB
- ADB provisioning → Phone agent: installs and starts
- Phone agent → Controller HTTP server: reports health
- Phone agent → Device inventory: collects device data
- Phone agent → Model manager: reconciles desired model (evidence: `node-agent/manager.go`)
- Model manager → Inference runtime: loads model into (evidence: `node-agent/manager.go`)
- Controller HTTP server → Node registry: tracks nodes
- Controller HTTP server → Model catalog: serves catalog (evidence: `controller/server.go`)
- Model catalog → Placement planner: triggers replanning
- Placement planner → Memory sizing: uses sizing (evidence: `controller/models/planner.go`)
- Controller HTTP server → OpenAI gateway: registers routes (evidence: `controller/server.go`)
- OpenAI gateway → Gateway auth: authenticates requests
- OpenAI gateway → Target selection: selects target
- OpenAI gateway → Node registry: routes to phones
- OpenAI gateway → Node pools: supports pool targets
- OpenAI gateway → External node integration: routes external nodes
- External engines → External node integration: registers as node
- Operators → pbctl CLI: manages cluster
- pbctl CLI → Admin API: calls admin API (evidence: `controller/cmd/pbctl/main.go`)
- Operators → Web panel views: uses panel
- Web panel views → Panel API client: requests data through (evidence: `controller/ui/static/js/app.js`)
- Panel API client → Admin API: calls admin endpoints (evidence: `controller/ui/static/js/api.js`)
- Inference clients → OpenAI gateway: sends inference requests
- Operators → OpenCode bridge: configures subagents
- Controller HTTP server → Usage accounting: accounts usage
- Controller HTTP server → Prometheus metrics: exports metrics (evidence: `controller/server.go`)
- Prometheus metrics → Prometheus and Grafana: scraped by
