# arz321/muse-protocol architecture

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

- Interactive diagram: https://gitdiagram.com/arz321/muse-protocol
- Repository: https://github.com/arz321/muse-protocol

## Overview

##### Project Type and Purpose
- This project is an Android mobile application whose purpose is to broadcast commands (via a Bluetooth protocol) to various smart toy devices (e.g., MuSe, LoveSpouse, Leten).
- The README indicates that the application is designed to send commands using different data representations (decimal, hexadecimal, or single bytes) to control toys.
- The “base” folder holding thousands of JSON files represents locally stored configuration or data (e.g., device details or protocol command mappings) that were extracted from an online database via provided URLs.

##### Analysis of the File Structure
- The “app” directory contains all Android-specific code and resources:
- app/src/main/java contains the core Java classes. For example, MainActivity.java is likely the entry point for the UI, while BleUtil.java and the BLEUtil class under the util package encapsulate Bluetooth and BLE command functionality.
- The “app/src/main/res” directory holds Android resources (layouts, mipmap images, values) with activity_main.xml being the UI’s layout.
- The AndroidManifest.xml file defines key app-level configurations.
- The “jniLibs” and “libs” directories include native libraries and third-party libraries (like bleUtil.jar) used for BLE functionalities, hinting at integration with lower-level native code.
- The “base” directory is filled with numerous JSON files. These are used to store protocol details or identifiers (as noted in the README) and act as a kind of local database to support the application’s functionality.
- Additional files at the root level (build.gradle, gradlew, settings.gradle, etc.) indicate standard Gradle-based build configuration.

a. Main Components:
- User Interface (UI) Layer: Represented by MainActivity and the associated layout (activity_main.xml). This is the point of interaction with the user where they input addresses, timing details, and commands.
- BLE Communication Module: Consists of the BleUtil classes (found in app/src/main/java/com/example/nirjon/bledemo4_advertising and the util subpackage) and the bleUtil.jar native library. This module is responsible for handling low-level Bluetooth/BLE interactions.
- Data Management/Local Database: The “base” folder (with its large collection of JSON files) should be depicted as the local data store that the application uses to lookup or validate toy device commands.
- Configuration and Build Infrastructure: Include the Gradle build scripts and project settings as supportive components (not central to run-time behavior but critical in the build and deployment pipeline).
- External Services/Endpoints: Although the app is primarily self-contained, the README mentions URLs for additional toy data and session details. You might include a component for the external API (e.g., the LeTen service) to illustrate where external data can be fetched.

b. Relationships and Data Flow:
- The UI Layer (MainActivity) accepts user inputs (such as device address, time delay, and command data) and passes these inputs to the BLE Communication Module.
- The BLE Communication Module (using BleUtil functions and libraries) processes these inputs and manages the communication with the toy devices.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: The application is divided into discrete layers—UI, business logic (BLE command broadcasting), and data management.
- Utilization of Native Libraries: Emphasize the integration of native code (found in jniLibs and bleUtil.jar) for performance-sensitive operations such as Bluetooth interactions.
- Modular Organization: The splitting of code into different packages (e.g., application logic vs. utility classes) demonstrates modular design, which is an architectural best practice.
- Testability: The existence of both androidTest and unit tests (in app/src/test and app/src/androidTest) suggests that testing is an integral part of the project design.

d. Key Technologies, Frameworks, and Libraries:
- Android SDK and Java for the mobile application.
- Gradle as the build system.
- Native libraries (JNI, bleUtil.jar) for handling specialized BLE operations.
- JSON for storing and managing local configuration and protocol data.

##### Final Recommendations
- Interface or abstraction boundaries (e.g., between the native library and Java code) are clearly shown.
- Given that much of the project’s functionality is tied to sending BLE commands and managing JSON-based protocol details, highlighting these interactions will help communicate both the complexity and the modular separation of responsibilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UI_MainActivity["UI/MainActivity"]:::uiComponent
        UI_Layout["UI Layout (activity_main.xml)"]:::uiComponent
    end

    %% BLE Communication Module
    subgraph "BLE Communication Module"
        BLE_BleUtil["BleUtil.java"]:::bleComponent
        BLE_BLEUtil["BLEUtil.java"]:::bleComponent
        BLE_Jar["Native Library (bleUtil.jar)"]:::bleComponent
        BLE_NativeLibs["JNI Libraries (jniLibs)"]:::bleComponent
    end

    %% Data Management / Local Database
    JSON_DB["JSON Data Store"]:::dataComponent

    %% External API / Service Endpoints
    External_API["External API Service"]:::externalComponent

    %% Configuration and Build Infrastructure
    subgraph "Configuration & Build"
        RootGradle["build.gradle"]:::configComponent
        AppGradle["app/build.gradle"]:::configComponent
        GradleProps["gradle.properties"]:::configComponent
        SettingsGradle["settings.gradle"]:::configComponent
    end

    %% Relationships
    UI_MainActivity -->|"sendsCommand"| BLE_BleUtil
    BLE_BleUtil -->|"utilizes"| BLE_BLEUtil
    BLE_BLEUtil -->|"integrates"| BLE_Jar
    BLE_BLEUtil -->|"integrates"| BLE_NativeLibs
    BLE_BLEUtil -->|"queries"| JSON_DB
    External_API -->|"updates"| JSON_DB

    %% Styles and Colors
    classDef uiComponent fill:#AED6F1,stroke:#1B4F72,stroke-width:2px
    classDef bleComponent fill:#F9E79F,stroke:#B9770E,stroke-width:2px
    classDef dataComponent fill:#A9DFBF,stroke:#1E8449,stroke-width:2px
    classDef configComponent fill:#F5B7B1,stroke:#C0392B,stroke-width:2px
    classDef externalComponent fill:#D7BDE2,stroke:#6C3483,stroke-width:2px

    %% Click Events
    click UI_MainActivity "https://github.com/arz321/muse-protocol/blob/master/app/src/main/java/com/example/nirjon/bledemo4_advertising/MainActivity.java"
    click UI_Layout "https://github.com/arz321/muse-protocol/blob/master/app/src/main/res/layout/activity_main.xml"
    click BLE_BleUtil "https://github.com/arz321/muse-protocol/blob/master/app/src/main/java/com/example/nirjon/bledemo4_advertising/BleUtil.java"
    click BLE_BLEUtil "https://github.com/arz321/muse-protocol/blob/master/app/src/main/java/com/example/nirjon/bledemo4_advertising/util/BLEUtil.java"
    click BLE_Jar "https://github.com/arz321/muse-protocol/blob/master/app/src/main/libs/bleUtil.jar"
    click BLE_NativeLibs "https://github.com/arz321/muse-protocol/tree/master/app/src/main/jniLibs"
    click JSON_DB "https://github.com/arz321/muse-protocol/tree/master/base/"
    click RootGradle "https://github.com/arz321/muse-protocol/blob/master/build.gradle"
    click AppGradle "https://github.com/arz321/muse-protocol/blob/master/app/build.gradle"
    click GradleProps "https://github.com/arz321/muse-protocol/blob/master/gradle.properties"
    click SettingsGradle "https://github.com/arz321/muse-protocol/blob/master/settings.gradle"
```
