# sarveshsivasankaran/phonebox-ai architecture

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

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

## Overview

PhoneBox pairs an Android desk-panel app with a cross-platform desktop agent. Users pair a phone over USB or Wi-Fi, configure pages and widgets, then view computer, AI-session, media, and automation data or send touch-control actions. The agent also supports integrations such as Home Assistant, GitHub, OBS, and AI coding tools. The README describes the editor and widget breadth; sampled source shows selected agent services and Android wiring, so unsampled capability links are omitted rather than inferred.

Main entry points: [`agent/PhoneBox.Agent/Program.cs`](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/Program.cs) (HTTP agent), [`android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt`](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt) (Android panel), [`agent/PhoneBox.Agent/PushStore.cs`](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/PushStore.cs) (Push state), [`agent/PhoneBox.Agent/RuleEngine.cs`](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/RuleEngine.cs) (Rule engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["Phone connection"]
  node_android["Android panel<br/>[MainActivity.kt]"]
  node_link["Agent link<br/>[AgentLink.kt]"]
  node_stream["Event stream<br/>[AgentStream.kt]"]
end

subgraph group_agent["Agent services"]
  node_agententry["HTTP agent<br/>[Program.cs]"]
  node_config["Configuration<br/>[Config.cs]"]
  node_push[("Push state<br/>[PushStore.cs]")]
  node_updates["Updates<br/>[UpdateService.cs]"]
  node_paths["App paths<br/>[AppPaths.cs]"]
end

subgraph group_insights["Monitoring and AI"]
  node_system["PC monitoring<br/>[SystemMonitor.cs]"]
  node_calendar["Calendar<br/>[CalendarMonitor.cs]"]
  node_ping["Ping monitor<br/>[PingMonitor.cs]"]
  node_sessions["AI sessions<br/>[SessionMonitor.cs]"]
  node_quotas["AI quotas<br/>[QuotaMonitor.cs]"]
  node_github["GitHub activity<br/>[GitHubMonitor.cs]"]
  node_codexbar["CodexBar<br/>[CodexBar.cs]"]
end

subgraph group_controls["Controls and automation"]
  node_rules["Rule engine<br/>[RuleEngine.cs]"]
  node_shortcuts["Shortcuts<br/>[Shortcuts.cs]"]
  node_approvals["OpenCode approvals"]
  node_approvalstore[("Approval store<br/>[ApprovalStore.cs]")]
  node_controldeck["Control Deck<br/>[ControlDeck.cs]"]
  node_music["Media controls<br/>[SpotifyControl.cs]"]
  node_homeassistant["Home Assistant<br/>[HomeAssistant.cs]"]
end

node_user(("Phone user"))
node_integrations["External services"]

node_user -->|"uses"| node_android
node_android -->|"creates link"| node_link
node_android -->|"creates stream"| node_stream
node_android -->|"connects to"| node_agententry
node_agententry -->|"uses"| node_push
node_agententry -->|"uses"| node_system
node_agententry -->|"routes updates"| node_updates
node_push -->|"persists through"| node_paths
node_agententry -->|"reads settings"| node_config
node_quotas -->|"uses"| node_codexbar
node_github -->|"queries GitHub"| node_integrations
node_sessions -->|"uses"| node_github
node_rules -->|"writes events"| node_push
node_rules -->|"observes"| node_sessions
node_rules -->|"runs"| node_shortcuts
node_approvals -->|"uses"| node_approvalstore
node_approvals -.->|"notifies"| node_push
node_controldeck -.->|"controls OBS"| node_integrations
node_music -.->|"controls media"| node_integrations
node_homeassistant -.->|"connects"| node_integrations
node_calendar -.->|"serves data"| node_agententry
node_ping -.->|"serves data"| node_agententry

click node_android "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt"
click node_link "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentLink.kt"
click node_stream "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentStream.kt"
click node_agententry "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/Program.cs"
click node_config "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/Config.cs"
click node_push "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/PushStore.cs"
click node_updates "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/UpdateService.cs"
click node_paths "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/AppPaths.cs"
click node_system "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/SystemMonitor.cs"
click node_calendar "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/CalendarMonitor.cs"
click node_ping "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/PingMonitor.cs"
click node_sessions "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/SessionMonitor.cs"
click node_quotas "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/QuotaMonitor.cs"
click node_github "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/GitHubMonitor.cs"
click node_codexbar "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/CodexBar.cs"
click node_rules "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/RuleEngine.cs"
click node_shortcuts "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/Shortcuts.cs"
click node_approvals "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/OpenCodeApprovals.cs"
click node_approvalstore "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/ApprovalStore.cs"
click node_controldeck "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/ControlDeck.cs"
click node_music "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/SpotifyControl.cs"
click node_homeassistant "https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/HomeAssistant.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_android,node_link,node_stream,node_user toneBlue
class node_agententry,node_config,node_push,node_updates,node_paths toneAmber
class node_system,node_calendar,node_ping,node_sessions,node_quotas,node_github,node_codexbar toneMint
class node_rules,node_shortcuts,node_approvals,node_approvalstore,node_controldeck,node_music,node_homeassistant toneRose
class node_integrations toneIndigo
```

## Components

### Phone connection

- [Android panel](https://github.com/sarveshsivasankaran/phonebox-ai/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/sarveshsivasankaran/phonebox-ai/blob/main/android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentLink.kt): `android/app/src/main/java/net/oxog/phonebox/deskpanel/AgentLink.kt`
- [Event stream](https://github.com/sarveshsivasankaran/phonebox-ai/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 services

- [HTTP agent](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/Program.cs): `agent/PhoneBox.Agent/Program.cs`
- [Configuration](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/Config.cs): `agent/PhoneBox.Agent/Config.cs`
- [Push state](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/PushStore.cs): `agent/PhoneBox.Agent/PushStore.cs`
- [Updates](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/UpdateService.cs): `agent/PhoneBox.Agent/UpdateService.cs`
- [App paths](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/AppPaths.cs): `agent/PhoneBox.Agent/AppPaths.cs`

### Monitoring and AI

- [PC monitoring](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/SystemMonitor.cs): `agent/PhoneBox.Agent/SystemMonitor.cs`
- [Calendar](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/CalendarMonitor.cs): `agent/PhoneBox.Agent/CalendarMonitor.cs`
- [Ping monitor](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/PingMonitor.cs): `agent/PhoneBox.Agent/PingMonitor.cs`
- [AI sessions](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/SessionMonitor.cs): `agent/PhoneBox.Agent/SessionMonitor.cs`
- [AI quotas](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/QuotaMonitor.cs): `agent/PhoneBox.Agent/QuotaMonitor.cs`
- [GitHub activity](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/GitHubMonitor.cs): `agent/PhoneBox.Agent/GitHubMonitor.cs`
- [CodexBar](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/CodexBar.cs): `agent/PhoneBox.Agent/CodexBar.cs`

### Controls and automation

- [Rule engine](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/RuleEngine.cs): `agent/PhoneBox.Agent/RuleEngine.cs`
- [Shortcuts](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/Shortcuts.cs): `agent/PhoneBox.Agent/Shortcuts.cs`
- [OpenCode approvals](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/OpenCodeApprovals.cs): `agent/PhoneBox.Agent/OpenCodeApprovals.cs`
- [Approval store](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/ApprovalStore.cs): `agent/PhoneBox.Agent/ApprovalStore.cs`
- [Control Deck](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/ControlDeck.cs): `agent/PhoneBox.Agent/ControlDeck.cs`
- [Media controls](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/SpotifyControl.cs): `agent/PhoneBox.Agent/SpotifyControl.cs`
- [Home Assistant](https://github.com/sarveshsivasankaran/phonebox-ai/blob/main/agent/PhoneBox.Agent/HomeAssistant.cs): `agent/PhoneBox.Agent/HomeAssistant.cs`

### Other components

- **Phone user**
- **External services**

## Connections

- Phone user → Android panel: uses (evidence: `README.md`)
- Android panel → Agent link: creates link (evidence: `android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt`)
- Android panel → Event stream: creates stream (evidence: `android/app/src/main/java/net/oxog/phonebox/deskpanel/MainActivity.kt`)
- Android panel → HTTP agent: connects to (evidence: `README.md`)
- HTTP agent → Push state: uses (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent → PC monitoring: uses (evidence: `agent/PhoneBox.Agent/Program.cs`)
- HTTP agent → Updates: routes updates (evidence: `agent/PhoneBox.Agent/Program.cs`)
- Push state → App paths: persists through (evidence: `agent/PhoneBox.Agent/PushStore.cs`)
- HTTP agent → Configuration: reads settings (evidence: `agent/PhoneBox.Agent/Program.cs`)
- AI quotas → CodexBar: uses (evidence: `agent/PhoneBox.Agent/QuotaMonitor.cs`)
- GitHub activity → External services: queries GitHub (evidence: `README.md`)
- AI sessions → GitHub activity: uses (evidence: `agent/PhoneBox.Agent/SessionMonitor.cs`)
- Rule engine → Push state: writes events (evidence: `agent/PhoneBox.Agent/RuleEngine.cs`)
- Rule engine → AI sessions: observes (evidence: `agent/PhoneBox.Agent/RuleEngine.cs`)
- Rule engine → Shortcuts: runs (evidence: `agent/PhoneBox.Agent/RuleEngine.cs`)
- OpenCode approvals → Approval store: uses (evidence: `agent/PhoneBox.Agent/OpenCodeApprovals.cs`)
- OpenCode approvals → Push state: notifies
- Control Deck → External services: controls OBS (evidence: `README.md`)
- Media controls → External services: controls media (evidence: `README.md`)
- Home Assistant → External services: connects (evidence: `README.md`)
- Calendar → HTTP agent: serves data (evidence: `agent/PhoneBox.Agent/Program.cs`)
- Ping monitor → HTTP agent: serves data (evidence: `agent/PhoneBox.Agent/Program.cs`)
