# shawnpana/phone-harness architecture

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

- Interactive diagram: https://gitdiagram.com/shawnpana/phone-harness
- Repository: https://github.com/shawnpana/phone-harness

## Overview

Phone Harness lets an agent operate a physical iPhone through macOS iPhone Mirroring or an Android device over adb, with an optional rented cloud Android. The main workflow is a script sent to the CLI, which exposes helpers that dispatch platform-neutral operations to a backend; the backend captures the screen and sends input, then returns text or other results. Cloud session management and device configuration are separate supporting flows. Some source excerpts are partial, so the graph includes only documented or directly supported wiring.

Main entry points: [`src/phone_harness/transport.py`](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/transport.py) (Operation dispatch), [`src/phone_harness/ios.py`](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/ios.py) (iPhone backend), [`src/phone_harness/cloud.py`](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/cloud.py) (Cloud sessions), [`src/phone_harness/admin.py`](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/admin.py) (Diagnostics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_runtime["Agent runtime"]
  node_run["CLI runner<br/>[run.py]"]
  node_helpers["Phone helpers<br/>[helpers.py]"]
end

subgraph group_control_backends["Control backends"]
  node_transport["Operation dispatch<br/>[transport.py]"]
  node_ios["iPhone backend<br/>[ios.py]"]
  node_android["Android backend<br/>[android.py]"]
  node_mirror["Mirroring transport<br/>[mirror.py]"]
  node_background["Background control<br/>[background.py]"]
  node_ocr["Vision OCR<br/>[ocr.py]"]
end

subgraph group_device_provisioning["Device provisioning"]
  node_cloud["Cloud sessions<br/>[cloud.py]"]
end

subgraph group_support["Support services"]
  node_config["Configuration<br/>[config.py]"]
  node_admin["Diagnostics<br/>[admin.py]"]
  node_telemetry["Telemetry<br/>[telemetry.py]"]
end

node_agent(("Agent"))
node_phone(("Connected phone"))
node_cloud_service(("Phone Harness Cloud"))
node_adb(("ADB"))

node_agent -->|"runs scripts"| node_run
node_run -->|"loads helpers"| node_helpers
node_run -->|"records events"| node_telemetry
node_helpers -->|"sends operations"| node_transport
node_transport -->|"reads platform"| node_config
node_transport -.->|"checks attachment"| node_cloud
node_transport -->|"dispatches operations"| node_ios
node_transport -->|"dispatches operations"| node_android
node_ios -->|"uses transport"| node_mirror
node_ios -->|"selects control path"| node_background
node_ios -->|"recognizes captures"| node_ocr
node_mirror -->|"sends input, captures screen"| node_phone
node_background -->|"sends input, captures screen"| node_phone
node_android -->|"runs device commands"| node_adb
node_adb -->|"controls device"| node_phone
node_cloud -->|"manages sessions"| node_cloud_service
node_cloud -->|"connects rented phone"| node_adb
node_cloud -->|"reads and writes state"| node_config
node_admin -->|"checks settings"| node_config
node_admin -->|"checks readiness"| node_ios
node_admin -->|"checks readiness"| node_android

click node_run "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/run.py"
click node_helpers "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/helpers.py"
click node_transport "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/transport.py"
click node_ios "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/ios.py"
click node_android "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/android.py"
click node_mirror "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/mirror.py"
click node_background "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/background.py"
click node_ocr "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/ocr.py"
click node_config "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/config.py"
click node_admin "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/admin.py"
click node_telemetry "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/telemetry.py"
click node_cloud "https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/cloud.py"

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_run,node_helpers toneBlue
class node_transport,node_ios,node_android,node_mirror,node_background,node_ocr toneAmber
class node_cloud toneMint
class node_config,node_admin,node_telemetry toneRose
class node_agent,node_phone,node_cloud_service,node_adb toneIndigo
```

## Components

### Agent runtime

- [CLI runner](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/run.py): `src/phone_harness/run.py`
- [Phone helpers](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/helpers.py): `src/phone_harness/helpers.py`

### Control backends

- [Operation dispatch](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/transport.py): `src/phone_harness/transport.py`
- [iPhone backend](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/ios.py): `src/phone_harness/ios.py`
- [Android backend](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/android.py): `src/phone_harness/android.py`
- [Mirroring transport](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/mirror.py): `src/phone_harness/mirror.py`
- [Background control](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/background.py): `src/phone_harness/background.py`
- [Vision OCR](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/ocr.py): `src/phone_harness/ocr.py`

### Device provisioning

- [Cloud sessions](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/cloud.py): `src/phone_harness/cloud.py`

### Support services

- [Configuration](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/config.py): `src/phone_harness/config.py`
- [Diagnostics](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/admin.py): `src/phone_harness/admin.py`
- [Telemetry](https://github.com/shawnpana/phone-harness/blob/main/src/phone_harness/telemetry.py): `src/phone_harness/telemetry.py`

### Other components

- **Agent**
- **Connected phone**
- **Phone Harness Cloud**
- **ADB**

## Connections

- Agent → CLI runner: runs scripts
- CLI runner → Phone helpers: loads helpers
- CLI runner → Telemetry: records events
- Phone helpers → Operation dispatch: sends operations
- Operation dispatch → Configuration: reads platform
- Operation dispatch → Cloud sessions: checks attachment
- Operation dispatch → iPhone backend: dispatches operations
- Operation dispatch → Android backend: dispatches operations
- iPhone backend → Mirroring transport: uses transport
- iPhone backend → Background control: selects control path
- iPhone backend → Vision OCR: recognizes captures
- Mirroring transport → Connected phone: sends input, captures screen
- Background control → Connected phone: sends input, captures screen
- Android backend → ADB: runs device commands
- ADB → Connected phone: controls device
- Cloud sessions → Phone Harness Cloud: manages sessions
- Cloud sessions → ADB: connects rented phone
- Cloud sessions → Configuration: reads and writes state
- Diagnostics → Configuration: checks settings
- Diagnostics → iPhone backend: checks readiness
- Diagnostics → Android backend: checks readiness