# astur-mobile/astur architecture

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

- Interactive diagram: https://gitdiagram.com/astur-mobile/astur
- Repository: https://github.com/astur-mobile/astur

## Overview

1. **Repository shape**
   - This is a TypeScript monorepo plus native Android/iOS agent code.
   - The main product is a mobile automation toolkit that exposes a Playwright-style test API, but executes against native platform control paths rather than WebDriver/Appium.

2. **Top-level execution flow**
   - A test imports `@astur-mobile/test`, configures `test.use({ astur: ... })`, and interacts with a `device` fixture.
   - The fixture flows into `packages/core`, which owns sessions, locators, waiting, keyboard behavior, and inspector-facing runtime state.
   - From there, core delegates to the platform package (`packages/android` or `packages/ios`), which talks to the device through native platform tools and optional agent processes.

3. **Shared contract layer**
   - `packages/protocol` is the boundary for shared data types and protocol messages.
   - It is the common language between core, platform drivers, and native agents, so selector semantics and response shapes stay aligned across Android and iOS.

4. **Core runtime**
   - `packages/core` is the central orchestration layer.
   - It implements sessions, locator resolution, auto-waiting, keyboard actions, config parsing, and error shaping.
   - This is the layer that turns Playwright-like calls such as `getByRole`, `tap`, `expect(...).toBeVisible()`, and `scrollIntoView()` into platform-specific operations.

5. **Android architecture**
   - `packages/android` is the host-side Android driver.
   - It uses ADB for lifecycle tasks, artifacts, and legacy fallback paths, but the default interaction path is a native Kotlin UIAutomator agent.
   - The internal agent code lives in `packages/android-agent`, built as APK artifacts and shipped under `packages/android/assets/agent`.
   - Android responsibilities include device discovery, emulator boot, app install/launch, screenshots, video, web URL opening, file transfer, and selector execution.

6. **Android interaction boundary**
   - The Android flow is split between host orchestration and on-device execution.
   - Host code chooses whether to operate through the Kotlin agent or the explicit ADB/XML fallback.
   - This keeps long-running device control on the native side while reserving ADB for setup, diagnostics, and compatibility.

7. **iOS architecture**
   - `packages/ios` is the host-side iOS driver.
   - It uses `simctl` and `devicectl` for diagnostics, simulator/real-device management, install/launch/terminate, and screenshots.
   - Native element lookup and gestures require the bundled Swift XCUITest agent under `packages/ios/assets/ios-xctest-agent`.
   - The iOS agent boundary includes a host app, a bridge client/server, and XCTest-based UI test code.

8. **iOS platform constraint**
   - The iOS design makes the XCTest boundary explicit: native element control is not done through a generic cross-platform protocol alone.
   - Real devices require signing and an Apple team for the XCUITest runner, which is an architectural dependency rather than just a build detail.

9. **Test integration and public API**
   - `packages/test` is the Playwright Test integration layer that exports the `test` and `expect` APIs.
   - `packages/astur-mobile` is the public npm-facing package that exposes the `astur-mobile` CLI entrypoint.
   - The combination gives consumers a familiar Playwright-like surface while hiding device-specific runtime wiring underneath.

10. **CLI and inspector**
   - `packages/cli` contains operational tooling: `doctor`, `devices`, `init`, `codegen`, `inspect`, and `test`.
   - It also hosts the inspector server and UI, which are separate from the test runtime and used for discovery/codegen/debug workflows.
   - `npx astur-mobile inspect` is an alias for code generation, reinforcing the CLI as both setup and introspection tooling.

11. **Scaffolding, examples, and documentation**
   - `packages/create-astur` is the project scaffolder for `npm create astur`.
   - `examples/` contains runnable Android and iOS suites that demonstrate the expected test architecture and fixture usage.
   - `docs/` holds the canonical source docs, and `docs-site/` is the Astro-based static site that publishes them.

12. **Native assets and distribution**
   - Native binaries and demo apps are checked into `assets/` and package-local `assets/` folders so the repo can build and smoke-test without external bootstrapping.
   - The Android agent APKs and the iOS XCTest agent sources are distributed as package assets, which is why the repo has both source trees and packaged copies.

13. **Verification and release pipeline**
   - `tests/` contains unit and integration coverage for parsers, runtime behavior, locator semantics, agent modes, and platform-specific flows.
   - GitHub workflows cover CI, docs publishing, native smoke tests, promotion, and release.
   - That means the repo’s architecture is validated at three levels: pure TypeScript logic, host-to-device driver behavior, and native agent packaging.

14. **How to diagram it**
   - Draw the center as `@astur-mobile/test` and `packages/core`.
   - Branch left/right into Android and iOS drivers.
   - Under each driver, separate host orchestration from on-device agent execution.
   - Keep `packages/protocol` as a shared boundary feeding both platform stacks.
   - Place CLI, inspector, docs, examples, and scaffolding as adjacent support systems rather than part of the runtime data path.

Main entry points: [`packages/core/src/index.ts`](https://github.com/astur-mobile/astur/blob/main/packages/core/src/index.ts) (Core runtime), [`packages/android/src/index.ts`](https://github.com/astur-mobile/astur/blob/main/packages/android/src/index.ts) (Android host), [`tests/core-runtime.test.ts`](https://github.com/astur-mobile/astur/blob/main/tests/core-runtime.test.ts) (Verification), [`packages/cli/src/index.ts`](https://github.com/astur-mobile/astur/blob/main/packages/cli/src/index.ts) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_node_test["Test API<br/>Playwright integration<br/>[index.ts]"]
  node_node_core["Core runtime<br/>orchestrator<br/>[index.ts]"]
  node_node_protocol["Protocol<br/>shared contract<br/>[index.ts]"]
  node_node_session["Sessions<br/>core session<br/>[session.ts]"]
  node_node_locator["Locators<br/>selector engine<br/>[locator.ts]"]
  node_node_wait["Waiting<br/>auto-wait<br/>[wait.ts]"]
  node_node_keyboard["Keyboard<br/>input helper<br/>[keyboard.ts]"]
end

subgraph group_grp_android["Android"]
  node_node_android_host["Android host<br/>driver<br/>[index.ts]"]
  node_node_android_cmd["ADB control<br/>host tooling<br/>[command.ts]"]
  node_node_android_xml["XML fallback<br/>fallback path<br/>[uiautomatorXml.ts]"]
  node_node_android_agent["Android agent<br/>on-device agent"]
end

subgraph group_grp_ios["iOS"]
  node_node_ios_host["iOS host<br/>driver<br/>[index.ts]"]
  node_node_ios_agent["iOS agent<br/>XCUITest agent"]
end

subgraph group_grp_support["Support"]
  node_node_mobile["Mobile pkg<br/>npm entrypoint<br/>[index.ts]"]
  node_node_cli["CLI<br/>operational tooling<br/>[index.ts]"]
  node_node_scaffold["Scaffolder<br/>project generator<br/>[index.ts]"]
  node_node_examples["Examples<br/>runnable suites"]
  node_node_docs["Docs<br/>documentation site<br/>[architecture.md]"]
end

subgraph group_grp_quality["Quality"]
  node_node_tests["Verification<br/>tests"]
end

node_node_test -->|"uses"| node_node_core
node_node_mobile -->|"exports"| node_node_test
node_node_core -->|"shares types"| node_node_protocol
node_node_core -->|"manages"| node_node_session
node_node_core -->|"resolves"| node_node_locator
node_node_core -->|"waits"| node_node_wait
node_node_core -->|"types"| node_node_keyboard
node_node_core -->|"targets"| node_node_android_host
node_node_core -->|"targets"| node_node_ios_host
node_node_android_host -->|"orchestrates"| node_node_android_cmd
node_node_android_host -.->|"falls back"| node_node_android_xml
node_node_android_host -->|"executes via"| node_node_android_agent
node_node_android_agent -->|"implements"| node_node_protocol
node_node_ios_host -->|"executes via"| node_node_ios_agent
node_node_ios_agent -->|"implements"| node_node_protocol
node_node_cli -->|"inspects"| node_node_core
node_node_cli -->|"supports"| node_node_examples
node_node_scaffold -->|"integrates"| node_node_cli
node_node_docs -.->|"documents"| node_node_core
node_node_tests -->|"verifies"| node_node_core
node_node_tests -->|"verifies"| node_node_android_host
node_node_tests -->|"verifies"| node_node_ios_host

click node_node_test "https://github.com/astur-mobile/astur/blob/main/packages/test/src/index.ts"
click node_node_mobile "https://github.com/astur-mobile/astur/blob/main/packages/astur-mobile/src/index.ts"
click node_node_core "https://github.com/astur-mobile/astur/blob/main/packages/core/src/index.ts"
click node_node_protocol "https://github.com/astur-mobile/astur/blob/main/packages/protocol/src/index.ts"
click node_node_session "https://github.com/astur-mobile/astur/blob/main/packages/core/src/session.ts"
click node_node_locator "https://github.com/astur-mobile/astur/blob/main/packages/core/src/locator.ts"
click node_node_wait "https://github.com/astur-mobile/astur/blob/main/packages/core/src/wait.ts"
click node_node_keyboard "https://github.com/astur-mobile/astur/blob/main/packages/core/src/keyboard.ts"
click node_node_android_host "https://github.com/astur-mobile/astur/blob/main/packages/android/src/index.ts"
click node_node_android_cmd "https://github.com/astur-mobile/astur/blob/main/packages/android/src/command.ts"
click node_node_android_xml "https://github.com/astur-mobile/astur/blob/main/packages/android/src/uiautomatorXml.ts"
click node_node_android_agent "https://github.com/astur-mobile/astur/blob/main/packages/android-agent/src/androidTest/kotlin/dev/astur/agent/AsturAgentServer.kt"
click node_node_ios_host "https://github.com/astur-mobile/astur/blob/main/packages/ios/src/index.ts"
click node_node_ios_agent "https://github.com/astur-mobile/astur/blob/main/packages/ios/assets/ios-xctest-agent/AsturAgentServer.swift"
click node_node_cli "https://github.com/astur-mobile/astur/blob/main/packages/cli/src/index.ts"
click node_node_scaffold "https://github.com/astur-mobile/astur/blob/main/packages/create-astur/src/index.ts"
click node_node_examples "https://github.com/astur-mobile/astur/blob/main/examples/android-native/playwright.config.ts"
click node_node_docs "https://github.com/astur-mobile/astur/blob/main/docs/architecture.md"
click node_node_tests "https://github.com/astur-mobile/astur/blob/main/tests/core-runtime.test.ts"

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_node_test,node_node_core,node_node_protocol,node_node_session,node_node_locator,node_node_wait,node_node_keyboard toneBlue
class node_node_android_host,node_node_android_cmd,node_node_android_xml,node_node_android_agent toneAmber
class node_node_ios_host,node_node_ios_agent toneMint
class node_node_mobile,node_node_cli,node_node_scaffold,node_node_examples,node_node_docs toneRose
class node_node_tests toneIndigo
```

## Components

### Runtime

Test-facing API and orchestration layers that drive devices.

- [Test API](https://github.com/astur-mobile/astur/blob/main/packages/test/src/index.ts): Playwright integration · Public test surface exporting test and expect. · `packages/test/src/index.ts`
- [Core runtime](https://github.com/astur-mobile/astur/blob/main/packages/core/src/index.ts): orchestrator · Sessions, locators, waiting, keyboard actions, config, and errors. · `packages/core/src/index.ts`
- [Protocol](https://github.com/astur-mobile/astur/blob/main/packages/protocol/src/index.ts): shared contract · Cross-package message and selector types shared by core and drivers. · `packages/protocol/src/index.ts`
- [Sessions](https://github.com/astur-mobile/astur/blob/main/packages/core/src/session.ts): core session · Device/session lifecycle and runtime state management. · `packages/core/src/session.ts`
- [Locators](https://github.com/astur-mobile/astur/blob/main/packages/core/src/locator.ts): selector engine · Playwright-style selector resolution and action targeting. · `packages/core/src/locator.ts`
- [Waiting](https://github.com/astur-mobile/astur/blob/main/packages/core/src/wait.ts): auto-wait · Expectation and retry behavior for visible, stable, and ready states. · `packages/core/src/wait.ts`
- [Keyboard](https://github.com/astur-mobile/astur/blob/main/packages/core/src/keyboard.ts): input helper · Text entry and key handling inside the runtime. · `packages/core/src/keyboard.ts`

### Android

Host driver, native agent, and packaged assets for Android execution.

- [Android host](https://github.com/astur-mobile/astur/blob/main/packages/android/src/index.ts): driver · Host-side Android control path using ADB plus native agent fallback. · `packages/android/src/index.ts`
- [ADB control](https://github.com/astur-mobile/astur/blob/main/packages/android/src/command.ts): host tooling · Lifecycle, artifacts, install, launch, screenshots, and compatibility paths. · `packages/android/src/command.ts`
- [XML fallback](https://github.com/astur-mobile/astur/blob/main/packages/android/src/uiautomatorXml.ts): fallback path · Legacy selector and device interaction path when agent execution is not used. · `packages/android/src/uiautomatorXml.ts`
- [Android agent](https://github.com/astur-mobile/astur/blob/main/packages/android-agent/src/androidTest/kotlin/dev/astur/agent/AsturAgentServer.kt): on-device agent · Kotlin UIAutomator agent bundled as APK artifacts and run on-device. · `packages/android-agent/src/androidTest/kotlin/dev/astur/agent/AsturAgentServer.kt`

### iOS

Host driver, native agent, and packaged assets for iOS execution.

- [iOS host](https://github.com/astur-mobile/astur/blob/main/packages/ios/src/index.ts): driver · Host-side iOS control path using simctl/devicectl plus native agent. · `packages/ios/src/index.ts`
- [iOS agent](https://github.com/astur-mobile/astur/blob/main/packages/ios/assets/ios-xctest-agent/AsturAgentServer.swift): XCUITest agent · Bundled Swift/XCTest agent with host app, bridge, and UI test runner. · `packages/ios/assets/ios-xctest-agent/AsturAgentServer.swift`

### Support

CLI, scaffolding, docs, examples, and shared contracts.

- [Mobile pkg](https://github.com/astur-mobile/astur/blob/main/packages/astur-mobile/src/index.ts): npm entrypoint · Public package and CLI entrypoint for astur-mobile. · `packages/astur-mobile/src/index.ts`
- [CLI](https://github.com/astur-mobile/astur/blob/main/packages/cli/src/index.ts): operational tooling · doctor, devices, init, codegen, inspect, test, and inspector server/UI. · `packages/cli/src/index.ts`
- [Scaffolder](https://github.com/astur-mobile/astur/blob/main/packages/create-astur/src/index.ts): project generator · npm create astur project bootstrapper. · `packages/create-astur/src/index.ts`
- [Examples](https://github.com/astur-mobile/astur/blob/main/examples/android-native/playwright.config.ts): runnable suites · Android and iOS example test suites demonstrating fixture usage. · `examples/android-native/playwright.config.ts`
- [Docs](https://github.com/astur-mobile/astur/blob/main/docs/architecture.md): documentation site · Canonical docs content and the Astro-based docs site. · `docs/architecture.md`

### Quality

Tests and CI workflows that validate the stack.

- [Verification](https://github.com/astur-mobile/astur/blob/main/tests/core-runtime.test.ts): tests · Unit and integration coverage for core, drivers, parsers, and agent modes. · `tests/core-runtime.test.ts`

## Connections

- Test API → Core runtime: uses · The test API delegates device behavior into core orchestration.
- Mobile pkg → Test API: exports · The public package exposes the test-facing entrypoint.
- Core runtime → Protocol: shares types · Core and drivers communicate through the protocol contract.
- Core runtime → Sessions: manages · Sessions hold runtime state and device attachment.
- Core runtime → Locators: resolves · Selectors are turned into platform actions through locator resolution.
- Core runtime → Waiting: waits · Core applies auto-wait and expectation retry logic.
- Core runtime → Keyboard: types · Keyboard behavior is part of the central runtime.
- Core runtime → Android host: targets · Core dispatches Android operations through the platform driver.
- Core runtime → iOS host: targets · Core dispatches iOS operations through the platform driver.
- Android host → ADB control: orchestrates · Host-side Android setup and diagnostics are handled via ADB tooling.
- Android host → XML fallback: falls back · The driver can switch to XML/legacy paths when needed.
- Android host → Android agent: executes via · Default Android interaction uses the native Kotlin agent.
- Android agent → Protocol: implements · Android agent messages and selectors align with the shared protocol.
- iOS host → iOS agent: executes via · iOS native element control uses the bundled XCTest agent.
- iOS agent → Protocol: implements · iOS agent behavior follows the shared protocol contract.
- CLI → Core runtime: inspects · CLI inspection and codegen interact with runtime concepts.
- CLI → Examples: supports · CLI tooling helps bootstrap and exercise example suites.
- Scaffolder → CLI: integrates · Project creation is part of the operational toolchain.
- Docs → Core runtime: documents · Docs explain runtime behavior, platform limits, and setup.
- Verification → Core runtime: verifies · Tests cover core runtime behavior and locator semantics.
- Verification → Android host: verifies · Tests cover Android parser and agent-mode flows.
- Verification → iOS host: verifies · Tests cover iOS parser and agent-mode flows.