# dingjikerbo/android-bluetoothkit architecture

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

- Interactive diagram: https://gitdiagram.com/dingjikerbo/android-bluetoothkit
- Repository: https://github.com/dingjikerbo/android-bluetoothkit

## Overview

##### Main Components
- Application/User Interface Layer (App Module):
– Located in the “app” directory, it includes all the Android activities (MainActivity, DeviceDetailActivity, TestActivity, etc.) and view components (PullRefreshListView, WaveView, etc.)
– This layer is responsible for presenting the UI and handling user interactions.

- Bluetooth Client & Core Logic (Library Module):
– Found in the “library” directory, this module holds the bulk of the Bluetooth functionality.
– Contains sub-components for:
▪ Connection Management: Classes in packages like “connect” (e.g., BleConnectManager, BleConnectDispatcher, etc.) deal with initiating and maintaining connections, retry strategies, and handling state changes.
▪ Device Scanning & Beacon Parsing: Packages “search” (including classes like BluetoothSearchManager, BluetoothSearcher, and Beacon classes) cover device discovery, scan request formulation, and parsing of beacon data.
▪ Communication & Data Transfer: Implementations for reading, writing, enabling notifications and indications (see methods like read(), write(), notify(), and unnotify()).
▪ Utility & Support: “utils” and “aidl” packages provide supportive functions (logging, proxy setups, byte conversion, AIDL interfaces for IPC, etc.) and the abstraction of raw Bluetooth API calls.
▪ Receiver & Listener Infrastructure: “receiver” packages contain classes that manage callbacks from Bluetooth events via listeners (BluetoothStateListener, BleConnectStatusListener, etc.)

- External Elements:
– Android OS and Bluetooth Stack: The system relies on native Android Bluetooth APIs.
– External Bluetooth Devices: The actual BLE devices with which the framework interacts.

##### Relationships and Interactions
- The UI components (activities and views) invoke operations on a singleton BluetoothClient instance (or ClientManager) that is responsible for coordinating interactions with the underlying library.
- The BluetoothClient (acting as a façade) triggers lower-level Bluetooth operations (connect, read, write, etc.) by delegating to various library components.
- Under the hood, asynchronous callbacks (e.g., BleConnectResponse, BleReadResponse) and event listeners are used to notify the application of operation results or state changes.
- In multi-process or service-based scenarios, AIDL interfaces define the contracts for inter-process communication.
- There is a clear separation between the presentation layer (UI in “app”) and the Bluetooth communication logic (in “library”) with well-defined APIs.

##### Architectural Patterns / Design Principles
- Modularization: The project is split into an “app” and “library” with a clear API boundary.
- Facade/Singleton: A single entry point (BluetoothClient) is recommended to manage Bluetooth interactions.
- Observer Pattern: Several listener interfaces (e.g., BluetoothStateListener, BleConnectStatusListener) are used to handle asynchronous events.
- Asynchronous Callback Mechanism: Operations such as connecting, reading, or writing use callback interfaces for handling success, failure, or timeout scenarios.
- Separation of Concerns: UI rendering, Bluetooth data processing, and hardware interaction are well separated.

##### Relevant Technologies/Frameworks
- Android Framework: Utilizing Android’s native Bluetooth APIs.
- Gradle: Build system files (build.gradle) indicate Gradle is used for project management.
- AIDL: Used for defining service interfaces and potential inter-process communication.
- Java: The primary programming language and standard Android development patterns.
- The use of listeners and callbacks throughout the library is central to its design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application/User Interface Layer
    subgraph "Application/User Interface Layer"
        A1["MainActivity"]:::ui
        A2["DeviceDetailActivity"]:::ui
        A3["TestActivity"]:::ui
        A4["UI Views (PullRefreshListView, WaveView)"]:::ui
    end

    %% Bluetooth Library Module
    subgraph "Bluetooth Library Module"
        B1["BluetoothClient (Facade)"]:::library
        B2["BluetoothClientImpl"]:::library

        subgraph "Framework Components"
            E["Connection Management (BleConnectManager,...)"]:::library
            F["Device Scanning (BluetoothSearchManager,...)"]:::library
            G["Beacon Parsing (BeaconParser, Beacon)"]:::library
            H["Communication & Data Transfer (Read/Write)"]:::library
            I1["Utility & Support"]:::library
            I2["AIDL Interfaces"]:::library
            J["Receivers & Listeners"]:::library
        end
    end

    %% External Systems
    K["Android OS Bluetooth Stack"]:::external
    L["External BLE Devices"]:::external

    %% Relationships between layers
    A1 -->|"invokes"| B1
    A2 -->|"invokes"| B1
    A3 -->|"invokes"| B1
    A4 -->|"triggers UI events to"| B1

    B1 -->|"delegates"| B2

    B1 --> E
    B1 --> F
    B1 --> G
    B1 --> H
    B1 --> I1
    B1 --> I2
    B1 --> J

    B1 -->|"calls native APIs"| K
    K -->|"communicates with"| L

    J -.->|"callback"| A1

    %% Styles
    classDef ui fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef library fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#1e8449,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/dingjikerbo/android-bluetoothkit/tree/master/app/src/main/java/com/inuker/bluetooth"
    click B1 "https://github.com/dingjikerbo/android-bluetoothkit/blob/master/library/src/main/java/com/inuker/bluetooth/library/BluetoothClient.java"
    click B2 "https://github.com/dingjikerbo/android-bluetoothkit/blob/master/library/src/main/java/com/inuker/bluetooth/library/BluetoothClientImpl.java"
    click E "https://github.com/dingjikerbo/android-bluetoothkit/tree/master/library/src/main/java/com/inuker/bluetooth/library/connect"
    click F "https://github.com/dingjikerbo/android-bluetoothkit/tree/master/library/src/main/java/com/inuker/bluetooth/library/search"
    click G "https://github.com/dingjikerbo/android-bluetoothkit/tree/master/library/src/main/java/com/inuker/bluetooth/library/beacon"
    click H "https://github.com/dingjikerbo/android-bluetoothkit/tree/master/library/src/main/java/com/inuker/bluetooth/library/connect/request"
    click I1 "https://github.com/dingjikerbo/android-bluetoothkit/tree/master/library/src/main/java/com/inuker/bluetooth/library/utils"
    click I2 "https://github.com/dingjikerbo/android-bluetoothkit/tree/master/library/src/main/aidl/com/inuker/bluetooth/library"
    click J "https://github.com/dingjikerbo/android-bluetoothkit/tree/master/library/src/main/java/com/inuker/bluetooth/library/receiver"
```
