This page introduces BitChat's architecture, design philosophy, and core components. It provides a high-level understanding of how the dual-transport mesh networking system operates and the principles that guide its implementation.
For detailed information about the intelligent routing between Bluetooth mesh and Nostr relays, see Dual Transport Architecture. For in-depth coverage of privacy features, ephemeral identities, and encryption layers, see Key Features and Privacy Model.
BitChat is a decentralized peer-to-peer messaging application that operates without central servers, phone numbers, or persistent accounts README.md5-6 It implements a dual-transport architecture that combines local Bluetooth Low Energy (BLE) mesh networking (for offline communication) with the internet-based Nostr protocol (for global reach) README.md17-18 The application is designed for scenarios ranging from everyday privacy-conscious messaging to disaster recovery and censorship-resistant communication WHITEPAPER.md15-18
The codebase is a native Swift application for iOS and macOS bitchat.xcodeproj/project.pbxproj82-90 Central coordination is managed by AppRuntime, which serves as the composition root, initializing core services and models used throughout the app bitchat/ViewModels/ChatViewModel.swift92-95
Sources: README.md1-30 WHITEPAPER.md15-18 bitchat.xcodeproj/project.pbxproj1-120
BitChat follows a layered MVVM architecture with a service-oriented design. The system is organized into functional layers that separate UI concerns from networking, protocol handling, and identity management.
The following diagram maps high-level system components to their corresponding code entities and shows how they interact.
Key architectural characteristics:
ChatViewModel acts as the central coordinator, implementing BitchatDelegate and TransportEventDelegate to bridge networking events to the UI bitchat/ViewModels/ChatViewModel.swift92-95MessageRouter performs intelligent transport selection, preferring BLE when available and falling back to Nostr README.md71-85 WHITEPAPER.md25-30Sources: bitchat/ViewModels/ChatViewModel.swift92-175 README.md71-89 WHITEPAPER.md32-62 bitchat/Protocols/BitchatProtocol.swift9-61
The application logic is decomposed into specialized coordinators and services held by the ChatViewModel bitchat/ViewModels/ChatViewModel.swift162-175
| Component | Purpose |
|---|---|
ChatOutgoingCoordinator | Manages the logic for sending messages across different contexts bitchat/ViewModels/ChatViewModel.swift168 |
PrivateChatManager | Handles private chat session lifecycle and message consolidation bitchat/ViewModels/ChatViewModel.swift164 |
UnifiedPeerService | Aggregates peer discovery from both mesh and favorites bitchat/ViewModels/ChatViewModel.swift165 |
MessageDeduplicationService | Prevents processing the same message multiple times via Bloom filters bitchat/ViewModels/ChatViewModel.swift167 |
CommandProcessor | Handles IRC-style slash commands like /nick or /msg bitchat/ViewModels/ChatViewModel.swift162 |
Sources: bitchat/ViewModels/ChatViewModel.swift162-175
BitChat routes messages through two independent transport layers depending on availability README.md17
The mesh network enables direct peer-to-peer communication within Bluetooth range. It supports multi-hop relaying (up to 7 hops) to extend coverage without internet access README.md32-35 Security is provided by the Noise Protocol (XX handshake) for end-to-end encryption WHITEPAPER.md71-74 The binary protocol is optimized for BLE MTU constraints bitchat/Protocols/BitchatProtocol.swift15-18
Nostr transport provides global reach via a distributed network of relays README.md44-46 It uses geohash coordinates to define geographic chat rooms at various precisions, from city blocks to entire regions README.md63-67
The MessageRouter implements automatic transport selection. It prefers local Bluetooth for its superior privacy and offline nature but falls back to Nostr if the recipient is reachable via the relay network README.md71-85
For detailed routing logic, see Dual Transport Architecture.
Sources: README.md30-90 WHITEPAPER.md23-30 bitchat/Protocols/BitchatProtocol.swift15-30
The following diagram traces a message from user input to its transmission.
Key decision points:
XX for BLE WHITEPAPER.md71-74 or NIP-17 for Nostr README.md47BitchatPacket bitchat/Protocols/BitchatProtocol.swift12-22Sources: README.md71-89 WHITEPAPER.md71-84 bitchat/ViewModels/ChatViewModel.swift162-175 bitchat/Protocols/BitchatProtocol.swift15-30
For details on the identity system and geohash privacy, see Key Features and Privacy Model.
Sources: README.md15-26 bitchat/ViewModels/ChatViewModel.swift39-44 WHITEPAPER.md15-28
| Channel Type | Transport | Scope |
|---|---|---|
Mesh (#bluetooth) | BLE | Local Multi-hop (up to 7 hops) README.md52-57 |
Location (e.g., #dr5rs) | Nostr | Geohash (Block to Region) README.md63-67 |
Sources: README.md50-89
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.