# nullc0rp/bluempos architecture

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

- Interactive diagram: https://gitdiagram.com/nullc0rp/bluempos
- Repository: https://github.com/nullc0rp/bluempos

## Overview

##### Main Components
- Mobile Device / Android App Container – This is the runtime environment where the mobile application is deployed.
- User Interface Layer – Represented by components like MainActivity, the UI packages (e.g., com.example.bluempos.ui and its themes), and Android layout files (activity_main.xml). This is where the user interacts with the simulated POS.
- BLE Module – The core component that handles Bluetooth Low Energy communication. Highlight the vulnerable GATT service where players can read the characteristic that initially returns “LOCKED” and then write the custom command (“SEND_FLAG_2”) to receive the flag.
- NFC Module – Although it’s a work-in-progress (flag for NFC APDU is “optional” in the README), include it as a planned component that can respond to ISO-DEP card interactions.
- Build and Configuration Tools – Represent the use of Gradle (with build.gradle.kts, gradle wrapper, etc.) and configuration files (e.g., AndroidManifest.xml) that manage dependencies and app settings.

##### Relationships and Interactions
- The Mobile Device contains the Android Application, which is composed of layered components: the UI layer interacts with the BLE and NFC modules.
- The BLE Module serves as an interface received commands from external clients (via tools like gatttool or nRF Connect) – representing an external connection entry.
- The UI layer communicates with (or displays outputs from) the BLE Module after processing commands.
- The NFC Module (future component) is depicted as an alternate input channel triggering its own flow.
- Optionally, indicate a testing path where the test suites (unit and instrumentation tests) target specific application modules.

##### Architectural Patterns and Technologies
- Separation of Concerns: Where UI, BLE/NFC modules, and business logic are clearly separated.
- Use of Gradle as the build automation tool.
- Android’s resource system (layouts, values, drawable, etc.) that define the app’s appearance and behavior.
- Call out specific technologies:
- Android SDK for the mobile platform
- BLE GATT profile to manage Bluetooth communications
- (Planned) NFC using IsoDep technology
- Testing frameworks supported by Android (JUnit, Espresso, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Android App Container"
        AppContainer["Android App Container"]:::container
        UI["UI Layer (MainActivity & Layouts)"]:::ui
        BLE["BLE Module (GATT Service Vulnerable)"]:::ble
        NFC["NFC Module (Planned: IsoDep Listener)"]:::nfc
        AppContainer --> UI
        AppContainer --> BLE
        AppContainer --> NFC
    end

    ExternalBLE["External BLE Tools (nRF Connect/gatttool)"]:::external
    ExternalBLE -->|"sends_command"| BLE
    UI -->|"updates_on_events"| BLE

    Build["Build & Config Tools (Gradle, AndroidManifest)"]:::build
    Build -->|"builds_app"| AppContainer

    Testing["Testing & Instrumentation (Unit & Instrumentation)"]:::testing
    Testing -->|"tests_app"| AppContainer

    click AppContainer "https://github.com/nullc0rp/bluempos/tree/master/app/"
    click UI "https://github.com/nullc0rp/bluempos/blob/master/app/src/main/java/com/example/bluempos/MainActivity.kt"
    click UI "https://github.com/nullc0rp/bluempos/tree/master/app/src/main/java/com/example/bluempos/ui/"
    click UI "https://github.com/nullc0rp/bluempos/blob/master/app/src/main/res/layout/activity_main.xml"
    click BLE "https://github.com/nullc0rp/bluempos/tree/master/app/src/main/java/com/example/bluempos/"
    click NFC "https://github.com/nullc0rp/bluempos/blob/master/app/src/main/res/xml/nfc_tech_filter.xml"
    click Testing "https://github.com/nullc0rp/bluempos/tree/master/app/src/androidTest/"
    click Testing "https://github.com/nullc0rp/bluempos/tree/master/app/src/test/"
    click Build "https://github.com/nullc0rp/bluempos/blob/master/app/build.gradle.kts"
    click Build "https://github.com/nullc0rp/bluempos/blob/master/app/src/main/AndroidManifest.xml"
    click Build "https://github.com/nullc0rp/bluempos/tree/master/gradle/"

    classDef container fill:#ffddcc,stroke:#333,stroke-width:2px;
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef ble fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef nfc fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef build fill:#d1d1e0,stroke:#333,stroke-width:2px;
    classDef testing fill:#f8d7da,stroke:#333,stroke-width:2px;
```
