# liangzhengang/okble architecture

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

- Interactive diagram: https://gitdiagram.com/liangzhengang/okble
- Repository: https://github.com/liangzhengang/okble

## Overview

##### Main Components
- Demo Application (app Module): This is the user-facing Android application that demonstrates usage. It contains UI activities and calls into the library to perform BLE scanning, connecting, reading, writing, and iBeacon simulations.
- BLE Library (okble-lib Module): This module encapsulates all the core BLE operations. It is structured in packages for beacon management, device operations (scan, connect, read/write, notify), permission handling, server side (advertising and simulating peripheral behavior) and client side (central scanning/communication).
- Android BLE Framework: This represents the native Android Bluetooth APIs (both BLE Central and Peripheral APIs) that are abstracted by the library.
- External Dependencies & Tools: Include Gradle build system, dynamic permissions (for Android API 23+), and possibly external utilities (like for logging or UUID utilities).

##### Relationships and Interactions
- The Demo App (app module) interacts with the okble-lib library through public APIs. For example, the app initiates a scan (via OKBLEScanManager), connects to devices (via OKBLEDevice and its implementations), and triggers various BLE operations.
- The okble-lib module exposes various classes (such as OKBLEDeviceImp, OKBLEBeaconScanManager, OKBLEAdvertiseManager, OKBLEServerDeviceImp, and managers for beacon and peripheral simulation) which internally coordinate with the core Android BLE APIs.
- Callbacks and listener interfaces appear throughout the code (for scan results, operation success/failure, notifications) to handle asynchronous communication. These should be visually represented to show that the app registers listeners and the library, after executing BLE operations, sends responses/events asynchronously.

##### Architectural Patterns and Design Principles
- Separation of concerns is evident by splitting the demo app and the BLE library.
- Use of callback interfaces for asynchronous event handling (e.g., DeviceScanCallBack, BLEOperation listeners, Server operation listeners) – show these as interfaces that decouple event production and consumption.
- Auto-reconnect and operation queuing: Indicate that the BLE device component uses an operation queue to manage BLE read/write/notification operations. This “queue management” can be shown as an internal component within the BLE device layer.

##### Technologies and Frameworks
- Android SDK (BLE APIs available from API level 18+).
- Gradle for building the app and library modules.
- Java as the programming language (based on package structure and file types).
- Standard Android components (Activities, Services if any, Broadcast Receivers for dynamic permissions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    DemoApp["Demo App (app Module)"]:::ui
    BLELib["BLE Library (okble-lib)"]:::lib
    AndroidBLE["Android BLE Framework"]:::external

    %% High-level interaction
    DemoApp -->|"calls"| BLELib

    %% Central Role Subgraph
    subgraph "Central Role"
        ScanMgr["OKBLEScanManager"]:::central
        DeviceInterface["OKBLEDevice"]:::central
        DeviceImp["OKBLEDeviceImp"]:::central
        OpQueue["Operation Queue"]:::central
        ScanCallback["DeviceScanCallBack"]:::central
        DeviceListener["OKBLEDeviceListener"]:::central
        BeaconMgr["Beacon Manager"]:::central
        BeaconEntities["Beacon Entities"]:::central
    end

    %% Peripheral Role Subgraph
    subgraph "Peripheral Role"
        AdvMgr["OKBLEAdvertiseManager"]:::peripheral
        AdvCallback["Advertise Callback"]:::peripheral
        AdvSettings["Advertise Settings"]:::peripheral
        ServerDevice["Server Device Impl"]:::peripheral
        ServerOp["Server Operation"]:::peripheral
    end

    %% Interactions from Demo App to BLE Library components
    DemoApp -->|"initiate_scan"| ScanMgr
    DemoApp -->|"device_connection"| DeviceInterface

    %% Internal BLE Library relationships (Central)
    DeviceInterface -->|"implemented_by"| DeviceImp
    DeviceImp -->|"uses"| OpQueue
    ScanMgr -->|"triggers"| ScanCallback
    DeviceImp -->|"notifies"| DeviceListener
    BeaconMgr -->|"manages"| BeaconEntities

    %% Central components calling Android BLE Framework
    ScanMgr -->|"calls_native"| AndroidBLE
    DeviceImp -->|"calls_native"| AndroidBLE

    %% Peripheral components interactions
    AdvMgr -->|"handles"| AdvCallback
    AdvMgr -->|"configures"| AdvSettings
    AdvMgr -->|"calls_peripheralAPI"| AndroidBLE
    AdvMgr -->|"supports"| ServerDevice
    ServerDevice -->|"executes"| ServerOp

    %% Callback relationships: asynchronous events from BLE Library back to Demo App
    ScanCallback ---|"scan_result"| DemoApp
    DeviceListener ---|"event_callback"| DemoApp

    %% Styling
    classDef ui fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef lib fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef central fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef peripheral fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#333,stroke-width:2px;

    %% Click Events
    click DemoApp "https://github.com/liangzhengang/okble/tree/master/app/src/main/java/com/a1anwang/okble_demo"
    click BLELib "https://github.com/liangzhengang/okble/tree/master/okble-lib/src/main/java/com/a1anwang/okble"
    click ScanMgr "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/client/scan/OKBLEScanManager.java"
    click DeviceInterface "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/client/core/OKBLEDevice.java"
    click DeviceImp "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/client/core/OKBLEDeviceImp.java"
    click OpQueue "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/common/BLEOperationQueue.java"
    click ScanCallback "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/client/scan/DeviceScanCallBack.java"
    click DeviceListener "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/client/core/OKBLEDeviceListener.java"
    click BeaconMgr "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/beacon/OKBLEBeaconManager.java"
    click BeaconEntities "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/beacon/OKBLEBeacon.java"
    click AdvMgr "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/server/advertise/OKBLEAdvertiseManager.java"
    click AdvCallback "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/server/advertise/OKBLEAdvertiseCallback.java"
    click AdvSettings "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/server/advertise/OKBLEAdvertiseSettings.java"
    click ServerDevice "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/server/core/OKBLEServerDeviceImp.java"
    click ServerOp "https://github.com/liangzhengang/okble/blob/master/okble-lib/src/main/java/com/a1anwang/okble/server/core/OKBLEServerOperation.java"
```
