# permissionlesstech/bitchat-android architecture

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

- Interactive diagram: https://gitdiagram.com/permissionlesstech/bitchat-android
- Repository: https://github.com/permissionlesstech/bitchat-android

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Mobile App"
        subgraph "UI Layer"
            MainActivity["MainActivity"]:::ui
            ChatScreen["ChatScreen"]:::ui
            OnboardingScreens["Onboarding Screens"]:::ui
        end
        subgraph "Domain Layer"
            ChatViewModel["ChatViewModel"]:::domain
            OnboardingCoordinator["OnboardingCoordinator"]:::domain
            CommandProcessor["CommandProcessor"]:::domain
            DataManager["DataManager"]:::domain
        end
        subgraph "Services Layer"
            MessageRouter["MessageRouter"]:::service
            PacketProcessor["PacketProcessor"]:::service
            BluetoothMeshService["BluetoothMeshService"]:::service
            NoiseSessionManager["NoiseSessionManager"]:::service
            EncryptionService["EncryptionService"]:::service
            NostrClient["NostrClient"]:::service
            NostrRelayManager["NostrRelayManager"]:::service
            TorManager["TorManager"]:::service
            OkHttpProvider["OkHttpProvider"]:::service
            StoreForwardManager["StoreForwardManager"]:::service
            PeerManager["PeerManager"]:::service
            SecurityManager["SecurityManager"]:::service
            PowerManager["PowerManager"]:::service
            GeohashChannelManager["GeohashChannelManager"]:::service
        end
        subgraph "Data & Persistence"
            SecureIdentityStateManager["SecureIdentityStateManager"]:::data
            FavoritesPersistenceService["FavoritesPersistenceService"]:::data
            EncryptedSharedPreferences["EncryptedSharedPreferences"]:::data
        end
    end

    subgraph "External Systems"
        BLEHardware["Bluetooth LE Stack"]:::external
        TorNetwork["Internet (Tor)"]:::external
        NostrRelays["Nostr Relays"]:::external
    end

    MainActivity -->|hosts UI| ChatScreen
    MainActivity -->|navigates| OnboardingScreens
    ChatScreen -->|user actions| ChatViewModel
    OnboardingScreens -->|user input| OnboardingCoordinator
    ChatViewModel -->|commands| CommandProcessor
    ChatViewModel -->|data| DataManager
    CommandProcessor -->|process| MessageRouter
    DataManager -->|store settings| SecureIdentityStateManager
    MessageRouter -->|route packet| PacketProcessor
    PacketProcessor -->|to BLE| BluetoothMeshService
    BluetoothMeshService -->|BLE API| BLEHardware
    BluetoothMeshService -->|store & forward| StoreForwardManager
    BluetoothMeshService -->|peer mgmt| PeerManager
    BluetoothMeshService -->|security| SecurityManager
    BluetoothMeshService -->|power mgmt| PowerManager
    EncryptionService -->|uses| NoiseSessionManager
    CommandProcessor -->|encrypt| EncryptionService
    ChatViewModel -->|preferences| SecureIdentityStateManager
    ChatViewModel -->|favorites| FavoritesPersistenceService
    ChatViewModel -->|geohash| GeohashChannelManager
    ChatViewModel -->|internet| NostrClient
    NostrClient -->|manage relays| NostrRelayManager
    NostrClient -->|WebSocket/OkHttp| OkHttpProvider
    OkHttpProvider -->|over Tor| TorManager
    NostrClient -->|publish/subscribe| NostrRelays
    TorManager -->|routes| TorNetwork

    click MainActivity "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/MainActivity.kt"
    click BitchatApplication "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/BitchatApplication.kt"
    click ChatScreen "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/ui/ChatScreen.kt"
    click OnboardingScreens "https://github.com/permissionlesstech/bitchat-android/tree/main/app/src/main/java/com/bitchat/android/onboarding/"
    click ChatViewModel "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/ui/ChatViewModel.kt"
    click OnboardingCoordinator "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/onboarding/OnboardingCoordinator.kt"
    click CommandProcessor "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/ui/CommandProcessor.kt"
    click DataManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/ui/DataManager.kt"
    click MessageRouter "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/services/MessageRouter.kt"
    click PacketProcessor "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/mesh/PacketProcessor.kt"
    click BluetoothMeshService "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/mesh/BluetoothMeshService.kt"
    click NoiseSessionManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/noise/NoiseSessionManager.kt"
    click EncryptionService "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/crypto/EncryptionService.kt"
    click NostrClient "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/nostr/NostrClient.kt"
    click NostrRelayManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/nostr/NostrRelayManager.kt"
    click TorManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/net/TorManager.kt"
    click OkHttpProvider "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/net/OkHttpProvider.kt"
    click StoreForwardManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/mesh/StoreForwardManager.kt"
    click PeerManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/mesh/PeerManager.kt"
    click SecurityManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/mesh/SecurityManager.kt"
    click PowerManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/mesh/PowerManager.kt"
    click SecureIdentityStateManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/identity/SecureIdentityStateManager.kt"
    click FavoritesPersistenceService "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/favorites/FavoritesPersistenceService.kt"
    click GeohashChannelManager "https://github.com/permissionlesstech/bitchat-android/blob/main/app/src/main/java/com/bitchat/android/geohash/LocationChannelManager.kt"

    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef domain fill:#d4edda,stroke:#155724,color:#155724
    classDef service fill:#fff3cd,stroke:#856404,color:#856404
    classDef data fill:#f0f0f0,stroke:#6c757d,color:#6c757d
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#383d41
```
