# xiaocong/uiautomator architecture

> Architecture diagram of the GitHub repository xiaocong/uiautomator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xiaocong/uiautomator
- Repository: https://github.com/xiaocong/uiautomator

## Overview

##### Main components
- Client Side (Python Test Scripts & Applications): This is where users import the module (e.g., “from uiautomator import device as d”) to perform UI actions.
- Python API/Wrapper Layer (uiautomator Library): This layer includes the core API methods (e.g., click, swipe, dump, etc.), watchers, handlers, and selectors. It abstracts the “uiautomator” functionality.
- Communication Layer (JSON-RPC & adb Interface): The API translates Python method calls into JSON-RPC requests that talk to the uiautomator-jsonrpc-server, with adb serving as the connection bridge.
- Android Device Side (uiautomator-jsonrpc-server and underlying Android uiautomator framework): The device runs a dedicated JSON-RPC server (packaged as an APK and related JAR files in the libs folder), which executes commands on the device.
- External Dependencies & Environment: Include the Android SDK and adb-related configurations that enable communication with a physical device.

##### Relationships and interactions
- That the API layer translates these calls into JSON-RPC calls that are sent via the “adb” connection.
- JSON-RPC calls being received by the Android device’s uiautomator-jsonrpc-server, which in turn uses the native Android uiautomator framework to interact with the device’s UI.
- Optionally, show feedback/response flowing back from the device to the API layer and then to the client scripts.

##### Architectural patterns/design principles
- Layered architecture: distinct separation between the Python API wrapper, the communication layer (RPC over adb), and the Android side implementation.
- Abstraction and encapsulation: the library completely hides the JSON-RPC and adb complexities behind a user-friendly API.
- Modular design: tests, documentation, and bundled libraries (APKs and JARs) are well separated, indicating an emphasis on maintainability and extensibility.

##### Relevant technologies and frameworks
- Python (and its packaging via setup.py, setup.cfg, requirements.txt)
- Android testing framework (uiautomator)
- adb (Android Debug Bridge) as a connectivity tool
- JSON-RPC for communication between the Python layer and the device’s uiautomator server

##### Detailed component separation
- For the API/Wrapper layer, detail that methods (like “click”, “swipe”, etc.) are provided to the end user.
- Under the communication layer, mention that the API wraps the adb call to trigger a JSON-RPC call (like “deviceInfo” or “dump”) on the Android side.
- On the device, note that the uiautomator-jsonrpc-server is started from APKs and uses an underlying Java library set (the APK and JAR files in the libs directory) to execute commands.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Side"
        client["Client (Python Test Scripts)"]:::client
    end

    subgraph "Core Layers"
        api["Python API/Wrapper"]:::api
        comm["Communication Layer (JSON-RPC via adb)"]:::comm
        api -->|"translatesCalls"| comm
    end

    subgraph "Android Device Side"
        android["Android Device (uiautomator-jsonrpc-server)"]:::android
        ui["Android UI/Framework"]:::ui
        android -->|"executesCommands"| ui
        comm -->|"sendsJSON-RPC"| android
        ui -->|"feedbackResponses"| comm
    end

    client -->|"callsMethods"| api
    comm -->|"responseBack"| api
    api -->|"returnsResponse"| client

    subgraph "External Dependencies & Environment"
        dep1["setup.py"]:::dep
        dep2["setup.cfg"]:::dep
        dep3["requirements.txt"]:::dep
    end

    dep1 -->|"configures"| comm
    dep2 -->|"configures"| comm
    dep3 -->|"configures"| comm

    click client "https://github.com/xiaocong/uiautomator/blob/master/test/test_device.py"
    click api "https://github.com/xiaocong/uiautomator/blob/master/uiautomator/__init__.py"
    click comm "https://github.com/xiaocong/uiautomator/blob/master/test/test_jsonrpc.py"
    click android "https://github.com/xiaocong/uiautomator/tree/master/uiautomator/libs/"
    click dep1 "https://github.com/xiaocong/uiautomator/blob/master/setup.py"
    click dep2 "https://github.com/xiaocong/uiautomator/blob/master/setup.cfg"
    click dep3 "https://github.com/xiaocong/uiautomator/blob/master/requirements.txt"

    classDef client fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef api fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef comm fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef android fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef ui fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef dep fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
