# mubaraknative/mbcompass architecture

> Architecture diagram of the GitHub repository mubaraknative/mbcompass, 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/mubaraknative/mbcompass
- Repository: https://github.com/mubaraknative/mbcompass

## Overview

##### Main Components
- Mobile Application Module (app): This is the heart of the project and contains the Android-specific code.
- Business Logic / ViewModel: The “MainViewModel.kt” in the package is clearly the point of interaction between the UI and the underlying system logic, following an MVVM pattern.
- Sensor/Data Handling Layer: The “sensor” package, especially “AndroidSensorEventListener.kt”, processes raw sensor data (magnetometer and accelerometer) and performs the sensor fusion essential for obtaining accurate compass readings.
- Utility Functions: Under “utils”, you have helper utilities (e.g., “CardinalDirection.kt” and “ToDegree.kt”) to calculate and convert sensor data into meaningful angles and directions.
- Testing and Instrumentation: Both “app/src/test” and “app/src/androidTest” indicate that unit tests and UI/integration tests exist to validate functionality across components.
- Build & Deployment: The Gradle/Kotlin scripts, the Gradle wrapper, and the “fastlane” directory for Android metadata and screenshots reflect the continuous deployment and release management parts of the system.

##### Component Relationships and Interactions
- The UI layer (Jetpack Compose screens and fragments like “CompassApp.kt” and “MapFragment.kt”) interacts directly with the MainViewModel, forwarding user actions and receiving data updates.
- The ViewModel mediates between the UI and the sensor layer. It subscribes to sensor events (from AndroidSensorEventListener) to update the UI in real time.
- The sensor layer reads data from the device’s hardware sensors (magnetometer and accelerometer), processes via sensor fusion, and outputs computed directional data.
- Utility functions are used by both the ViewModel and sensor components to translate raw sensor readings into user-friendly information.
- Android resources provide the visual and functional UI elements, while the configuration and build scripts manage compilation, dependencies, and deployment.

##### Architectural Patterns and Key Technologies
- MVVM (Model-View-ViewModel): Evident with a dedicated MainViewModel managing the state between the sensor readings and UI.
- Jetpack Compose: Indicates the use of modern declarative UI building techniques.
- Android Lifecycle Awareness: The app is designed “with Android Lifecycle in mind” to enhance power efficiency, ensuring sensor listeners are active only as needed.
- Sensor Fusion: Combines data from multiple sensors (accelerometer and magnetometer) for more accurate compass readings.
- OpenStreetMap Integration: Found in the location module, it shows how external services or APIs are integrated into the application.

##### Final Recommendations
- Double-check that every major feature highlighted in the README (e.g., sensor fusion for accuracy, lifecycle management, and map integration) is represented.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Mobile Application Module
    subgraph "Mobile Application Module"
        %% UI Layer Subgraph
        subgraph "UI Layer"
            Nav["CompassNavGraph"]:::ui
            Compass["Compass Screen (CompassApp)"]:::ui
            Location["Location/Map Feature"]:::ui
        end
        BL["Business Logic (MainViewModel)"]:::bl
        Sensor["Sensor Handling (AndroidSensorEventListener)"]:::sensor
        Utils["Utility Functions (CardinalDirection, ToDegree)"]:::utils
        Resources["Android Resources"]:::resources
    end

    %% Testing Subgraph
    subgraph "Testing and Instrumentation"
        Unit["Unit Tests"]:::testing
        Inst["Instrumentation Tests"]:::testing
    end

    %% Build & Deployment Subgraph
    subgraph "Build & Deployment"
        Gradle["Gradle Build Scripts"]:::build
        Fastlane["Fastlane Deployment"]:::build
    end

    %% Component Relationships
    %% Sensor data flow
    Sensor -->|"sendsData"| BL
    %% Utility functions usage
    BL -->|"uses"| Utils
    Sensor -->|"uses"| Utils

    %% UI interactions with Business Logic (bidirectional)
    Nav -->|"triggers"| BL
    Compass -->|"triggers"| BL
    Location -->|"triggers"| BL
    BL -->|"updates"| Nav
    BL -->|"updates"| Compass
    BL -->|"updates"| Location

    %% Android Resources support UI rendering
    Resources -->|"renders"| Nav
    Resources -->|"renders"| Compass
    Resources -->|"renders"| Location

    %% Build & Deployment supporting Mobile Module
    Gradle -->|"builds"| BL
    Gradle -->|"builds"| Resources
    Fastlane -->|"deploys"| BL
    Fastlane -->|"deploys"| Resources

    %% Testing connected with Business Logic for validation
    BL -->|"tests"| Unit
    BL -->|"tests"| Inst

    %% Click Events
    click Nav "https://github.com/mubaraknative/mbcompass/blob/main/app/src/main/java/com/mubarak/mbcompass/ui/CompassNavGraph.kt"
    click Compass "https://github.com/mubaraknative/mbcompass/blob/main/app/src/main/java/com/mubarak/mbcompass/ui/compass/CompassApp.kt"
    click Location "https://github.com/mubaraknative/mbcompass/tree/main/app/src/main/java/com/mubarak/mbcompass/ui/location"
    click BL "https://github.com/mubaraknative/mbcompass/blob/main/app/src/main/java/com/mubarak/mbcompass/MainViewModel.kt"
    click Sensor "https://github.com/mubaraknative/mbcompass/blob/main/app/src/main/java/com/mubarak/mbcompass/sensor/AndroidSensorEventListener.kt"
    click Utils "https://github.com/mubaraknative/mbcompass/tree/main/app/src/main/java/com/mubarak/mbcompass/utils"
    click Resources "https://github.com/mubaraknative/mbcompass/tree/main/app/src/main/res"
    click Unit "https://github.com/mubaraknative/mbcompass/tree/main/app/src/test"
    click Inst "https://github.com/mubaraknative/mbcompass/tree/main/app/src/androidTest"
    click Gradle "https://github.com/mubaraknative/mbcompass/blob/main/app/build.gradle.kts"
    click Fastlane "https://github.com/mubaraknative/mbcompass/tree/main/fastlane"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef bl fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef sensor fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef utils fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef resources fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef testing fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
