# mobile-dev-inc/maestro architecture

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

- Interactive diagram: https://gitdiagram.com/mobile-dev-inc/maestro
- Repository: https://github.com/mobile-dev-inc/maestro

## Overview

#### Purpose and entry points
Maestro is a JVM-based, cross-platform UI/E2E automation framework for Android, iOS, and web. Users write YAML flows; the CLI parses, validates, executes, and reports them against local or cloud devices. Main entry points are the CLI application and command layer: `maestro-cli/src/main/java/maestro/cli/App.kt`, `maestro-cli/src/main/java/maestro/cli/command/TestCommand.kt`, and MCP server command support in `maestro-cli/src/main/java/maestro/cli/command/McpCommand.kt`.

#### Flow language and shared domain model
The platform-independent contract is a typed flow model: commands, selectors, conditions, configuration, and workspace metadata. This is the boundary between YAML authoring and runtime execution. Core definitions live in `maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt`, `maestro-orchestra-models/src/main/java/maestro/orchestra/ElementSelector.kt`, and `maestro-orchestra-models/src/main/java/maestro/orchestra/MaestroConfig.kt`.

#### Parse, validate, and plan flows
The orchestra module turns YAML files into typed commands, reports syntax/validation errors with source context, resolves subflow dependencies, and plans workspace execution order/filtering. This stage prevents invalid paths, malformed commands, and unsupported configuration before device interaction. Key paths: `maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt`, `maestro-orchestra/src/main/java/maestro/orchestra/workspace/WorkspaceExecutionPlanner.kt`, and `maestro-orchestra/src/main/java/maestro/orchestra/validation/AppValidator.kt`.

#### Execution engine and artifacts
`Orchestra` interprets the normalized command list against a `Maestro` device session, applying synchronization, selectors, interactions, assertions, retries, scripts, screenshots, recording, and nested flows. It emits listener events and captures failure/debug artifacts; CLI runners turn those events into terminal, HTML, or JUnit output. Core paths: `maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt`, `maestro-client/src/main/java/maestro/Maestro.kt`, and `maestro-orchestra/src/main/kotlin/maestro/orchestra/debug/ArtifactCollector.kt`.

#### Device abstraction and platform adapters
`maestro-client` defines the common Driver/device/view-hierarchy API and selects platform implementations. Android communicates through ADB and bundled APK services; iOS uses an installed XCTest driver over local device/simulator tooling; web uses Chrome DevTools Protocol/Selenium-oriented components. Important boundaries: `maestro-client/src/main/java/maestro/Driver.kt`, `maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt`, `maestro-client/src/main/java/maestro/drivers/IOSDriver.kt`, and `maestro-client/src/main/java/maestro/drivers/CdpWebDriver.kt`.

#### On-device drivers and OS dependencies
Android driver code is an instrumentation/service implementation that exposes accessibility hierarchy, screenshots, input, settings, location, and media operations. iOS has both Kotlin-side XCTest client/installer code and a Swift/Objective-C XCTest runner that hosts route handlers. Platform runtimes include Android SDK/ADB/emulators, Xcode/simctl/XCTest/iOS devices, Chrome/CDP, Java 17+, and GraalJS for flow scripts. Paths: `maestro-android/src/androidTest/java/dev/mobile/maestro/MaestroDriverService.kt`, `maestro-ios-driver/src/main/kotlin/xcuitest/XCTestDriverClient.kt`, `maestro-ios-xctest-runner/maestro-driver-iosUITests/Routes/XCTestHTTPServer.swift`, and `maestro-client/src/main/java/maestro/js/GraalJsEngine.kt`.

#### Integrations: cloud, AI, and MCP
The CLI optionally authenticates to Maestro services for cloud execution/device listing, analytics, updates, and cloud artifacts. It also embeds an MCP server so coding agents can run flows and inspect/control live devices; its viewer includes a separate TypeScript/Vite frontend. AI commands use cloud prediction and provider clients for visual assertions/text extraction, including Anthropic and OpenAI integrations. Paths: `maestro-cli/src/main/java/maestro/cli/cloud/CloudInteractor.kt`, `maestro-cli/src/main/java/maestro/cli/mcp/McpServer.kt`, `maestro-ai/src/main/java/maestro/ai/CloudPredictionAIEngine.kt`, and `maestro-ai/src/main/java/maestro/ai/anthropic/Client.kt`.

#### Build and delivery
This is a Gradle multi-module repository rooted at `settings.gradle.kts` and `build.gradle.kts`. GitHub Actions build and test the CLI and demo app, publish CLI releases/snapshots, publish schemas, and rebuild iOS drivers. End-to-end fixtures center on a Flutter demo application and YAML workspaces: `e2e/run_tests`, `e2e/demo_app/lib/main.dart`, and `.github/workflows/test-e2e.yaml`.

Main entry points: [`maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt`](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt) (Orchestra engine), [`maestro-client/src/main/java/maestro/Driver.kt`](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/Driver.kt) (Driver API), [`maestro-cli/src/main/java/maestro/cli/App.kt`](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/App.kt) (CLI application), [`maestro-cli/src/main/java/maestro/cli/command/TestCommand.kt`](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/command/TestCommand.kt) (Test command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI &amp; integrations"]
  node_app["CLI application<br/>Kotlin CLI<br/>[App.kt]"]
  node_test_command["Test command<br/>CLI command<br/>[TestCommand.kt]"]
  node_mcp{{"MCP server<br/>agent integration<br/>[McpServer.kt]"}}
  node_cloud["Cloud interactor<br/>service client<br/>[CloudInteractor.kt]"]
  node_ai_engine["Cloud AI engine<br/>AI integration"]
end

subgraph group_flow["Flow processing"]
  node_models["Typed flow model<br/>shared domain<br/>[Commands.kt]"]
  node_parser["YAML flow parser"]
  node_validator["Flow validator<br/>validation<br/>[AppValidator.kt]"]
  node_planner["Workspace planner<br/>execution planner"]
end

subgraph group_execution["Execution &amp; devices"]
  node_orchestra["Orchestra engine<br/>command interpreter<br/>[Orchestra.kt]"]
  node_artifacts["Artifact collector<br/>debug artifacts"]
  node_maestro_session["Maestro session<br/>device session<br/>[Maestro.kt]"]
  node_driver_api["Driver API<br/>device abstraction<br/>[Driver.kt]"]
  node_android_driver["Android driver<br/>platform adapter<br/>[AndroidDriver.kt]"]
  node_ios_driver["iOS driver<br/>platform adapter<br/>[IOSDriver.kt]"]
  node_web_driver["Web driver<br/>platform adapter<br/>[CdpWebDriver.kt]"]
end

subgraph group_platform["Platform runtimes"]
  node_android_service["Android driver service<br/>instrumentation service"]
  node_ios_xctest_client["XCTest driver client<br/>iOS transport"]
  node_ios_xctest_runner["XCTest HTTP runner<br/>iOS on-device runner"]
  node_graal_js["GraalJS engine<br/>script runtime<br/>[GraalJsEngine.kt]"]
end

subgraph group_delivery["Build &amp; delivery"]
  node_gradle["Gradle multi-module build<br/>build system"]
  node_e2e["E2E fixtures"]
  node_ci["GitHub Actions E2E<br/>CI workflow<br/>[test-e2e.yaml]"]
end

node_app -->|"dispatches"| node_test_command
node_app -->|"starts"| node_mcp
node_test_command -->|"loads flows"| node_parser
node_parser -->|"produces"| node_models
node_models -->|"validates"| node_validator
node_validator -->|"approved flows"| node_planner
node_planner -->|"execution plan"| node_orchestra
node_orchestra -->|"drives"| node_maestro_session
node_orchestra -->|"captures debug data"| node_artifacts
node_orchestra -->|"runs scripts"| node_graal_js
node_orchestra -.->|"uses AI assertions"| node_ai_engine
node_maestro_session -->|"uses"| node_driver_api
node_driver_api -->|"selects"| node_android_driver
node_driver_api -->|"selects"| node_ios_driver
node_driver_api -->|"selects"| node_web_driver
node_android_driver -->|"ADB/service protocol"| node_android_service
node_ios_driver -->|"installs and connects"| node_ios_xctest_client
node_ios_xctest_client -->|"XCTest routes"| node_ios_xctest_runner
node_app -.->|"optional cloud operations"| node_cloud
node_mcp -->|"inspects and controls"| node_maestro_session
node_gradle -->|"builds"| node_app
node_ci -->|"builds and publishes"| node_gradle
node_ci -->|"runs"| node_e2e
node_e2e -.->|"exercises"| node_test_command

click node_app "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/App.kt"
click node_test_command "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/command/TestCommand.kt"
click node_mcp "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/mcp/McpServer.kt"
click node_cloud "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/cloud/CloudInteractor.kt"
click node_models "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt"
click node_parser "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt"
click node_validator "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/validation/AppValidator.kt"
click node_planner "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/workspace/WorkspaceExecutionPlanner.kt"
click node_orchestra "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt"
click node_artifacts "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/kotlin/maestro/orchestra/debug/ArtifactCollector.kt"
click node_maestro_session "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/Maestro.kt"
click node_driver_api "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/Driver.kt"
click node_android_driver "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt"
click node_ios_driver "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/drivers/IOSDriver.kt"
click node_web_driver "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/drivers/CdpWebDriver.kt"
click node_android_service "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-android/src/androidTest/java/dev/mobile/maestro/MaestroDriverService.kt"
click node_ios_xctest_client "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-ios-driver/src/main/kotlin/xcuitest/XCTestDriverClient.kt"
click node_ios_xctest_runner "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-ios-xctest-runner/maestro-driver-iosUITests/Routes/XCTestHTTPServer.swift"
click node_graal_js "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/js/GraalJsEngine.kt"
click node_ai_engine "https://github.com/mobile-dev-inc/maestro/blob/main/maestro-ai/src/main/java/maestro/ai/CloudPredictionAIEngine.kt"
click node_gradle "https://github.com/mobile-dev-inc/maestro/blob/main/settings.gradle.kts"
click node_e2e "https://github.com/mobile-dev-inc/maestro/blob/main/e2e/run_tests"
click node_ci "https://github.com/mobile-dev-inc/maestro/blob/main/.github/workflows/test-e2e.yaml"

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_app,node_test_command,node_mcp,node_cloud,node_ai_engine toneBlue
class node_models,node_parser,node_validator,node_planner toneAmber
class node_orchestra,node_artifacts,node_maestro_session,node_driver_api,node_android_driver,node_ios_driver,node_web_driver toneMint
class node_android_service,node_ios_xctest_client,node_ios_xctest_runner,node_graal_js toneRose
class node_gradle,node_e2e,node_ci toneIndigo
```

## Components

### CLI & integrations

- [CLI application](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/App.kt): Kotlin CLI · Primary user entry point. · `maestro-cli/src/main/java/maestro/cli/App.kt`
- [Test command](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/command/TestCommand.kt): CLI command · `maestro-cli/src/main/java/maestro/cli/command/TestCommand.kt`
- [MCP server](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/mcp/McpServer.kt): agent integration · Lets coding agents run flows and inspect devices. · `maestro-cli/src/main/java/maestro/cli/mcp/McpServer.kt`
- [Cloud interactor](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-cli/src/main/java/maestro/cli/cloud/CloudInteractor.kt): service client · Cloud runs, devices, artifacts, auth, and analytics. · `maestro-cli/src/main/java/maestro/cli/cloud/CloudInteractor.kt`
- [Cloud AI engine](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-ai/src/main/java/maestro/ai/CloudPredictionAIEngine.kt): AI integration · Visual assertions and text extraction through cloud/provider clients. · `maestro-ai/src/main/java/maestro/ai/CloudPredictionAIEngine.kt`

### Flow processing

- [Typed flow model](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt): shared domain · Commands, selectors, conditions, and configuration. · `maestro-orchestra-models/src/main/java/maestro/orchestra/Commands.kt`
- [YAML flow parser](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt): parser · Converts authored YAML to typed flows with source context. · `maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt`
- [Flow validator](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/validation/AppValidator.kt): validation · Rejects malformed commands and unsupported configuration. · `maestro-orchestra/src/main/java/maestro/orchestra/validation/AppValidator.kt`
- [Workspace planner](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/workspace/WorkspaceExecutionPlanner.kt): execution planner · Resolves subflows, ordering, and filtering. · `maestro-orchestra/src/main/java/maestro/orchestra/workspace/WorkspaceExecutionPlanner.kt`

### Execution & devices

- [Orchestra engine](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt): command interpreter · Executes normalized commands with retries, assertions, scripts, and nested flows. · `maestro-orchestra/src/main/java/maestro/orchestra/Orchestra.kt`
- [Artifact collector](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-orchestra/src/main/kotlin/maestro/orchestra/debug/ArtifactCollector.kt): debug artifacts · Captures failure and debugging evidence. · `maestro-orchestra/src/main/kotlin/maestro/orchestra/debug/ArtifactCollector.kt`
- [Maestro session](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/Maestro.kt): device session · Execution-facing device session API. · `maestro-client/src/main/java/maestro/Maestro.kt`
- [Driver API](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/Driver.kt): device abstraction · Common device and view-hierarchy contract. · `maestro-client/src/main/java/maestro/Driver.kt`
- [Android driver](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt): platform adapter · `maestro-client/src/main/java/maestro/drivers/AndroidDriver.kt`
- [iOS driver](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/drivers/IOSDriver.kt): platform adapter · `maestro-client/src/main/java/maestro/drivers/IOSDriver.kt`
- [Web driver](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/drivers/CdpWebDriver.kt): platform adapter · `maestro-client/src/main/java/maestro/drivers/CdpWebDriver.kt`

### Platform runtimes

- [Android driver service](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-android/src/androidTest/java/dev/mobile/maestro/MaestroDriverService.kt): instrumentation service · Provides hierarchy, input, screenshots, settings, and media operations. · `maestro-android/src/androidTest/java/dev/mobile/maestro/MaestroDriverService.kt`
- [XCTest driver client](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-ios-driver/src/main/kotlin/xcuitest/XCTestDriverClient.kt): iOS transport · Installs and communicates with the XCTest driver. · `maestro-ios-driver/src/main/kotlin/xcuitest/XCTestDriverClient.kt`
- [XCTest HTTP runner](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-ios-xctest-runner/maestro-driver-iosUITests/Routes/XCTestHTTPServer.swift): iOS on-device runner · Hosts XCTest route handlers. · `maestro-ios-xctest-runner/maestro-driver-iosUITests/Routes/XCTestHTTPServer.swift`
- [GraalJS engine](https://github.com/mobile-dev-inc/maestro/blob/main/maestro-client/src/main/java/maestro/js/GraalJsEngine.kt): script runtime · `maestro-client/src/main/java/maestro/js/GraalJsEngine.kt`

### Build & delivery

- [Gradle multi-module build](https://github.com/mobile-dev-inc/maestro/blob/main/settings.gradle.kts): build system · `settings.gradle.kts`
- [E2E fixtures](https://github.com/mobile-dev-inc/maestro/blob/main/e2e/run_tests): demo app & YAML workspaces · `e2e/run_tests`
- [GitHub Actions E2E](https://github.com/mobile-dev-inc/maestro/blob/main/.github/workflows/test-e2e.yaml): CI workflow · Builds, tests, publishes, and rebuilds platform drivers. · `.github/workflows/test-e2e.yaml`

## Connections

- CLI application → Test command: dispatches
- CLI application → MCP server: starts
- Test command → YAML flow parser: loads flows
- YAML flow parser → Typed flow model: produces
- Typed flow model → Flow validator: validates
- Flow validator → Workspace planner: approved flows
- Workspace planner → Orchestra engine: execution plan
- Orchestra engine → Maestro session: drives
- Orchestra engine → Artifact collector: captures debug data
- Orchestra engine → GraalJS engine: runs scripts
- Orchestra engine → Cloud AI engine: uses AI assertions
- Maestro session → Driver API: uses
- Driver API → Android driver: selects
- Driver API → iOS driver: selects
- Driver API → Web driver: selects
- Android driver → Android driver service: ADB/service protocol
- iOS driver → XCTest driver client: installs and connects
- XCTest driver client → XCTest HTTP runner: XCTest routes
- CLI application → Cloud interactor: optional cloud operations
- MCP server → Maestro session: inspects and controls
- Gradle multi-module build → CLI application: builds
- GitHub Actions E2E → Gradle multi-module build: builds and publishes
- GitHub Actions E2E → E2E fixtures: runs
- E2E fixtures → Test command: exercises
