How permissionlesstech/bitchat-android works
Project Type & Purpose
• This is a single-module Android client app implementing a secure, decentralized peer-to-peer messaging system over Bluetooth LE mesh and optional internet geohash channels (Nostr).
• It uses MVVM (Jetpack Compose + ViewModel) for UI, Kotlin Coroutines for async, BouncyCastle for crypto, Nordic BLE for mesh, OkHttp/Tor for internet channels, EncryptedSharedPreferences for storage.
High-Level File Structure
• app/src/main/java/com/bitchat/android
– BitchatApplication.kt (app init & DI)
– MainActivity.kt (UI host & permission gating)
– core (UI utilities), ui (Compose screens & UI managers), onboarding, protocol, services, mesh, noise (crypto), nostr (internet channel), net (Tor & OkHttp), geohash, identity, favorites, model, util.
• Third-party & config: build files, Gradle, Fastlane metadata, GitHub workflows, assets (geohash_picker.html, nostr_relays.csv).
Key README Insights
• MVVM pattern: ChatViewModel manages business logic.
• Core services: BluetoothMeshService, EncryptionService, BinaryProtocol.
• External integrations: Bluetooth LE mesh (fragmentation, routing, store-and-forward), Tor + Nostr relays for geohash channels.
• Persistence: EncryptedSharedPreferences & optional message retention.
– Presentation Layer
• Jetpack Compose UI (ChatScreen, Onboarding Screens, etc.)
• MainActivity
– Domain Layer
• ChatViewModel (MVVM entry point)
• OnboardingCoordinator, CommandProcessor, DataManager
– Services & Business Logic
• MessageRouter / PacketProcessor
• BluetoothMeshService (central + peripheral roles)
• NoiseSessionManager & EncryptionService (X25519/AES-GCM, Ed25519 signatures)
• NostrClient / NostrRelayManager (WebSocket via OkHttp + TorManager)
• StoreForwardManager, PeerManager, SecurityManager, PowerManager
– Persistence & Config
• EncryptedSharedPreferences (settings & identity)
• Local caches (SQLite or file assets for geohash, favorites)
– External Systems
• Bluetooth LE stack (Android BLE APIs / Nordic library)
• Internet (Tor network, Nostr relays)
• UI → ViewModel: user actions, commands (e.g., /join)
• ViewModel → Services: forward commands to MessageRouter, EncryptionService, NostrClient
• MessageRouter ↔ BluetoothMeshService: send/receive binary packets
• BluetoothMeshService ↔ Android BLE Hardware
• EncryptionService ↔ NoiseSessionManager: encrypt/decrypt payloads
• ViewModel ↔ EncryptedSharedPreferences: read/write settings & identity keys
• ViewModel ↔ NostrClient: subscribe/publish events over WebSocket
• TorManager ↔ OkHttpProvider: wrap HTTP traffic for Nostr
c. Architectural Patterns & Principles
• MVVM separation: UI / state / business logic
• Service-oriented within app: each feature (mesh, crypto, network) in its own service class
• Layered architecture: Presentation → Domain → Data/Services → External
• Dependency injection at Application startup
d. Key Technologies & Libraries
• Jetpack Compose, Material 3
• Kotlin Coroutines & Flow
• BouncyCastle (crypto primitives)
• Nordic BLE library (reliable BLE mesh)
• OkHttp & WebSockets (Nostr relay communication)
• Tor Manager (optional internet privacy)
• EncryptedSharedPreferences
• LZ4 (message compression)