# ghost-in-the-droid/android-agent architecture

> Architecture diagram of the GitHub repository ghost-in-the-droid/android-agent, 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/ghost-in-the-droid/android-agent
- Repository: https://github.com/ghost-in-the-droid/android-agent

## Overview

Ghost in the Droid is a cross-platform mobile automation framework: an agent or dashboard sends commands, the backend interprets device state and executes actions on Android or iOS, and skills and scheduled jobs package those actions into reusable workflows. The map also includes documented streaming, skill creation and discovery, emulator, and on-device inference capabilities. Source excerpts establish core device, API, and scheduling links; broader feature links are cited to the README, so unsampled internals are not expanded.

Main entry points: [`gitd/bots/common/device.py`](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/bots/common/device.py) (Platform Device Factory), [`gitd/routers/phone.py`](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/phone.py) (Phone Routes), [`gitd/app.py`](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/app.py) (FastAPI App), [`gitd/services/job_engine.py`](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/job_engine.py) (Job Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent Interfaces"]
  node_dashboard["Web Dashboard<br/>[App.vue]"]
  node_mcp["MCP Server<br/>[mcp_server.py]"]
  node_frameworks["Framework Adapters<br/>[_core.py]"]
  node_cli["Ghost CLI<br/>[run.py]"]
end

subgraph group_backend["API and Orchestration"]
  node_api_app["FastAPI App<br/>[app.py]"]
  node_phone_routes["Phone Routes<br/>[phone.py]"]
  node_chat_routes["Agent Chat Routes<br/>[agent_chat.py]"]
  node_agent_chat["Agent Chat<br/>[agent_chat.py]"]
  node_agent_tools["Agent Tools<br/>[agent_tools.py]"]
  node_device_context["Device Context<br/>[device_context.py]"]
  node_storage[("SQLite Persistence<br/>[base.py]")]
  node_db_helpers["Database Helpers<br/>[db_helpers.py]"]
end

subgraph group_devices["Device Runtime"]
  node_device_factory["Platform Device Factory<br/>[device.py]"]
  node_android["Android ADB<br/>[adb.py]"]
  node_ios["iOS WDA<br/>[ios.py]"]
  node_streaming["Screen Streaming<br/>[streaming.py]"]
  node_emulators["Emulator Pool"]
end

subgraph group_automation["Skills and Jobs"]
  node_skill_runtime["Skill Runtime<br/>[base.py]"]
  node_skill_platforms["Skill Platforms<br/>[platforms.py]"]
  node_skill_hub["Skill Hub<br/>[skills.py]"]
  node_creator["Skill Creator<br/>[skill_creation.py]"]
  node_explorer["App Explorer<br/>[auto_creator.py]"]
  node_job_engine["Job Engine<br/>[job_engine.py]"]
  node_scheduler["Scheduler"]
end

subgraph group_phone_apps["Phone Applications"]
  node_portal["Android Portal"]
  node_ios_agent["iOS On-Device Agent<br/>[AgentLoop.swift]"]
  node_ios_inference["On-Device Inference"]
end

node_user(("Agent or User"))

node_user -->|"issues tool requests"| node_mcp
node_user -->|"starts device chat"| node_dashboard
node_user -->|"runs task"| node_cli
node_user -->|"uses agent tools"| node_frameworks
node_dashboard -->|"calls REST API"| node_api_app
node_cli -->|"invokes agent"| node_agent_chat
node_frameworks -->|"exposes tools"| node_agent_tools
node_api_app -->|"registers routes"| node_phone_routes
node_api_app -->|"registers routes"| node_chat_routes
node_mcp -.->|"provides tool surface"| node_agent_tools
node_chat_routes -->|"dispatches chat"| node_agent_chat
node_agent_chat -.->|"uses tools"| node_agent_tools
node_phone_routes -->|"resolves devices"| node_device_factory
node_phone_routes -->|"requests screen context"| node_device_context
node_device_context -->|"gets device"| node_device_factory
node_device_factory -->|"dispatches Android"| node_android
node_device_factory -->|"dispatches iOS"| node_ios
node_phone_routes -->|"reads device records"| node_storage
node_phone_routes -->|"uses DB helpers"| node_db_helpers
node_streaming -->|"gets device stream"| node_device_factory
node_streaming -.->|"connects Android stream"| node_portal
node_agent_tools -->|"reads device state"| node_device_context
node_skill_runtime -->|"selects platform"| node_skill_platforms
node_skill_platforms -->|"uses device"| node_device_factory
node_skill_hub -->|"installs and runs skills"| node_skill_runtime
node_creator -->|"inspects screen"| node_device_context
node_explorer -->|"explores device"| node_device_factory
node_scheduler -->|"enqueues scheduled jobs"| node_job_engine
node_job_engine -->|"runs skill jobs"| node_skill_platforms
node_job_engine -->|"targets device"| node_device_factory
node_job_engine -->|"uses DB helpers"| node_db_helpers
node_api_app -.->|"registers emulator routes"| node_emulators
node_ios_agent -.->|"generates responses"| node_ios_inference

click node_dashboard "https://github.com/ghost-in-the-droid/android-agent/blob/main/frontend/src/App.vue"
click node_mcp "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/mcp_server.py"
click node_frameworks "https://github.com/ghost-in-the-droid/android-agent/blob/main/integrations/_core.py"
click node_cli "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/ghostcli/run.py"
click node_api_app "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/app.py"
click node_phone_routes "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/phone.py"
click node_chat_routes "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/agent_chat.py"
click node_agent_chat "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/agent_chat.py"
click node_agent_tools "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/agent_tools.py"
click node_device_context "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/device_context.py"
click node_storage "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/models/base.py"
click node_db_helpers "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/db_helpers.py"
click node_device_factory "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/bots/common/device.py"
click node_android "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/bots/common/adb.py"
click node_ios "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/bots/common/ios.py"
click node_streaming "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/streaming.py"
click node_portal "https://github.com/ghost-in-the-droid/android-agent/blob/main/portal/app/src/main/java/com/ghostinthedroid/portal/GhostWebRtcManager.kt"
click node_skill_runtime "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/skills/base.py"
click node_skill_platforms "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/skills/platforms.py"
click node_skill_hub "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/skills.py"
click node_creator "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/skill_creation.py"
click node_explorer "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/skills/auto_creator.py"
click node_job_engine "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/job_engine.py"
click node_scheduler "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/scheduler_service.py"
click node_emulators "https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/emulator_service.py"
click node_ios_agent "https://github.com/ghost-in-the-droid/android-agent/blob/main/ios/GhostLLM/Agent/AgentLoop.swift"
click node_ios_inference "https://github.com/ghost-in-the-droid/android-agent/blob/main/ios/GhostLLM/Engine/InferenceEngine.swift"

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_dashboard,node_mcp,node_frameworks,node_cli,node_user toneBlue
class node_api_app,node_phone_routes,node_chat_routes,node_agent_chat,node_agent_tools,node_device_context,node_storage,node_db_helpers toneAmber
class node_device_factory,node_android,node_ios,node_streaming,node_emulators toneMint
class node_skill_runtime,node_skill_platforms,node_skill_hub,node_creator,node_explorer,node_job_engine,node_scheduler toneRose
class node_portal,node_ios_agent,node_ios_inference toneIndigo
```

## Components

### Agent Interfaces

- [Web Dashboard](https://github.com/ghost-in-the-droid/android-agent/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [MCP Server](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/mcp_server.py): `gitd/mcp_server.py`
- [Framework Adapters](https://github.com/ghost-in-the-droid/android-agent/blob/main/integrations/_core.py): `integrations/_core.py`
- [Ghost CLI](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/ghostcli/run.py): `gitd/ghostcli/run.py`

### API and Orchestration

- [FastAPI App](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/app.py): `gitd/app.py`
- [Phone Routes](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/phone.py): `gitd/routers/phone.py`
- [Agent Chat Routes](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/agent_chat.py): `gitd/routers/agent_chat.py`
- [Agent Chat](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/agent_chat.py): `gitd/services/agent_chat.py`
- [Agent Tools](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/agent_tools.py): `gitd/services/agent_tools.py`
- [Device Context](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/device_context.py): `gitd/services/device_context.py`
- [SQLite Persistence](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/models/base.py): `gitd/models/base.py`
- [Database Helpers](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/db_helpers.py): `gitd/services/db_helpers.py`

### Device Runtime

- [Platform Device Factory](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/bots/common/device.py): `gitd/bots/common/device.py`
- [Android ADB](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/bots/common/adb.py): `gitd/bots/common/adb.py`
- [iOS WDA](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/bots/common/ios.py): `gitd/bots/common/ios.py`
- [Screen Streaming](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/streaming.py): `gitd/routers/streaming.py`
- [Emulator Pool](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/emulator_service.py): `gitd/services/emulator_service.py`

### Skills and Jobs

- [Skill Runtime](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/skills/base.py): `gitd/skills/base.py`
- [Skill Platforms](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/skills/platforms.py): `gitd/skills/platforms.py`
- [Skill Hub](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/routers/skills.py): `gitd/routers/skills.py`
- [Skill Creator](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/skill_creation.py): `gitd/services/skill_creation.py`
- [App Explorer](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/skills/auto_creator.py): `gitd/skills/auto_creator.py`
- [Job Engine](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/job_engine.py): `gitd/services/job_engine.py`
- [Scheduler](https://github.com/ghost-in-the-droid/android-agent/blob/main/gitd/services/scheduler_service.py): `gitd/services/scheduler_service.py`

### Phone Applications

- [Android Portal](https://github.com/ghost-in-the-droid/android-agent/blob/main/portal/app/src/main/java/com/ghostinthedroid/portal/GhostWebRtcManager.kt): `portal/app/src/main/java/com/ghostinthedroid/portal/GhostWebRtcManager.kt`
- [iOS On-Device Agent](https://github.com/ghost-in-the-droid/android-agent/blob/main/ios/GhostLLM/Agent/AgentLoop.swift): `ios/GhostLLM/Agent/AgentLoop.swift`
- [On-Device Inference](https://github.com/ghost-in-the-droid/android-agent/blob/main/ios/GhostLLM/Engine/InferenceEngine.swift): `ios/GhostLLM/Engine/InferenceEngine.swift`

### Other components

- **Agent or User**

## Connections

- Agent or User → MCP Server: issues tool requests (evidence: `README.md`)
- Agent or User → Web Dashboard: starts device chat (evidence: `README.md`)
- Agent or User → Ghost CLI: runs task (evidence: `README.md`)
- Agent or User → Framework Adapters: uses agent tools (evidence: `README.md`)
- Web Dashboard → FastAPI App: calls REST API (evidence: `README.md`)
- Ghost CLI → Agent Chat: invokes agent (evidence: `gitd/ghostcli/run.py`)
- Framework Adapters → Agent Tools: exposes tools (evidence: `integrations/_core.py`)
- FastAPI App → Phone Routes: registers routes (evidence: `gitd/app.py`)
- FastAPI App → Agent Chat Routes: registers routes (evidence: `gitd/app.py`)
- MCP Server → Agent Tools: provides tool surface
- Agent Chat Routes → Agent Chat: dispatches chat (evidence: `gitd/routers/agent_chat.py`)
- Agent Chat → Agent Tools: uses tools
- Phone Routes → Platform Device Factory: resolves devices (evidence: `gitd/routers/phone.py`)
- Phone Routes → Device Context: requests screen context (evidence: `gitd/routers/phone.py`)
- Device Context → Platform Device Factory: gets device (evidence: `gitd/services/device_context.py`)
- Platform Device Factory → Android ADB: dispatches Android (evidence: `gitd/bots/common/device.py`)
- Platform Device Factory → iOS WDA: dispatches iOS (evidence: `gitd/bots/common/device.py`)
- Phone Routes → SQLite Persistence: reads device records (evidence: `gitd/routers/phone.py`)
- Phone Routes → Database Helpers: uses DB helpers (evidence: `gitd/routers/phone.py`)
- Screen Streaming → Platform Device Factory: gets device stream (evidence: `gitd/routers/streaming.py`)
- Screen Streaming → Android Portal: connects Android stream
- Agent Tools → Device Context: reads device state (evidence: `gitd/services/device_context.py`)
- Skill Runtime → Skill Platforms: selects platform (evidence: `gitd/skills/base.py`)
- Skill Platforms → Platform Device Factory: uses device (evidence: `gitd/skills/platforms.py`)
- Skill Hub → Skill Runtime: installs and runs skills (evidence: `README.md`)
- Skill Creator → Device Context: inspects screen
- App Explorer → Platform Device Factory: explores device
- Scheduler → Job Engine: enqueues scheduled jobs (evidence: `gitd/services/scheduler_service.py`)
- Job Engine → Skill Platforms: runs skill jobs (evidence: `gitd/services/job_engine.py`)
- Job Engine → Platform Device Factory: targets device (evidence: `gitd/services/job_engine.py`)
- Job Engine → Database Helpers: uses DB helpers
- FastAPI App → Emulator Pool: registers emulator routes
- iOS On-Device Agent → On-Device Inference: generates responses
