# hkuds/phonecli architecture

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

## Overview

PhoneCLI compiles mobile-app navigation into callable commands, then routes requests through deterministic command replay before model-backed GUI handling for unfamiliar screens. Its broader product includes device control, bounded conversational memory, replaceable model backends, and Android task evaluation; the repository also contains model/data-training code. The README documents the main routing behavior, while sampled source confirms model calls, Android control, and evaluation mechanics. Several runtime modules were not sampled, so their connections are shown only where the README explicitly describes them.

Main entry points: [`phonecli/agent.py`](https://github.com/hkuds/phonecli/blob/main/phonecli/agent.py) (Agent orchestration), [`utils_mobile/and_controller.py`](https://github.com/hkuds/phonecli/blob/main/utils_mobile/and_controller.py) (Android controller), [`evaluation/task.py`](https://github.com/hkuds/phonecli/blob/main/evaluation/task.py) (Task execution), [`agent/model.py`](https://github.com/hkuds/phonecli/blob/main/agent/model.py) (Model adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_harness["Mobile Harness"]
  node_runner["Request runner<br/>[run.py]"]
  node_agent["Agent orchestration<br/>[agent.py]"]
  node_mapbuild["App-map crawler<br/>[build_map.py]"]
  node_appmap["Compiled app map<br/>[app_map.py]"]
  node_cli["Command interface<br/>[cli.py]"]
  node_controller["Android controller<br/>[and_controller.py]"]
  node_vision["GUI executor"]
  node_text["Text executor<br/>[text_executor.py]"]
  node_ui["UI parsing<br/>[xml_tool.py]"]
end

subgraph group_models["Models and Memory"]
  node_model["Model adapters<br/>[model.py]"]
  node_llmclient["LLM client<br/>[llm_client.py]"]
  node_memory[("Conversation memory<br/>[memory.py]")]
  node_usage["Token accounting<br/>[token_usage.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Evaluation runner<br/>[evaluation.py]"]
  node_task["Task execution<br/>[task.py]"]
  node_definitions["Task definitions<br/>[definition.py]"]
  node_judge["LLM judge<br/>[llm_evaluator.py]"]
end

subgraph group_training["Model Training"]
  node_data["Training data<br/>[data_maker.py]"]
  node_trainingcode["SFT and RL"]
end

node_user(("Mobile request"))
node_device["Mobile device"]

node_user -->|"submits request"| node_runner
node_runner -->|"routes request"| node_agent
node_mapbuild -->|"compiles navigation"| node_appmap
node_agent -->|"replays commands"| node_appmap
node_agent -->|"falls back"| node_vision
node_cli -.->|"issues device commands"| node_controller
node_vision -.->|"acts on device"| node_controller
node_text -->|"acts on device"| node_controller
node_controller -->|"controls"| node_device
node_controller -.->|"captures UI state"| node_ui
node_agent -.->|"requests model action"| node_model
node_model -.->|"calls completion"| node_llmclient
node_agent -.->|"uses context"| node_memory
node_model -->|"records usage"| node_usage
node_eval -.->|"runs tasks"| node_task
node_task -->|"loads task metrics"| node_definitions
node_task -->|"judges results"| node_judge
node_task -->|"reports tokens"| node_usage
node_data -.->|"feeds training"| node_trainingcode

click node_runner "https://github.com/hkuds/phonecli/blob/main/phonecli/run.py"
click node_agent "https://github.com/hkuds/phonecli/blob/main/phonecli/agent.py"
click node_mapbuild "https://github.com/hkuds/phonecli/blob/main/phonecli/build_map.py"
click node_appmap "https://github.com/hkuds/phonecli/blob/main/phonecli/app_map.py"
click node_cli "https://github.com/hkuds/phonecli/blob/main/phonecli/cli.py"
click node_controller "https://github.com/hkuds/phonecli/blob/main/utils_mobile/and_controller.py"
click node_vision "https://github.com/hkuds/phonecli/blob/main/page_executor/simple_vision_executor.py"
click node_text "https://github.com/hkuds/phonecli/blob/main/page_executor/text_executor.py"
click node_ui "https://github.com/hkuds/phonecli/blob/main/utils_mobile/xml_tool.py"
click node_model "https://github.com/hkuds/phonecli/blob/main/agent/model.py"
click node_llmclient "https://github.com/hkuds/phonecli/blob/main/phonecli/llm_client.py"
click node_memory "https://github.com/hkuds/phonecli/blob/main/phonecli/memory.py"
click node_usage "https://github.com/hkuds/phonecli/blob/main/phonecli/token_usage.py"
click node_eval "https://github.com/hkuds/phonecli/blob/main/evaluation/evaluation.py"
click node_task "https://github.com/hkuds/phonecli/blob/main/evaluation/task.py"
click node_definitions "https://github.com/hkuds/phonecli/blob/main/evaluation/definition.py"
click node_judge "https://github.com/hkuds/phonecli/blob/main/evaluation/tasks/llm_evaluator.py"
click node_data "https://github.com/hkuds/phonecli/blob/main/prepare_data/visual_model_data/data_maker.py"
click node_trainingcode "https://github.com/hkuds/phonecli/tree/main/model_training/R1-V/src/r1-v/src/open_r1"

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_runner,node_agent,node_mapbuild,node_appmap,node_cli,node_controller,node_vision,node_text,node_ui toneBlue
class node_model,node_llmclient,node_memory,node_usage toneAmber
class node_eval,node_task,node_definitions,node_judge,node_user toneMint
class node_data,node_trainingcode toneRose
class node_device toneIndigo
```

## Components

### Mobile Harness

- [Request runner](https://github.com/hkuds/phonecli/blob/main/phonecli/run.py): `phonecli/run.py`
- [Agent orchestration](https://github.com/hkuds/phonecli/blob/main/phonecli/agent.py): `phonecli/agent.py`
- [App-map crawler](https://github.com/hkuds/phonecli/blob/main/phonecli/build_map.py): `phonecli/build_map.py`
- [Compiled app map](https://github.com/hkuds/phonecli/blob/main/phonecli/app_map.py): `phonecli/app_map.py`
- [Command interface](https://github.com/hkuds/phonecli/blob/main/phonecli/cli.py): `phonecli/cli.py`
- [Android controller](https://github.com/hkuds/phonecli/blob/main/utils_mobile/and_controller.py): `utils_mobile/and_controller.py`
- [GUI executor](https://github.com/hkuds/phonecli/blob/main/page_executor/simple_vision_executor.py): `page_executor/simple_vision_executor.py`
- [Text executor](https://github.com/hkuds/phonecli/blob/main/page_executor/text_executor.py): `page_executor/text_executor.py`
- [UI parsing](https://github.com/hkuds/phonecli/blob/main/utils_mobile/xml_tool.py): `utils_mobile/xml_tool.py`

### Models and Memory

- [Model adapters](https://github.com/hkuds/phonecli/blob/main/agent/model.py): `agent/model.py`
- [LLM client](https://github.com/hkuds/phonecli/blob/main/phonecli/llm_client.py): `phonecli/llm_client.py`
- [Conversation memory](https://github.com/hkuds/phonecli/blob/main/phonecli/memory.py): `phonecli/memory.py`
- [Token accounting](https://github.com/hkuds/phonecli/blob/main/phonecli/token_usage.py): `phonecli/token_usage.py`

### Evaluation

- [Evaluation runner](https://github.com/hkuds/phonecli/blob/main/evaluation/evaluation.py): `evaluation/evaluation.py`
- [Task execution](https://github.com/hkuds/phonecli/blob/main/evaluation/task.py): `evaluation/task.py`
- [Task definitions](https://github.com/hkuds/phonecli/blob/main/evaluation/definition.py): `evaluation/definition.py`
- [LLM judge](https://github.com/hkuds/phonecli/blob/main/evaluation/tasks/llm_evaluator.py): `evaluation/tasks/llm_evaluator.py`

### Model Training

- [Training data](https://github.com/hkuds/phonecli/blob/main/prepare_data/visual_model_data/data_maker.py): `prepare_data/visual_model_data/data_maker.py`
- [SFT and RL](https://github.com/hkuds/phonecli/tree/main/model_training/R1-V/src/r1-v/src/open_r1): `model_training/R1-V/src/r1-v/src/open_r1`

### Other components

- **Mobile request**
- **Mobile device**

## Connections

- Mobile request → Request runner: submits request (evidence: `README.md`)
- Request runner → Agent orchestration: routes request (evidence: `README.md`)
- App-map crawler → Compiled app map: compiles navigation (evidence: `README.md`)
- Agent orchestration → Compiled app map: replays commands (evidence: `README.md`)
- Agent orchestration → GUI executor: falls back (evidence: `README.md`)
- Command interface → Android controller: issues device commands
- GUI executor → Android controller: acts on device
- Text executor → Android controller: acts on device (evidence: `page_executor/text_executor.py`)
- Android controller → Mobile device: controls (evidence: `utils_mobile/and_controller.py`)
- Android controller → UI parsing: captures UI state
- Agent orchestration → Model adapters: requests model action
- Model adapters → LLM client: calls completion
- Agent orchestration → Conversation memory: uses context (evidence: `README.md`)
- Model adapters → Token accounting: records usage (evidence: `agent/model.py`)
- Evaluation runner → Task execution: runs tasks
- Task execution → Task definitions: loads task metrics (evidence: `evaluation/task.py`)
- Task execution → LLM judge: judges results (evidence: `evaluation/tasks/clock/clock.py`)
- Task execution → Token accounting: reports tokens (evidence: `evaluation/task.py`)
- Training data → SFT and RL: feeds training