# permissionlesstech/bitchat architecture

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

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

## Overview

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: [`bitchat/ViewModels/ChatViewModel.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/ViewModels/ChatViewModel.swift) (Chat coordination), [`bitchat/Nostr/NostrRelayManager.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/NostrRelayManager.swift) (Nostr relays), [`bitchat/Services/MessageRouter.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/MessageRouter.swift) (Message routing), [`bitchat/Services/BLE/BLEService.swift`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/BLE/BLEService.swift) (Bluetooth mesh)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and conversations"]
  node_app["App shell<br/>[BitchatApp.swift]"]
  node_chat["Chat coordination"]
  node_conversation[("Conversation state")]
end

subgraph group_routing["Messaging and mesh"]
  node_message["Message model"]
  node_router["Message routing"]
  node_transport["Transport configuration"]
  node_ble["Bluetooth mesh<br/>[BLEService.swift]"]
  node_receive["Mesh receive"]
  node_packet["Binary packets"]
  node_sync["Gossip synchronization"]
  node_outbox[("Store and forward")]
end

subgraph group_internet["Nostr and location"]
  node_nostr["Nostr relays"]
  node_nostrprotocol["Nostr protocol"]
  node_inbound["Nostr inbound"]
  node_geo["Geographic channels"]
end

subgraph group_security["Identity and security"]
  node_identity["Identity state"]
  node_keychain[("Keychain storage")]
  node_noise["Noise sessions"]
  node_noiseconstants["Noise security rules"]
end

subgraph group_features["Community features"]
  node_board["Community boards<br/>[BoardManager.swift]"]
  node_groups["Group messaging"]
  node_voice["Voice messaging"]
end

node_user(("Chat user"))
node_external(("Nostr relay network"))

node_user -->|"uses"| node_app
node_app -.->|"presents"| node_chat
node_chat -.->|"updates"| node_conversation
node_chat -.->|"routes"| node_router
node_router -.->|"selects transport"| node_transport
node_router -->|"prefers Bluetooth"| node_ble
node_router -->|"falls back"| node_nostr
node_router -->|"queues messages"| node_outbox
node_chat -.->|"composes"| node_message
node_ble -.->|"transmits"| node_packet
node_ble -.->|"receives packets"| node_receive
node_receive -.->|"synchronizes"| node_sync
node_nostr -.->|"connects"| node_external
node_nostr -->|"uses protocol"| node_nostrprotocol
node_nostr -.->|"delivers events"| node_inbound
node_inbound -->|"records presence"| node_geo
node_geo -->|"uses relays"| node_nostr
node_identity -->|"stores keys"| node_keychain
node_ble -->|"secures sessions"| node_noise
node_noise -->|"uses rules"| node_noiseconstants
node_nostr -->|"carries board posts"| node_board
node_chat -.->|"supports groups"| node_groups
node_chat -.->|"supports voice"| node_voice

click node_app "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/BitchatApp.swift"
click node_chat "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/ViewModels/ChatViewModel.swift"
click node_conversation "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/App/ConversationStore.swift"
click node_message "https://github.com/permissionlesstech/bitchat/blob/main/localPackages/BitFoundation/Sources/BitFoundation/BitchatMessage.swift"
click node_router "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/MessageRouter.swift"
click node_transport "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/TransportConfig.swift"
click node_ble "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/BLE/BLEService.swift"
click node_receive "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/BLE/BLEReceivePipeline.swift"
click node_packet "https://github.com/permissionlesstech/bitchat/blob/main/localPackages/BitFoundation/Sources/BitFoundation/BitchatPacket.swift"
click node_sync "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Sync/GossipSyncManager.swift"
click node_outbox "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/Courier/MessageOutboxStore.swift"
click node_nostr "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/NostrRelayManager.swift"
click node_nostrprotocol "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/NostrProtocol.swift"
click node_inbound "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/ViewModels/NostrInboundPipeline.swift"
click node_geo "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/ViewModels/GeoChannelCoordinator.swift"
click node_identity "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Identity/SecureIdentityStateManager.swift"
click node_keychain "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/KeychainManager.swift"
click node_noise "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Noise/NoiseSessionManager.swift"
click node_noiseconstants "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Noise/NoiseSecurityConstants.swift"
click node_board "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/Board/BoardManager.swift"
click node_groups "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/Groups/GroupProtocol.swift"
click node_voice "https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Features/voice/PTTCaptureEngine.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_chat,node_conversation,node_user toneBlue
class node_message,node_router,node_transport,node_ble,node_receive,node_packet,node_sync,node_outbox toneAmber
class node_nostr,node_nostrprotocol,node_inbound,node_geo toneMint
class node_identity,node_keychain,node_noise,node_noiseconstants toneRose
class node_board,node_groups,node_voice,node_external toneIndigo
```

## Components

### App and conversations

- [App shell](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/BitchatApp.swift): `bitchat/BitchatApp.swift`
- [Chat coordination](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/ViewModels/ChatViewModel.swift): `bitchat/ViewModels/ChatViewModel.swift`
- [Conversation state](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/App/ConversationStore.swift): `bitchat/App/ConversationStore.swift`

### Messaging and mesh

- [Message model](https://github.com/permissionlesstech/bitchat/blob/main/localPackages/BitFoundation/Sources/BitFoundation/BitchatMessage.swift): `localPackages/BitFoundation/Sources/BitFoundation/BitchatMessage.swift`
- [Message routing](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/MessageRouter.swift): `bitchat/Services/MessageRouter.swift`
- [Transport configuration](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/TransportConfig.swift): `bitchat/Services/TransportConfig.swift`
- [Bluetooth mesh](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/BLE/BLEService.swift): `bitchat/Services/BLE/BLEService.swift`
- [Mesh receive](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/BLE/BLEReceivePipeline.swift): `bitchat/Services/BLE/BLEReceivePipeline.swift`
- [Binary packets](https://github.com/permissionlesstech/bitchat/blob/main/localPackages/BitFoundation/Sources/BitFoundation/BitchatPacket.swift): `localPackages/BitFoundation/Sources/BitFoundation/BitchatPacket.swift`
- [Gossip synchronization](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Sync/GossipSyncManager.swift): `bitchat/Sync/GossipSyncManager.swift`
- [Store and forward](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/Courier/MessageOutboxStore.swift): `bitchat/Services/Courier/MessageOutboxStore.swift`

### Nostr and location

- [Nostr relays](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/NostrRelayManager.swift): `bitchat/Nostr/NostrRelayManager.swift`
- [Nostr protocol](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Nostr/NostrProtocol.swift): `bitchat/Nostr/NostrProtocol.swift`
- [Nostr inbound](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/ViewModels/NostrInboundPipeline.swift): `bitchat/ViewModels/NostrInboundPipeline.swift`
- [Geographic channels](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/ViewModels/GeoChannelCoordinator.swift): `bitchat/ViewModels/GeoChannelCoordinator.swift`

### Identity and security

- [Identity state](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Identity/SecureIdentityStateManager.swift): `bitchat/Identity/SecureIdentityStateManager.swift`
- [Keychain storage](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/KeychainManager.swift): `bitchat/Services/KeychainManager.swift`
- [Noise sessions](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Noise/NoiseSessionManager.swift): `bitchat/Noise/NoiseSessionManager.swift`
- [Noise security rules](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Noise/NoiseSecurityConstants.swift): `bitchat/Noise/NoiseSecurityConstants.swift`

### Community features

- [Community boards](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/Board/BoardManager.swift): `bitchat/Services/Board/BoardManager.swift`
- [Group messaging](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/Groups/GroupProtocol.swift): `bitchat/Services/Groups/GroupProtocol.swift`
- [Voice messaging](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Features/voice/PTTCaptureEngine.swift): `bitchat/Features/voice/PTTCaptureEngine.swift`

### Other components

- **Chat user**
- **Nostr relay network**

## Connections

- Chat user → App shell: uses (evidence: `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 (evidence: `README.md`)
- Message routing → Nostr relays: falls back (evidence: `README.md`)
- Message routing → Store and forward: queues messages (evidence: `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 (evidence: `bitchat/Nostr/NostrRelayManager.swift`)
- Nostr relays → Nostr inbound: delivers events
- Nostr inbound → Geographic channels: records presence (evidence: `bitchat/ViewModels/NostrInboundPipeline.swift`)
- Geographic channels → Nostr relays: uses relays (evidence: `README.md`)
- Identity state → Keychain storage: stores keys (evidence: `bitchat/Identity/SecureIdentityStateManager.swift`)
- Bluetooth mesh → Noise sessions: secures sessions (evidence: `README.md`)
- Noise sessions → Noise security rules: uses rules (evidence: `bitchat/Noise/NoiseSessionManager.swift`)
- Nostr relays → Community boards: carries board posts (evidence: `bitchat/Services/Board/BoardManager.swift`)
- Chat coordination → Group messaging: supports groups
- Chat coordination → Voice messaging: supports voice
