# guilhermelimait/thunderpass architecture

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

- Interactive diagram: https://gitdiagram.com/guilhermelimait/thunderpass
- Repository: https://github.com/guilhermelimait/thunderpass

## Overview

1. **What this repo is**
   ThunderPass is a single Android application, written in Kotlin with Jetpack Compose, that runs mostly on-device. Its core product loop is: discover nearby devices over Bluetooth LE, perform an authenticated encrypted exchange, store the encounter locally, and update the UI/widgets.

2. **Top-level runtime shape**
   The app starts in `MainActivity`, while `ThunderPassApplication` provides process-wide setup. A `BleService` runs as the long-lived foreground service that keeps scanning/advertising active. `BootReceiver` restarts that service after reboot so the Bluetooth presence layer survives device restarts.

3. **Main architectural boundary: Bluetooth encounter engine**
   The `ble/` package is the heart of the system. It contains the GATT client/server pair, rotating anonymous ID generation, encounter deduplication, nearby-device state tracking, and BLE payload encryption. This layer is responsible for the actual “Spark” flow between two phones and is separate from the UI and persistence layers.

4. **Encounter data flow**
   When two devices meet, the BLE layer establishes a short-lived secure session, exchanges profile cards, validates authenticity, and emits an encounter record. That result flows into the local database as an `Encounter`, and the app raises a notification / haptic feedback from the encounter event path. The same encounter is also surfaced in the passes/history screens and widgets.

5. **Local persistence**
   The app uses Room for local storage, with schemas checked in under `app/schemas`. The database contains at least three core entities: `Encounter`, `MyProfile`, and `PeerProfileSnapshot`, accessed via matching DAOs. The README indicates the database is encrypted with SQLCipher, with the passphrase protected via encrypted shared preferences, making local storage a security boundary rather than plain app storage.

6. **Profile and content management**
   The `data/` package contains app-specific content managers such as `BadgeManager` and `StickerManager`. These sit above the database and feed profile-related UI, achievements, and decorative/avatar content. They are part of the local game-like progression layer rather than the Bluetooth transport layer.

7. **Step/Volt subsystem**
   The `steps/` package isolates step-count based Volt earning. This is a separate input stream from Bluetooth: hardware activity recognition contributes passive daily progress, while Bluetooth encounters contribute “Spark” rewards. In the architecture diagram, this is a local sensor-derived subsystem feeding the same persistence/UI surface as encounter rewards.

8. **Pairing and device-to-device sync**
   The `security/` package handles multi-device ownership and sync. `DeviceGroupManager`, `PairedSyncManager`, and `PayloadSigner` implement manual pairing, authenticated sync, and signed payload exchange between a user’s own devices. This is distinct from stranger encounters: paired-device sync can move profile, badges, Volt balance, and encounter history, while keeping raw scan data and sensitive keys local.

9. **RetroAchievements integration**
   The `retro/` package is the only clear external network dependency. It contains Retrofit client/service code plus auth, caching, and repository layers for RetroAchievements profile data. This data is used to enrich the user’s own profile and peer encounter cards, but it is architecturally optional and separate from the offline-first Bluetooth flow.

10. **UI composition**
   The `ui/` package is a Compose-based presentation layer with screens for onboarding, home, profile, encounters, badges, shop, settings, device sync, and editor flows. `HomeViewModel` and `ProfileViewModel` bridge the UI to domain/state sources. Navigation is centralized in `Navigation.kt`, so the diagram should show the UI as a consumer of repositories/managers rather than as the owner of business logic.

11. **Widgets as a second presentation surface**
   The `widget/` package exposes Android home-screen widgets that mirror core app state: profile, encounter summary, and a toggle/status card. These widgets read from the same local state as the main UI and can control the scan service. They are an important architectural boundary because they provide read/write access without opening the app.

12. **Security and cryptographic concern separation**
   Even though cryptography is part of the Bluetooth exchange, the repo keeps the security primitives separated from transport and UI. `BleEncryption`, `RotatingIdManager`, `RotatingIdUtils`, and `PayloadSigner` indicate a layered design where identity, message signing, and session encryption are handled independently from rendering and storage.

13. **Assets, resources, and device-specific affordances**
   The repo includes Android resources for widgets, notifications, themes, launcher assets, and a background audio file. These are not central to the core data model, but they support the app’s experiential layer: encounter notifications, visual feedback, and branded UI.

14. **Operational/deployment boundary**
   There is no backend service in this repository; the only networked integration is RetroAchievements. Distribution is via APK/GitHub releases, and the GitHub Actions workflow is mainly build/release infrastructure rather than product runtime architecture. That makes the system fundamentally peer-to-peer plus local persistence.

15. **How to draw the diagram**
   A useful architecture diagram should center on: `BleService` and the `ble/` package in the middle; local Room/SQLCipher storage below; Compose UI, widgets, and view models on the client side; `security/` and `steps/` as supporting subsystems; and `retro/` as the only external API boundary. The boot receiver and foreground service are the lifecycle edges that keep the Bluetooth engine alive.

Main entry points: [`app/src/main/java/com/thunderpass/data/db/ThunderPassDatabase.kt`](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/ThunderPassDatabase.kt) (ThunderPass DB), [`app/src/main/java/com/thunderpass/BleService.kt`](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/BleService.kt) (BLE Service), [`app/src/main/java/com/thunderpass/ui/HomeScreen.kt`](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/HomeScreen.kt) (Compose Screens), [`app/src/main/java/com/thunderpass/security/PairedSyncManager.kt`](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/security/PairedSyncManager.kt) (Pairing Sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["App"]
  node_main_activity["Main Activity<br/>entry activity<br/>[MainActivity.kt]"]
  node_ble_service["BLE Service<br/>foreground service<br/>[BleService.kt]"]
  node_boot_receiver["Boot Receiver<br/>broadcast receiver<br/>[BootReceiver.kt]"]
end

subgraph group_ble["Bluetooth Engine"]
  node_ble_engine{{"BLE Engine<br/>peer exchange"}}
  node_gatt_pair["GATT Pair<br/>transport pair"]
  node_sync_gatt["Sync GATT<br/>paired transport"]
  node_identity_crypto["Identity & Crypto"]
  node_encounter_state["Encounter State<br/>state & dedup"]
end

subgraph group_data["Local Data"]
  node_encounter_db[("ThunderPass DB<br/>room database")]
  node_encounter_dao["Encounter DAO<br/>room dao<br/>[EncounterDao.kt]"]
  node_profile_dao["Profile DAO<br/>room dao<br/>[MyProfileDao.kt]"]
  node_peer_snapshot_dao["Peer DAO<br/>room dao"]
  node_content_mgrs["Content Managers<br/>app content<br/>[BadgeManager.kt]"]
end

subgraph group_security["Security & Sync"]
  node_pairing_sync["Pairing Sync<br/>device pairing"]
end

subgraph group_support["Sensors & Progress"]
  node_step_volt["Step Volt<br/>sensor rewards<br/>[StepVoltManager.kt]"]
end

subgraph group_presentation["Presentation"]
  node_home_vm["Home VM<br/>view model<br/>[HomeViewModel.kt]"]
  node_profile_vm["Profile VM<br/>view model"]
  node_navigation["Navigation<br/>compose nav<br/>[Navigation.kt]"]
  node_screens["Compose Screens<br/>ui screens<br/>[HomeScreen.kt]"]
  node_widgets["Widgets"]
end

subgraph group_external["External API"]
  node_retro_repo["Retro Repo<br/>network repository<br/>[RetroRepository.kt]"]
end

node_app -->|"starts UI"| node_main_activity
node_app -->|"provides setup"| node_ble_service
node_boot_receiver -->|"restarts"| node_ble_service
node_main_activity -->|"hosts"| node_navigation
node_ble_service -->|"runs"| node_ble_engine
node_ble_engine -->|"stranger flow"| node_gatt_pair
node_ble_engine -->|"paired flow"| node_sync_gatt
node_ble_engine -->|"secures"| node_identity_crypto
node_ble_engine -->|"tracks"| node_encounter_state
node_ble_engine -->|"stores encounters"| node_encounter_db
node_encounter_db -->|"exposes"| node_encounter_dao
node_encounter_db -->|"exposes"| node_profile_dao
node_encounter_db -->|"exposes"| node_peer_snapshot_dao
node_content_mgrs -->|"feeds"| node_profile_vm
node_pairing_sync -->|"uses"| node_sync_gatt
node_pairing_sync -->|"signs"| node_identity_crypto
node_step_volt -->|"updates"| node_encounter_db
node_retro_repo -->|"enriches"| node_profile_vm
node_home_vm -->|"feeds"| node_screens
node_profile_vm -->|"feeds"| node_screens
node_navigation -->|"routes to"| node_screens
node_screens -->|"mirrors"| node_widgets
node_widgets -->|"controls"| node_ble_service
node_ble_engine -->|"publishes state"| node_widgets
node_ble_engine -->|"feeds"| node_home_vm
node_ble_engine -->|"shares state"| node_pairing_sync

click node_app "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ThunderPassApplication.kt"
click node_main_activity "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/MainActivity.kt"
click node_ble_service "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/BleService.kt"
click node_boot_receiver "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/BootReceiver.kt"
click node_encounter_db "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/ThunderPassDatabase.kt"
click node_encounter_dao "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/dao/EncounterDao.kt"
click node_profile_dao "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/dao/MyProfileDao.kt"
click node_peer_snapshot_dao "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/dao/PeerProfileSnapshotDao.kt"
click node_content_mgrs "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/BadgeManager.kt"
click node_pairing_sync "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/security/PairedSyncManager.kt"
click node_step_volt "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/steps/StepVoltManager.kt"
click node_home_vm "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/HomeViewModel.kt"
click node_profile_vm "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/ProfileViewModel.kt"
click node_navigation "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/Navigation.kt"
click node_screens "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/HomeScreen.kt"
click node_widgets "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/widget/ThunderPassWidget.kt"
click node_retro_repo "https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/retro/RetroRepository.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_main_activity,node_ble_service,node_boot_receiver,node_retro_repo toneBlue
class node_ble_engine,node_gatt_pair,node_sync_gatt,node_identity_crypto,node_encounter_state toneAmber
class node_encounter_db,node_encounter_dao,node_profile_dao,node_peer_snapshot_dao,node_content_mgrs toneMint
class node_pairing_sync toneRose
class node_step_volt toneIndigo
class node_home_vm,node_profile_vm,node_navigation,node_screens,node_widgets toneTeal
```

## Components

### Runtime

App process, lifecycle, and long-lived service entrypoints.

- [App](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ThunderPassApplication.kt): application · Android application process and dependency setup. · `app/src/main/java/com/thunderpass/ThunderPassApplication.kt`
- [Main Activity](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/MainActivity.kt): entry activity · Primary activity that hosts the app UI. · `app/src/main/java/com/thunderpass/MainActivity.kt`
- [BLE Service](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/BleService.kt): foreground service · Long-lived service that keeps scan and advertise active. · `app/src/main/java/com/thunderpass/BleService.kt`
- [Boot Receiver](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/BootReceiver.kt): broadcast receiver · Restarts the Bluetooth service after device reboot. · `app/src/main/java/com/thunderpass/BootReceiver.kt`

### Bluetooth Engine

Peer discovery, encounter exchange, and BLE session management.

- **BLE Engine**: peer exchange · Core encounter engine for nearby discovery and secure exchange.
- **GATT Pair**: transport pair · Client/server endpoints for stranger encounters.
- **Sync GATT**: paired transport · Client/server endpoints for authenticated device-to-device sync.
- **Identity & Crypto**: crypto · Rotating IDs, payload encryption, and anonymous session identity.
- **Encounter State**: state & dedup · Nearby device tracking and encounter deduplication.

### Local Data

Encrypted local persistence and app-specific content managers.

- [ThunderPass DB](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/ThunderPassDatabase.kt): room database · Encrypted local database used as the persistence boundary. · `app/src/main/java/com/thunderpass/data/db/ThunderPassDatabase.kt`
- [Encounter DAO](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/dao/EncounterDao.kt): room dao · Persistence access for encounter records. · `app/src/main/java/com/thunderpass/data/db/dao/EncounterDao.kt`
- [Profile DAO](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/dao/MyProfileDao.kt): room dao · Persistence access for the local profile. · `app/src/main/java/com/thunderpass/data/db/dao/MyProfileDao.kt`
- [Peer DAO](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/db/dao/PeerProfileSnapshotDao.kt): room dao · Persistence access for cached peer profile snapshots. · `app/src/main/java/com/thunderpass/data/db/dao/PeerProfileSnapshotDao.kt`
- [Content Managers](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/data/BadgeManager.kt): app content · Badge and sticker managers that feed profile and progression UI. · `app/src/main/java/com/thunderpass/data/BadgeManager.kt`

### Security & Sync

Pairing, payload signing, and device-to-device sync.

- [Pairing Sync](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/security/PairedSyncManager.kt): device pairing · Manual pairing, signed payload exchange, and multi-device ownership sync. · `app/src/main/java/com/thunderpass/security/PairedSyncManager.kt`

### Sensors & Progress

Local sensor-derived rewards and progression inputs.

- [Step Volt](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/steps/StepVoltManager.kt): sensor rewards · Step-count based Volt earning from local motion signals. · `app/src/main/java/com/thunderpass/steps/StepVoltManager.kt`

### Presentation

Compose UI, view models, and widgets.

- [Home VM](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/HomeViewModel.kt): view model · Binds home screen state to app data sources. · `app/src/main/java/com/thunderpass/ui/HomeViewModel.kt`
- [Profile VM](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/ProfileViewModel.kt): view model · Binds profile screen state to app data sources and retro data. · `app/src/main/java/com/thunderpass/ui/ProfileViewModel.kt`
- [Navigation](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/Navigation.kt): compose nav · Centralized screen routing for the Compose UI. · `app/src/main/java/com/thunderpass/ui/Navigation.kt`
- [Compose Screens](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/ui/HomeScreen.kt): ui screens · Onboarding, home, profile, encounters, badges, shop, settings, and sync screens. · `app/src/main/java/com/thunderpass/ui/HomeScreen.kt`
- [Widgets](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/widget/ThunderPassWidget.kt): app widgets · Home-screen widgets that mirror and control core app state. · `app/src/main/java/com/thunderpass/widget/ThunderPassWidget.kt`

### External API

Optional networked integration outside the offline-first core.

- [Retro Repo](https://github.com/guilhermelimait/thunderpass/blob/main/app/src/main/java/com/thunderpass/retro/RetroRepository.kt): network repository · RetroAchievements auth, cache, and API-backed profile data. · `app/src/main/java/com/thunderpass/retro/RetroRepository.kt`

## Connections

- App → Main Activity: starts UI · Application process launches the main entry activity.
- App → BLE Service: provides setup · Application initializes process-wide components used by the service and UI.
- Boot Receiver → BLE Service: restarts · Boot receiver brings the foreground Bluetooth service back after reboot.
- Main Activity → Navigation: hosts · Main activity hosts the Compose navigation graph.
- BLE Service → BLE Engine: runs · Foreground service drives the encounter engine.
- BLE Engine → GATT Pair: stranger flow · The BLE engine uses the encounter GATT client/server pair for nearby exchanges.
- BLE Engine → Sync GATT: paired flow · The BLE engine also supports authenticated device sync transport.
- BLE Engine → Identity & Crypto: secures · Rotating IDs and encryption protect BLE session identity and payloads.
- BLE Engine → Encounter State: tracks · Nearby-device state and deduplication gate encounter emission.
- BLE Engine → ThunderPass DB: stores encounters · Completed encounters are written to local persistence.
- ThunderPass DB → Encounter DAO: exposes · Database exposes the encounter entity access path.
- ThunderPass DB → Profile DAO: exposes · Database exposes the local profile access path.
- ThunderPass DB → Peer DAO: exposes · Database exposes cached peer snapshot access path.
- Content Managers → Profile VM: feeds · Badge and sticker content enrich profile-oriented presentation state.
- Pairing Sync → Sync GATT: uses · Device-group pairing and sync ride on the authenticated sync transport.
- Pairing Sync → Identity & Crypto: signs · Signed payload exchange depends on security primitives.
- Step Volt → ThunderPass DB: updates · Sensor-derived progress is persisted alongside other local state.
- Retro Repo → Profile VM: enriches · Optional network profile data flows into profile presentation.
- Home VM → Compose Screens: feeds · Home view model provides state to Compose screens.
- Profile VM → Compose Screens: feeds · Profile view model provides state to Compose screens.
- Navigation → Compose Screens: routes to · Central navigation connects the major app screens.
- Compose Screens → Widgets: mirrors · Widgets reuse the same core state and actions exposed in the app.
- Widgets → BLE Service: controls · Widgets can toggle or surface the scan/service state.
- BLE Engine → Widgets: publishes state · Encounter outcomes are surfaced to the widget layer.
- BLE Engine → Home VM: feeds · Encounter and presence state drive the home experience.
- BLE Engine → Pairing Sync: shares state · Paired-device sync can exchange encounter and profile data.
