# google/python-adb architecture

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

- Interactive diagram: https://gitdiagram.com/google/python-adb
- Repository: https://github.com/google/python-adb

## Overview

##### Main Components
a. ADB and Fastboot Core Modules:
- The “adb” directory holds the core implementation. It includes modules for:
– Command handling (adb_commands.py)
– Debugging functions (adb_debug.py, fastboot_debug.py)
– Protocol implementations (adb_protocol.py, fastboot.py, filesync_protocol.py)
– Cryptographic signing (sign_cryptography.py, sign_pycryptodome.py, sign_pythonrsa.py)
– Common utilities (common.py, common_cli.py) and USB-specific exception handling (usb_exceptions.py)
b. CLI Tools Build:
- The “make_tools.py” script packages the core modules into executables (adb.zip and fastboot.zip), which then provide the CLI tools (pyadb and pyfastboot). This layer is critical to show how users interact with the system at a command-line level.
c. Testing Suite:
- The “test” directory contains tests (e.g., adb_test.py, fastboot_test.py, common_stub.py) that validate the functionality of the modules.
d. Project Packaging and CI:
- Files like setup.py, .travis.yml, and tox.ini indicate build configuration, dependency management, and continuous integration settings.

##### Relationships and Interactions between Components
a. User Interface/CLI Layer:
- The executable zips (pyadb and pyfastboot) serve as entry points. They invoke the underlying functions and classes in the adb modules.
b. Library/API Layer:
- For developers, the library exposes functionality (via classes like AdbCommands) that encapsulate USB communications, command execution, and device interactions.
c. Cryptography Layer:
- The signing modules (sign_cryptography, etc.) integrate with the API’s authentication requirements (especially for devices that need verified connections).
d. USB Communication:
- The core modules interface with external dependencies (libusb1 and python-libusb1) to establish and maintain USB communications with Android devices.
e. Testing & CI:
- The test directory ensures stability and expected behavior; CI files handle automated testing and integration.

##### Architectural Patterns and Design Principles
a. Modularity: The code cleanly separates protocol-specific logic (ADB vs. Fastboot), cryptography, and common utilities.
b. Layering: There is a clear distinction between the CLI interface, underlying library/API, and the hardware communication layer.
c. Reusability: The library is designed to be imported and used in other Python code (see usage examples), demonstrating good API design practices.
d. Direct Communication: Unlike traditional ADB daemons, this project opens a direct command channel to the device, which is a unique design decision that should be noted.

##### Relevant Technologies, Frameworks, and Libraries
- Python (both Python 2 and Python 3 compatibility as noted in the README)
- libusb1 (and python-libusb1 for USB communications)
- Cryptographic libraries (py-cryptography, python-rsa, and optionally M2Crypto)
- CI tools (Travis CI, as deduced from .travis.yml) and test frameworks for automated testing.

##### Summary
- The hierarchy from the CLI interface to the core library, then down to hardware-level communication.
- The modular separation of ADB and Fastboot functionalities.
- External interactions (with USB libraries, cryptographic libraries, and Android devices).
- How testing and CI support the development lifecycle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Tools Layer
    subgraph "CLI Tools"
        CLI1("pyadb Tool"):::cli
        CLI2("pyfastboot Tool"):::cli
    end

    %% Core Library/API Layer
    subgraph "Core Library/API"
        CMD("ADB Command Handling"):::core
        DBG1("ADB Debugging"):::core
        DBG2("Fastboot Debugging"):::core
        PROT1("ADB Protocol Implementation"):::core
        PROT2("Fastboot Protocol Implementation"):::core
        PROT3("FileSync Protocol"):::core
        COMMON1("Common Utility (common.py)"):::core
        COMMON2("CLI Support (common_cli.py)"):::core
        USBEX("USB Exception Handling"):::core
    end

    %% Cryptography/Signing Layer
    subgraph "Cryptography/Signing"
        CRYPTO1("Sign Cryptography"):::crypto
        CRYPTO2("Sign Pycryptodome"):::crypto
        CRYPTO3("Sign PythonRSA"):::crypto
    end

    %% USB Communication Layer
    subgraph "USB Communication Layer"
        USB("USB Communication"):::usb
    end

    %% Build & Packaging/CI Layer
    subgraph "Build & Packaging/CI"
        BUILD("Build Tools (make_tools.py)"):::packaging
        SETUP("Package Setup (setup.py)"):::packaging
        TRAVIS("Travis CI Config (.travis.yml)"):::packaging
        TOX("Tox Configuration (tox.ini)"):::packaging
    end

    %% Testing Suite Layer
    subgraph "Testing Suite"
        TEST1("ADB Tests"):::testing
        TEST2("Fastboot Tests"):::testing
        TEST3("Common Stub Tests"):::testing
    end

    %% Relationships from CLI Tools to Core Library/API
    CLI1 -->|"invokes"| CMD
    CLI1 -->|"invokes"| PROT1
    CLI2 -->|"invokes"| PROT2

    %% Relationships within Core Library/API to External Layers
    CMD -->|"USBcomms"| USB
    CMD -->|"authenticates"| CRYPTO1
    PROT2 -->|"authenticates"| CRYPTO2
    DBG2 -->|"authenticates"| CRYPTO3

    %% Relationships: Testing Suite tests components in Core Library/API
    TEST1 -->|"tests"| CMD
    TEST2 -->|"tests"| PROT2
    TEST3 -->|"tests"| COMMON1

    %% Relationships: Build & Packaging produces CLI Tools
    SETUP -->|"configures"| BUILD
    TRAVIS -->|"triggers"| BUILD
    TOX -->|"triggers"| BUILD
    BUILD -->|"packages"| CLI1
    BUILD -->|"packages"| CLI2

    %% Click Events
    click CMD "https://github.com/google/python-adb/blob/master/adb/adb_commands.py"
    click DBG1 "https://github.com/google/python-adb/blob/master/adb/adb_debug.py"
    click DBG2 "https://github.com/google/python-adb/blob/master/adb/fastboot_debug.py"
    click PROT1 "https://github.com/google/python-adb/blob/master/adb/adb_protocol.py"
    click PROT2 "https://github.com/google/python-adb/blob/master/adb/fastboot.py"
    click PROT3 "https://github.com/google/python-adb/blob/master/adb/filesync_protocol.py"
    click CRYPTO1 "https://github.com/google/python-adb/blob/master/adb/sign_cryptography.py"
    click CRYPTO2 "https://github.com/google/python-adb/blob/master/adb/sign_pycryptodome.py"
    click CRYPTO3 "https://github.com/google/python-adb/blob/master/adb/sign_pythonrsa.py"
    click COMMON1 "https://github.com/google/python-adb/blob/master/adb/common.py"
    click COMMON2 "https://github.com/google/python-adb/blob/master/adb/common_cli.py"
    click USBEX "https://github.com/google/python-adb/blob/master/adb/usb_exceptions.py"
    click BUILD "https://github.com/google/python-adb/blob/master/make_tools.py"
    click SETUP "https://github.com/google/python-adb/blob/master/setup.py"
    click TRAVIS "https://github.com/google/python-adb/blob/master/.travis.yml"
    click TOX "https://github.com/google/python-adb/blob/master/tox.ini"
    click TEST1 "https://github.com/google/python-adb/blob/master/test/adb_test.py"
    click TEST2 "https://github.com/google/python-adb/blob/master/test/fastboot_test.py"
    click TEST3 "https://github.com/google/python-adb/blob/master/test/common_stub.py"

    %% Styles
    classDef cli fill:#a8e6cf,stroke:#56ab2f,stroke-width:2px;
    classDef core fill:#c9daf8,stroke:#0b5394,stroke-width:2px;
    classDef crypto fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
    classDef usb fill:#ffe0b2,stroke:#f57c00,stroke-width:2px;
    classDef packaging fill:#f4cccc,stroke:#d9534f,stroke-width:2px;
    classDef testing fill:#d9ead3,stroke:#265727,stroke-width:2px;
```
