# honeynet/droidbot architecture

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

- Interactive diagram: https://gitdiagram.com/honeynet/droidbot
- Repository: https://github.com/honeynet/droidbot

## Overview

##### Project Type and Purpose
- DroidBot is a full-stack, command-line driven testing framework for Android apps.
- It orchestrates devices/emulators via ADB, generates input events (random/scripted/ML-driven), monitors app state, and builds a UI Transition Graph (UTG).

##### File Structure
- Top-level entry points:
- start.py / droidbot/start.py – CLI launcher
- droidbot/app.py, droidbot/droidbot.py – core engine
- Adapters (droidbot/adapter): modular interfaces to external tools/protocols (ADB, minicap, logcat, JDWP, Accessibility, CV).
- Core modules:
- env_manager.py – sets up device environment (install APK, start services)
- input_manager.py / input_event.py – events dispatch
- input_policy*.py, rl/ – decision logic (random, scripted, RL)
- monitor.py / device_state.py – state capture (view hierarchy, screenshots, logs)
- utg.py – UTG construction
- Resources: built-in scripts, native libraries, APKs, styling for reports.
- Script samples: json templates for custom input sequences.

##### README Insights
- Dependencies: Python, Java/Android SDK, (optional) OpenCV
- Modes: random vs. GUI-model vs. CV mode vs. humanoid
- Outputs: logs, view hierarchy XML, screenshots, UTG graph

##### Main Components & Interactions

A. CLI Layer
- Component: `droidbot` CLI
- Responsibility: parse arguments, invoke core engine

B. Core Engine
- Modules: AppRunner (app.py), Environment Manager
- Flow:
1. env_manager installs APK on device/emulator
2. env_manager activates required services (accessibility, IME)

C. Adapter Layer
- Adapters: ADB, DroidBot IME, Minicap (screen capture), Logcat, JDWP, CV, Telnet, ProcessMonitor, etc.
- Role: send input events (`input_manager` → adapter), capture device state (`monitor` ← adapter)

D. Input Decision Layer
- Random Policy / Scripted Policy / RL Policy
- RL submodules: env (state↔observation), action, reward, config

E. Monitoring & State
- device_state: holds current UI tree, screenshot, logs
- monitor: continuously polls adapters for updates

F. UTG Builder & Reporter
- utg.py: builds nodes (UI states) and edges (events)
- resources/stylesheets + HTML templates: generate report

G. External Dependencies
- Android SDK (adb)
- Java VM (for APK instrumentation)
- (Optional) OpenCV for CV adapter

##### Architectural Patterns & Principles
- Modular adapter pattern: each device interaction protocol in its own class
- Pluggable input policies: easily swap random, script, RL
- Separation of concerns: environment setup, input generation, monitoring, reporting

##### Detail
- Modules and submodules (e.g., rl/env.py under “RL Policy”)
- Key resource directories (e.g., built-in scripts under resources/scripts)
- External integrations (Humanoid, optional OpenCV)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI and Core Engine
    subgraph "CLI & Core Engine"
        direction TB
        CLI["DroidBot CLI"]:::cli_core
        AppRunner["AppRunner"]:::cli_core
        EnvManager["Environment Manager"]:::cli_core
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        ADBAdapter["ADB Adapter"]:::adapters
        IMEAdapter["DroidBot IME Adapter"]:::adapters
        MinicapAdapter["Minicap Adapter"]:::adapters
        LogcatAdapter["Logcat Adapter"]:::adapters
        JDWPAdapter["JDWP Adapter"]:::adapters
        CVAdapter["CV Adapter"]:::adapters
        AppAdapter["DroidBot App Adapter"]:::adapters
        TelnetAdapter["Telnet Adapter"]:::adapters
        ProcessMonAdapter["Process Monitor Adapter"]:::adapters
        QEMUAdapter["QEMU Adapter"]:::adapters
        UserInputMon["User Input Monitor Adapter"]:::adapters
    end

    %% Input Decision Layer
    subgraph "Input Decision Layer"
        direction TB
        RandomScripted["Random/Scripted Policy"]:::policies
        RLPolicy["RL Policy"]:::policies
    end

    %% Input Manager & Events
    subgraph "Input Manager & Events"
        direction TB
        InputManager["Input Manager"]:::cli_core
        InputEvent["Input Event"]:::cli_core
    end

    %% Monitoring & State Capture
    subgraph "Monitoring & State"
        direction TB
        Monitor["Monitor"]:::monitoring
        DeviceState["Device State Store"]:::monitoring
        DeviceAbstraction["Device Abstraction"]:::monitoring
    end

    %% UTG Builder & Reporting
    subgraph "UTG & Reporting"
        direction TB
        UTGBuilder["UTG Builder"]:::monitoring
        ReportResources["Reporting Resources"]:::monitoring
        Scripts["Built-in Scripts"]:::monitoring
        Samples["Script Samples"]:::monitoring
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        AndroidSDK(("Android SDK")):::external
        JavaVM(("Java VM")):::external
        OpenCV(("OpenCV (optional)")):::external
    end

    %% Connections
    CLI -->|invokes| AppRunner
    CLI -->|invokes| EnvManager
    AppRunner -->|uses| EnvManager
    EnvManager -->|deploys APK to| ADBAdapter
    EnvManager -->|starts services on| IMEAdapter
    InputManager -->|sends events to| ADBAdapter
    InputManager -->|sends events to| IMEAdapter
    InputEvent -->|triggers| InputManager
    RandomScripted -->|decides events| InputEvent
    RLPolicy -->|decides events| InputEvent
    ADBAdapter -->|captures state| Monitor
    LogcatAdapter -->|captures logs| Monitor
    JDWPAdapter -->|captures state| Monitor
    MinicapAdapter -->|captures screenshots| Monitor
    CVAdapter -->|captures images| Monitor
    Monitor -->|updates| DeviceState
    Monitor -->|updates| DeviceAbstraction
    DeviceState -->|feeds| UTGBuilder
    UTGBuilder -->|generates| ReportResources
    ReportResources -->|styles| Scripts
    Scripts -->|templates| Samples

    AndroidSDK -.->|adb| ADBAdapter
    JavaVM -.->|instrumentation| AppAdapter
    OpenCV -.->|CV processing| CVAdapter

    %% Click Events
    click CLI "https://github.com/honeynet/droidbot/blob/master/droidbot/start.py"
    click AppRunner "https://github.com/honeynet/droidbot/blob/master/droidbot/app.py"
    click EnvManager "https://github.com/honeynet/droidbot/blob/master/droidbot/env_manager.py"
    click ADBAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/adb.py"
    click MinicapAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/minicap.py"
    click LogcatAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/logcat.py"
    click JDWPAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/jdwp.py"
    click CVAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/cv.py"
    click IMEAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/droidbot_ime.py"
    click AppAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/droidbot_app.py"
    click TelnetAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/telnet.py"
    click ProcessMonAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/process_monitor.py"
    click QEMUAdapter "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/qemu.py"
    click UserInputMon "https://github.com/honeynet/droidbot/blob/master/droidbot/adapter/user_input_monitor.py"
    click RandomScripted "https://github.com/honeynet/droidbot/blob/master/droidbot/input_policy.py"
    click RLPolicy "https://github.com/honeynet/droidbot/blob/master/droidbot/rl/env.py"
    click InputManager "https://github.com/honeynet/droidbot/blob/master/droidbot/input_manager.py"
    click InputEvent "https://github.com/honeynet/droidbot/blob/master/droidbot/input_event.py"
    click Monitor "https://github.com/honeynet/droidbot/blob/master/droidbot/monitor.py"
    click DeviceState "https://github.com/honeynet/droidbot/blob/master/droidbot/device_state.py"
    click DeviceAbstraction "https://github.com/honeynet/droidbot/blob/master/droidbot/device.py"
    click UTGBuilder "https://github.com/honeynet/droidbot/blob/master/droidbot/utg.py"
    click ReportResources "https://github.com/honeynet/droidbot/blob/master/droidbot/resources/index.html"
    click Scripts "https://github.com/honeynet/droidbot/tree/master/droidbot/resources/scripts/"
    click Samples "https://github.com/honeynet/droidbot/tree/master/script_samples/"

    %% Styles
    classDef cli_core fill:#D0E6FF,stroke:#0366d6,color:#000;
    classDef adapters fill:#DFFFE0,stroke:#228B22,color:#000;
    classDef policies fill:#FFD8B1,stroke:#FF8C00,color:#000;
    classDef monitoring fill:#F0F0F0,stroke:#999,color:#000;
    classDef external fill:#F5EEF8,stroke:#A020F0,color:#000;
```
