# ersinkoc/phonebox architecture

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

- Interactive diagram: https://gitdiagram.com/ersinkoc/phonebox
- Repository: https://github.com/ersinkoc/phonebox

## Overview

PhoneBox pairs an Android desk panel with a Windows, Linux, or macOS agent. The phone connects over USB or Wi-Fi, and the agent serves panel data and actions while monitoring the computer and integrating with developer tools. The README also documents page/widget editing, rules, webhooks, Control Deck, and companion features; several of these implementations are not excerpted, so their internal wiring is not inferred. Edges are limited to relationships visible in excerpts, the source index, or README statements.

Main entry points: [`agent/PhoneBox.Agent/Program.cs`](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/Program.cs) (HTTP agent API), [`agent/PhoneBox.Agent/PushStore.cs`](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/PushStore.cs) (Webhooks and push data), [`android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt`](https://github.com/ersinkoc/phonebox/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt) (Android panel), [`agent/PhoneBox.Agent/SessionMonitor.cs`](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/SessionMonitor.cs) (AI sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_phone["Phone panel"]
  node_panel["Android panel<br/>[MainActivity.kt]"]
  node_link["Agent link<br/>[AgentLink.kt]"]
  node_stream["Live event stream<br/>[AgentStream.kt]"]
end

subgraph group_agent["Agent runtime"]
  node_runtime["HTTP agent API<br/>[Program.cs]"]
  node_endpoint["Agent endpoint<br/>[AgentEndpoint.cs]"]
  node_adb["USB routing<br/>[AdbReverse.cs]"]
end

subgraph group_monitoring["Monitoring and integrations"]
  node_system["PC metrics<br/>[SystemMonitor.cs]"]
  node_calendar["Calendar monitor<br/>[CalendarMonitor.cs]"]
  node_sessions["AI sessions<br/>[SessionMonitor.cs]"]
  node_quotas["AI quotas<br/>[QuotaMonitor.cs]"]
  node_codexbar["CodexBar provider<br/>[CodexBar.cs]"]
  node_github["GitHub activity<br/>[GitHubMonitor.cs]"]
  node_obs["OBS controls<br/>[ObsMonitor.cs]"]
end

subgraph group_interaction["Controls and automation"]
  node_media["Media controls<br/>[SpotifyControl.cs]"]
  node_deck["Control Deck<br/>[ControlDeck.cs]"]
  node_shortcuts["PC shortcuts<br/>[Shortcuts.cs]"]
  node_rules["Automation rules<br/>[RuleEngine.cs]"]
end

subgraph group_state["Configuration and state"]
  node_push[("Webhooks and push data<br/>[PushStore.cs]")]
  node_config[("Agent configuration<br/>[Config.cs]")]
  node_paths["Private file paths<br/>[AppPaths.cs]"]
end

node_user(("PhoneBox user"))
node_codex(("Codex CLI data"))
node_claude(("Claude Code data"))
node_github_service(("GitHub"))

node_user -->|"uses"| node_panel
node_panel -->|"requests data"| node_link
node_panel -->|"opens stream"| node_stream
node_link -->|"forwards requests"| node_runtime
node_stream -->|"opens stream"| node_link
node_runtime -->|"uses port"| node_endpoint
node_runtime -->|"serves metrics"| node_system
node_runtime -->|"serves calendar"| node_calendar
node_runtime -->|"serves sessions"| node_sessions
node_runtime -->|"serves quotas"| node_quotas
node_runtime -->|"serves activity"| node_github
node_runtime -->|"serves controls"| node_obs
node_runtime -->|"routes controls"| node_deck
node_runtime -->|"routes media actions"| node_media
node_runtime -->|"serves pushed data"| node_push
node_runtime -->|"reads and saves"| node_config
node_quotas -->|"reads provider data"| node_codexbar
node_sessions -->|"reads session files"| node_codex
node_sessions -->|"reads session files"| node_claude
node_github -.->|"checks activity"| node_github_service
node_rules -->|"emits or removes"| node_push
node_rules -->|"runs actions"| node_shortcuts
node_deck -->|"runs shortcuts"| node_shortcuts
node_push -->|"persists data"| node_paths
node_adb -->|"configures routing"| node_endpoint
node_user -.->|"configures widgets"| node_deck
node_user -.->|"configures rules"| node_rules
node_user -.->|"pushes values"| node_push

click node_panel "https://github.com/ersinkoc/phonebox/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt"
click node_link "https://github.com/ersinkoc/phonebox/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentLink.kt"
click node_stream "https://github.com/ersinkoc/phonebox/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentStream.kt"
click node_runtime "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/Program.cs"
click node_endpoint "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/AgentEndpoint.cs"
click node_system "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/SystemMonitor.cs"
click node_calendar "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/CalendarMonitor.cs"
click node_sessions "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/SessionMonitor.cs"
click node_quotas "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/QuotaMonitor.cs"
click node_codexbar "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/CodexBar.cs"
click node_github "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/GitHubMonitor.cs"
click node_obs "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/ObsMonitor.cs"
click node_media "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/SpotifyControl.cs"
click node_deck "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/ControlDeck.cs"
click node_shortcuts "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/Shortcuts.cs"
click node_rules "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/RuleEngine.cs"
click node_push "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/PushStore.cs"
click node_config "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/Config.cs"
click node_paths "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/AppPaths.cs"
click node_adb "https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/AdbReverse.cs"

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_panel,node_link,node_stream,node_user toneBlue
class node_runtime,node_endpoint,node_adb toneAmber
class node_system,node_calendar,node_sessions,node_quotas,node_codexbar,node_github,node_obs toneMint
class node_media,node_deck,node_shortcuts,node_rules toneRose
class node_push,node_config,node_paths,node_codex,node_claude,node_github_service toneIndigo
```

## Components

### Phone panel

- [Android panel](https://github.com/ersinkoc/phonebox/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt): `android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt`
- [Agent link](https://github.com/ersinkoc/phonebox/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentLink.kt): `android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentLink.kt`
- [Live event stream](https://github.com/ersinkoc/phonebox/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentStream.kt): `android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentStream.kt`

### Agent runtime

- [HTTP agent API](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/Program.cs): `agent/PhoneBox.Agent/Program.cs`
- [Agent endpoint](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/AgentEndpoint.cs): `agent/PhoneBox.Agent/AgentEndpoint.cs`
- [USB routing](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/AdbReverse.cs): `agent/PhoneBox.Agent/AdbReverse.cs`

### Monitoring and integrations

- [PC metrics](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/SystemMonitor.cs): `agent/PhoneBox.Agent/SystemMonitor.cs`
- [Calendar monitor](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/CalendarMonitor.cs): `agent/PhoneBox.Agent/CalendarMonitor.cs`
- [AI sessions](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/SessionMonitor.cs): `agent/PhoneBox.Agent/SessionMonitor.cs`
- [AI quotas](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/QuotaMonitor.cs): `agent/PhoneBox.Agent/QuotaMonitor.cs`
- [CodexBar provider](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/CodexBar.cs): `agent/PhoneBox.Agent/CodexBar.cs`
- [GitHub activity](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/GitHubMonitor.cs): `agent/PhoneBox.Agent/GitHubMonitor.cs`
- [OBS controls](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/ObsMonitor.cs): `agent/PhoneBox.Agent/ObsMonitor.cs`

### Controls and automation

- [Media controls](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/SpotifyControl.cs): `agent/PhoneBox.Agent/SpotifyControl.cs`
- [Control Deck](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/ControlDeck.cs): `agent/PhoneBox.Agent/ControlDeck.cs`
- [PC shortcuts](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/Shortcuts.cs): `agent/PhoneBox.Agent/Shortcuts.cs`
- [Automation rules](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/RuleEngine.cs): `agent/PhoneBox.Agent/RuleEngine.cs`

### Configuration and state

- [Webhooks and push data](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/PushStore.cs): `agent/PhoneBox.Agent/PushStore.cs`
- [Agent configuration](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/Config.cs): `agent/PhoneBox.Agent/Config.cs`
- [Private file paths](https://github.com/ersinkoc/phonebox/blob/main/agent/PhoneBox.Agent/AppPaths.cs): `agent/PhoneBox.Agent/AppPaths.cs`

### Other components

- **PhoneBox user**
- **Codex CLI data**
- **Claude Code data**
- **GitHub**

## Connections

- PhoneBox user → Android panel: uses
- Android panel → Agent link: requests data (evidence: `android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt`)
- Android panel → Live event stream: opens stream (evidence: `android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt`)
- Agent link → HTTP agent API: forwards requests (evidence: `android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentLink.kt`)
- Live event stream → Agent link: opens stream (evidence: `android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentStream.kt`)
- HTTP agent API → Agent endpoint: uses port (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → PC metrics: serves metrics (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → Calendar monitor: serves calendar (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → AI sessions: serves sessions (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → AI quotas: serves quotas (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → GitHub activity: serves activity (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → OBS controls: serves controls (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → Control Deck: routes controls (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → Media controls: routes media actions (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → Webhooks and push data: serves pushed data (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent API → Agent configuration: reads and saves (evidence: `agent/PhoneBox.Agent/Program.cs`)
- AI quotas → CodexBar provider: reads provider data (evidence: `agent/PhoneBox.Agent/QuotaMonitor.cs`)
- AI sessions → Codex CLI data: reads session files
- AI sessions → Claude Code data: reads session files (evidence: `agent/PhoneBox.Agent/SessionMonitor.cs`)
- GitHub activity → GitHub: checks activity
- Automation rules → Webhooks and push data: emits or removes (evidence: `agent/PhoneBox.Agent/RuleEngine.cs`)
- Automation rules → PC shortcuts: runs actions (evidence: `agent/PhoneBox.Agent/RuleEngine.cs`)
- Control Deck → PC shortcuts: runs shortcuts (evidence: `agent/PhoneBox.Agent/ControlDeck.cs`)
- Webhooks and push data → Private file paths: persists data (evidence: `agent/PhoneBox.Agent/PushStore.cs`)
- USB routing → Agent endpoint: configures routing (evidence: `agent/PhoneBox.Agent/AdbReverse.cs`)
- PhoneBox user → Control Deck: configures widgets
- PhoneBox user → Automation rules: configures rules
- PhoneBox user → Webhooks and push data: pushes values