How guilhermelimait/thunderpass works
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: ThunderPassDatabase.kt ThunderPass DB · BleService.kt BLE Service · HomeScreen.kt Compose Screens · PairedSyncManager.kt Pairing Sync
Components 22
Runtime
App process, lifecycle, and long-lived service entrypoints.
- App · Android application process and dependency setup.
app/src/main/java/com/thunderpass/ThunderPassApplication.kt - Main Activity · Primary activity that hosts the app UI.
app/src/main/java/com/thunderpass/MainActivity.kt - BLE Service · Long-lived service that keeps scan and advertise active.
app/src/main/java/com/thunderpass/BleService.kt - Boot 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 · Core encounter engine for nearby discovery and secure exchange.
- GATT Pair · Client/server endpoints for stranger encounters.
- Sync GATT · Client/server endpoints for authenticated device-to-device sync.
- Identity & Crypto · Rotating IDs, payload encryption, and anonymous session identity.
- Encounter State · Nearby device tracking and encounter deduplication.
Local Data
Encrypted local persistence and app-specific content managers.
- ThunderPass DB · Encrypted local database used as the persistence boundary.
app/src/main/java/com/thunderpass/data/db/ThunderPassDatabase.kt - Encounter DAO · Persistence access for encounter records.
app/src/main/java/com/thunderpass/data/db/dao/EncounterDao.kt - Profile DAO · Persistence access for the local profile.
app/src/main/java/com/thunderpass/data/db/dao/MyProfileDao.kt - Peer DAO · Persistence access for cached peer profile snapshots.
app/src/main/java/com/thunderpass/data/db/dao/PeerProfileSnapshotDao.kt - Content Managers · 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 · 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 · 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 · Binds home screen state to app data sources.
app/src/main/java/com/thunderpass/ui/HomeViewModel.kt - Profile VM · Binds profile screen state to app data sources and retro data.
app/src/main/java/com/thunderpass/ui/ProfileViewModel.kt - Navigation · Centralized screen routing for the Compose UI.
app/src/main/java/com/thunderpass/ui/Navigation.kt - Compose Screens · Onboarding, home, profile, encounters, badges, shop, settings, and sync screens.
app/src/main/java/com/thunderpass/ui/HomeScreen.kt - 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 · RetroAchievements auth, cache, and API-backed profile data.
app/src/main/java/com/thunderpass/retro/RetroRepository.kt
Connections 26
- 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.