This document provides a high-level introduction to the BitChat codebase architecture, covering the application's core purpose, architectural patterns, and major subsystems. It serves as an entry point for understanding how BitChat's components interact to provide decentralized mesh messaging.
For details on the dual transport system, see Dual Transport Architecture. For privacy features and identity management, see Key Features and Privacy Model. For implementation details of specific subsystems, refer to sections 2-11.
Sources: README.md1-126 WHITEPAPER.md1-310
BitChat is a decentralized peer-to-peer messaging application for iOS and macOS that operates without central servers, accounts, or phone numbers. It combines two complementary transport mechanisms:
The application is designed for censorship-resistant communication in scenarios where internet connectivity is unavailable, untrustworthy, or heavily monitored, such as protests, natural disasters, or remote areas.
Sources: README.md3-30 WHITEPAPER.md9-29
BitChat follows a strict MVVM (Model-View-ViewModel) architecture with a centralized service layer. The pattern enforces separation of concerns between UI rendering (SwiftUI Views), business logic (ViewModels), and platform services (Service Layer).
Architecture Components
| Layer | Key Classes | Responsibility |
|---|---|---|
| Entry Point | BitchatApp | App lifecycle, service initialization, scene management |
| View | ContentView, AppInfoView | SwiftUI UI rendering, user interaction |
| ViewModel | ChatViewModel | State management, business logic coordination |
| Service | BLEService, NostrTransport, NoiseEncryptionService | Transport, encryption, identity, persistence |
| Model | BitchatMessage, BitchatPacket, BitchatPeer | Data structures |
Sources: README.md31-93 Diagram 1 from high-level overview
ChatViewModel is the primary coordinator with an importance score of 386.84 (highest in the codebase). It manages:
publicMessages, privateChats)LocationChannelManager.selectedChannel)MessageRouterNoiseEncryptionServiceFavoritesPersistenceServiceSources: Diagram 1 from high-level overview, bitchat/Views/AppInfoView.swift1-292 (references ViewModel pattern)
The transport layer implements a dual-stack architecture abstracted behind MessageRouter:
Transport Selection Logic:
MessageRouter.outboxfavoriteStatusChanged notificationSources: Diagram 2 from high-level overview, README.md74-92
The cryptography stack is built on the Noise Protocol Framework with a 3-layer identity model:
Identity Components:
| Component | Type | Purpose | Storage |
|---|---|---|---|
PeerID | 8-byte truncated hash | Network-level routing, privacy through rotation | Ephemeral |
| Noise Static Key | Curve25519 keypair | End-to-end encryption, persistent identity | Keychain |
| Ed25519 Signing Key | Ed25519 keypair | Message authentication, announcements | Keychain |
| Fingerprint | SHA-256 hash | Out-of-band verification | Derived |
| Petname | String | User-assigned nickname | Encrypted cache |
TrustLevel | Enum | .unknown, .verified, .trusted | Encrypted cache |
Sources: Diagram 3 from high-level overview, WHITEPAPER.md71-105
BitChat implements a four-layer protocol stack as defined in the whitepaper:
Protocol Specification:
Noise_XX_25519_ChaChaPoly_SHA256BitchatPacket with fixed 13-byte headerSources: WHITEPAPER.md30-68 WHITEPAPER.md162-242 Diagram 5 from high-level overview
BitChat supports two channel types with different transport and scope characteristics:
Channel Characteristics:
| Channel | ID Format | Transport | Scope | Persistent ID |
|---|---|---|---|---|
mesh | #bluetooth | BLE mesh | Multi-hop local | No |
block | #dr5rsj7 (7 chars) | Nostr | ~153m | Per-geohash derived key |
neighborhood | #dr5rs (6 chars) | Nostr | ~1.2km | Per-geohash derived key |
city | #dr5r (5 chars) | Nostr | ~4.9km | Per-geohash derived key |
province | #dr5 (4 chars) | Nostr | ~156km | Per-geohash derived key |
region | #dr (2 chars) | Nostr | ~5000km | Per-geohash derived key |
Sources: Diagram 4 from high-level overview, README.md53-73
The message processing pipeline handles deduplication, routing, and UI updates:
Deduplication Strategies:
Batching Rationale: Public messages use 150ms batching to prevent UI thrashing during high-volume mesh broadcasts. Private messages bypass batching for immediate delivery.
Sources: Diagram 5 from high-level overview
The application coordinates multiple services with different background behavior requirements:
Service Coordination Details:
NetworkActivationService: Global kill switch that gates whether network services can startSources: Diagram 7 from high-level overview
The following subsystems are documented in detail in their respective sections:
| Section | Subsystem | Description |
|---|---|---|
| #2 | Core Application Architecture | MVVM pattern, service layer, dependency injection |
| #3 | Transport Layer | BLE mesh, Nostr relays, message routing, peer discovery |
| #4 | Cryptography and Security | Noise Protocol, session management, identity verification |
| #5 | User Interface | SwiftUI views, channel selection, peer lists |
| #6 | Location-Based Features | Geohash channels, GeoRelay discovery, per-geohash privacy |
| #7 | Protocol and Message Processing | Binary encoding, fragmentation, deduplication, commands |
| #8 | Data Models and State | Message/packet models, peer state, favorites persistence |
| #9 | Build System and Configuration | Xcode project, permissions, dependencies |
| #10 | Extensions and Integrations | Share extension, notifications, URL schemes |
| #11 | Testing and Quality Assurance | Mock infrastructure, integration tests, protocol validation |
Sources: Table of contents structure
Supported Platforms:
Build Requirements:
External Dependencies (Swift Package Manager):
Project Structure:
bitchat/ - Main application targetbitchatShareExtension/ - iOS share extensionbitchatTests/ - Unit and integration testsSources: README.md95-119
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.