How permissionlesstech/bitchat works
BitChat is a decentralized messaging app for iOS and macOS, combining offline Bluetooth mesh with internet-based Nostr relays. A user composes a message; routing prefers an available Bluetooth/Noise path, falls back to an encrypted Nostr envelope, or queues for later delivery. Location channels, synchronization, boards, and voice broaden that workflow. The graph follows documented capabilities and sampled references; some subsystem links are dashed where implementation wiring was not shown.
Main entry points: ChatViewModel.swift Chat coordination · NostrRelayManager.swift Nostr relays · MessageRouter.swift Message routing · BLEService.swift Bluetooth mesh
Components 24
App and conversations
- App shell
bitchat/BitchatApp.swift - Chat coordination
bitchat/ViewModels/ChatViewModel.swift - Conversation state
bitchat/App/ConversationStore.swift
Messaging and mesh
- Message model
localPackages/BitFoundation/Sources/BitFoundation/BitchatMessage.swift - Message routing
bitchat/Services/MessageRouter.swift - Transport configuration
bitchat/Services/TransportConfig.swift - Bluetooth mesh
bitchat/Services/BLE/BLEService.swift - Mesh receive
bitchat/Services/BLE/BLEReceivePipeline.swift - Binary packets
localPackages/BitFoundation/Sources/BitFoundation/BitchatPacket.swift - Gossip synchronization
bitchat/Sync/GossipSyncManager.swift - Store and forward
bitchat/Services/Courier/MessageOutboxStore.swift
Nostr and location
- Nostr relays
bitchat/Nostr/NostrRelayManager.swift - Nostr protocol
bitchat/Nostr/NostrProtocol.swift - Nostr inbound
bitchat/ViewModels/NostrInboundPipeline.swift - Geographic channels
bitchat/ViewModels/GeoChannelCoordinator.swift
Identity and security
- Identity state
bitchat/Identity/SecureIdentityStateManager.swift - Keychain storage
bitchat/Services/KeychainManager.swift - Noise sessions
bitchat/Noise/NoiseSessionManager.swift - Noise security rules
bitchat/Noise/NoiseSecurityConstants.swift
Community features
- Community boards
bitchat/Services/Board/BoardManager.swift - Group messaging
bitchat/Services/Groups/GroupProtocol.swift - Voice messaging
bitchat/Features/voice/PTTCaptureEngine.swift
Other components
- Chat user
- Nostr relay network
Connections 23
- Chat user → App shell: uses
README.md - App shell → Chat coordination: presents
- Chat coordination → Conversation state: updates
- Chat coordination → Message routing: routes
- Message routing → Transport configuration: selects transport
- Message routing → Bluetooth mesh: prefers Bluetooth
README.md - Message routing → Nostr relays: falls back
README.md - Message routing → Store and forward: queues messages
README.md - Chat coordination → Message model: composes
- Bluetooth mesh → Binary packets: transmits
- Bluetooth mesh → Mesh receive: receives packets
- Mesh receive → Gossip synchronization: synchronizes
- Nostr relays → Nostr relay network: connects
- Nostr relays → Nostr protocol: uses protocol
bitchat/Nostr/NostrRelayManager.swift - Nostr relays → Nostr inbound: delivers events
- Nostr inbound → Geographic channels: records presence
bitchat/ViewModels/NostrInboundPipeline.swift - Geographic channels → Nostr relays: uses relays
README.md - Identity state → Keychain storage: stores keys
bitchat/Identity/SecureIdentityStateManager.swift - Bluetooth mesh → Noise sessions: secures sessions
README.md - Noise sessions → Noise security rules: uses rules
bitchat/Noise/NoiseSessionManager.swift - Nostr relays → Community boards: carries board posts
bitchat/Services/Board/BoardManager.swift - Chat coordination → Group messaging: supports groups
- Chat coordination → Voice messaging: supports voice