# Architecture

**There is one runtime underneath everything.** MobileCLI is the single API that speaks to every device. Mobilewright and Mobile MCP are clients of it, CI and scripts call it directly, and Mobile Next Cloud is that same runtime — managed and scaled for you. So the stack is an hourglass: many ways in on top, one waist in the middle, every device on the bottom.

<!-- -->

The same MobileCLI runs in two places, unchanged — on your machine, or behind the cloud:

<!-- -->

Because local and cloud are the same stack, moving to the cloud is a connection-string change, not a rewrite.

## Which piece do I use?[​](#which-piece-do-i-use "Direct link to Which piece do I use?")

| You are…                                                   | You use…                                 |
| ---------------------------------------------------------- | ---------------------------------------- |
| A developer writing mobile tests or automating mobile apps | **Mobilewright**                         |
| An AI agent (Claude Code, Cursor, Copilot…)                | **Mobile MCP**                           |
| Scripting or CI, want raw control                          | **mobilecli** directly (CLI or JSON-RPC) |
| You need real devices at scale                             | **Mobile Next Cloud**                    |

## How a single action flows[​](#how-a-single-action-flows "Direct link to How a single action flows")

When Mobile MCP receives *"tap the Login button"*, it calls MobileCLI, which asks DeviceKit (running on the device) for the accessibility tree, finds the element, and tells DeviceKit to inject the tap — then the result travels back up the same path. Every layer speaks JSON-RPC, so the identical call works whether the device is on your desk or in the cloud.

## Layers[​](#layers "Direct link to Layers")

**DeviceKit** — Runs on the device (or simulator host). Exposes a JSON-RPC 2.0 API over WebSocket or HTTP. Handles screen capture, accessibility tree dumps, input injection, app lifecycle. Separate implementations for iOS ([devicekit-ios](https://github.com/mobile-next/devicekit-ios)) and Android ([devicekit-android](https://github.com/mobile-next/devicekit-android)).

**MobileCLI** — A single Go binary that connects to DeviceKit and exposes a unified interface across iOS and Android. Serves three interfaces: CLI commands, JSON-RPC over WebSocket, JSON-RPC over HTTP POST. Mobilewright and Mobile MCP both talk to MobileCLI.

**Mobilewright** — TypeScript/JS automation framework. Connects to MobileCLI via WebSocket. Provides the Playwright-style API (`getByRole`, `expect`, auto-waiting) on top of MobileCLI's raw JSON-RPC calls.

**Mobile MCP** — MCP server that connects to MobileCLI. Makes mobile device control available to any MCP-compatible AI agent (Claude Code, Cursor, VS Code Copilot, etc.) as a set of structured tools.

**Mobile Next Cloud** — Manages a fleet of MobileCLI instances running in the cloud (AWS Device Farm). Handles device allocation, session management, test result hosting, and permissions. Exposes a REST API for management, JSON-RPC for device interaction, and its own MCP server for remote access.