# dtmilano/androidviewclient architecture

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

- Interactive diagram: https://gitdiagram.com/dtmilano/androidviewclient
- Repository: https://github.com/dtmilano/androidviewclient

## Overview

##### Project type and purpose
- It is a command-line / library tool written in Python that automates Android UI testing.
- It provides:
– ADB-based device communication (adbclient module)
– UI Hierarchy capture & parsing (uiautomatorhelper + dumpsys)
– Logical “ViewClient” abstractions for interacting with on-screen elements
– Script generation (“culebra” scripts) and Robot Framework wrappers
– Concurrency support for multiple devices

##### File structure
- **src/com/dtmilano/android** – core Python packages:
– **adb**: low-level ADBClient, dumpsys, key-mapping
– **uiautomator**: UIAutomatorHelper wrapper for UIAutomator server
– **viewclient**: ViewClient Java/Python code that parses and manipulates UI trees
– **robotframework**: integration layer for Robot Framework
– Helper modules: controlpanel, plot, distance, concertina, kato
- **tools/** and **examples/** – CLI entry scripts & end-user examples
- **setup.py** / **build.xml** – packaging and publishing; defines console entrypoints
- **docs/** / **sphinx/** / **uml/** – documentation and UML artifacts
- **tests/** / **tst/** – unit / integration tests, resource mocks

##### README for additional insights
- Confirms pure-Python design (>= Python 3.6)
- Highlights ADB usage, UI Automator Hierarchy vs. image-based comparison
- Mentions forthcoming Kotlin backend (out of scope here)

##### Main components and their relationships
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. User / CLI layer                                                  │
│   • culebra, tools/ scripts, examples scripts → Python entrypoints    │
├─────────────────────────────────────────────────────────────────────────┤
│ 2. Core-Library layer                                                │
│   • adbclient module (spawns ADB subprocesses)                       │
│   • uiautomatorhelper (talks to on-device UIAutomator server)        │
│   • viewclient (parses UI XML, presents tree API)                    │
│   • script-generation engine (culebra)                                │
│   • optional robotframework adapter                                   │
├─────────────────────────────────────────────────────────────────────────┤
│ 3. External-Integration layer                                         │
│   • Local ADB server / daemon                                         │
│   • USB / TCP/IP → Android devices / emulators                        │
│   • On-device UIAutomator (Java)                                      │
├─────────────────────────────────────────────────────────────────────────┤
│ 4. Persistence & CI                                                     │
│   • GitHub Actions workflows (pythonpublish.yml)                      │
│   • Packaging: PyPI (setup.py) / Ant (build.xml)                      │
└─────────────────────────────────────────────────────────────────────────┘

Relationships & interactions:
– CLI layer invokes functions in the Core-Library.
– Core-Library → spawns ADB subprocesses → communicates with ADB server.
– ADB server ↔ Android device/emulator.
– On-device UIAutomator service returns UI hierarchy → Core-Library.
– Core-Library processes hierarchy, issues input commands back via ADB.
– Script-generation engine writes reusable Python test scripts.
– RobotFramework adapter calls Core-Library APIs for keyword-driven tests.

##### Architectural patterns & design principles
- **Modular layering**: clear separation of CLI, core logic, and external integration
- **Adapters**: ADBClient adapter, UIAutomator helper adapter, RobotFramework adapter
- **Factory / generator**: “culebra” script/ code generator
- **Concurrency**: thread-pool or async support for multi-device operation
- **Test coverage**: heavy use of unit/integration tests under `tests/` and `tst/`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% 1. CLI Layer
    subgraph "1. User / CLI Layer"
        direction TB
        culebra_cli["culebra (CLI)"]:::cli
        dump_cli["dump (CLI)"]:::cli
        examples["examples/"]:::cli
    end

    %% 2. Core-Library Layer
    subgraph "2. Core-Library Layer"
        direction TB
        subgraph "ADB Communication"
            direction TB
            AdbClient["adbclient.py"]:::pythonComp
            Dumpsys["dumpsys.py"]:::pythonComp
            AndroidKeyMap["androidkeymap.py"]:::pythonComp
        end
        subgraph "UI Hierarchy Capture & Parsing"
            direction TB
            UIAutomatorHelper["uiautomatorhelper.py"]:::pythonComp
            UAUtils["utils.py"]:::pythonComp
        end
        subgraph "ViewClient Abstraction"
            direction TB
            ViewClientPy["viewclient.py"]:::pythonComp
            ViewClientJava["ViewClient.java"]:::pythonComp
        end
        subgraph "Script Generation Engine"
            direction TB
            CodeGen["code_generator.py"]:::pythonComp
            Culebron["culebron.py"]:::pythonComp
            ToolsCulebra["tools/culebra"]:::pythonComp
        end
        subgraph "RobotFramework Adapter"
            direction TB
            RobotAdapter["viewclientwrapper.py"]:::pythonComp
        end
        Concurrency["Concurrency (threads/async)"]:::pythonComp
    end

    %% 3. External-Integration Layer
    subgraph "3. External-Integration Layer"
        direction TB
        ADBServer["ADB Server"]:::external
        Device["Android Device / Emulator"]:::external
        UIAutomatorService["UIAutomator Service"]:::external
    end

    %% 4. Persistence & CI/CD
    subgraph "4. Persistence & CI/CD"
        direction TB
        Setup["setup.py"]:::ci
        BuildXML["build.xml"]:::ci
        GHActions["pythonpublish.yml"]:::ci
    end

    %% Connections
    culebra_cli -->|"invokes"| CodeGen
    dump_cli -->|"invokes"| UIAutomatorHelper
    examples -->|"demo scripts"| ViewClientPy

    CodeGen -->|"uses"| ViewClientPy
    ViewClientPy -->|"parses XML"| UAUtils
    UIAutomatorHelper -->|"shell dump-uiautomator"| AdbClient
    AdbClient -->|"spawns adb"| ADBServer
    ADBServer -->|"communicates via USB/TCP"| Device
    Device -->|"runs"| UIAutomatorService
    UIAutomatorService -->|"returns UI hierarchy"| UIAutomatorHelper
    AdbClient -->|"sends input commands"| Device

    RobotAdapter -->|"wraps Core APIs"| ViewClientPy
    Concurrency -.->|"async operations"| AdbClient

    Setup -->|"defines package"| CodeGen
    BuildXML -->|"Ant build"| CodeGen
    GHActions -->|"CI/CD workflow"| Setup

    %% Click Events
    click AdbClient "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/adb/adbclient.py"
    click Dumpsys "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/adb/dumpsys.py"
    click AndroidKeyMap "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/adb/androidkeymap.py"
    click UIAutomatorHelper "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/uiautomator/uiautomatorhelper.py"
    click UAUtils "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/uiautomator/utils.py"
    click ViewClientPy "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/viewclient.py"
    click ViewClientJava "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/viewclient/ViewClient.java"
    click CodeGen "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/code_generator.py"
    click Culebron "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/culebron.py"
    click ToolsCulebra "https://github.com/dtmilano/androidviewclient/tree/master/tools/culebra"
    click RobotAdapter "https://github.com/dtmilano/androidviewclient/blob/master/src/com/dtmilano/android/robotframework/viewclientwrapper.py"
    click culebra_cli "https://github.com/dtmilano/androidviewclient/tree/master/tools/culebra"
    click dump_cli "https://github.com/dtmilano/androidviewclient/tree/master/tools/dump"
    click examples "https://github.com/dtmilano/androidviewclient/tree/master/examples/"
    click Setup "https://github.com/dtmilano/androidviewclient/blob/master/setup.py"
    click BuildXML "https://github.com/dtmilano/androidviewclient/blob/master/build.xml"
    click GHActions "https://github.com/dtmilano/androidviewclient/blob/master/.github/workflows/pythonpublish.yml"

    %% Styles
    classDef pythonComp fill:#ADD8E6,stroke:#000
    classDef external fill:#90EE90,stroke:#000
    classDef cli fill:#FFA500,stroke:#000
    classDef ci fill:#DDA0DD,stroke:#000
```
