# jackjackbits/bitchat architecture

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

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

## Overview

##### Project Type and Purpose
- Native iOS/macOS decentralized P2P messaging app
- No servers or internet—Bluetooth LE mesh network with end-to-end encryption

##### External Elements
- Other peer Device nodes (identical component stacks)
- Bluetooth LE radio/link between Device nodes

1. User action in View → ChatViewModel
2. ChatViewModel → Service Layer (e.g., sendMessage → EncryptionService → BinaryProtocol)
3. BinaryProtocol → BluetoothMeshService → CoreBluetooth API
4. CoreBluetooth API → Physical mesh → CoreBluetooth API on peer
5. Peer’s BluetoothMeshService → Protocol Layer → EncryptionService (decrypt) → ChatViewModel → View

Also show:
– DeliveryTracker/Retry/Retention as observers on inbound/outbound message streams
– KeychainManager used by EncryptionService & Channel management
– CompressionUtil and BloomFilter used inside Service/Protocol to compress and dedupe

##### Architectural Patterns & Design Principles
- MVVM for UI separation
- Service‐oriented: each service has single responsibility (encryption, networking, retry, retention)
- Protocol abstraction: clean separation between message semantics (BitchatProtocol) and on‐wire format (BinaryProtocol)
- Local‐first, peer‐to‐peer mesh with store‐and‐forward

##### Technologies & Frameworks
– SwiftUI (Views, declarative UI)
– Combine or Swift concurrency (async streams between ViewModel & Services)
– CoreBluetooth (Bluetooth LE mesh)
– Crypto libraries: X25519, Ed25519, AES-GCM, Argon2id
– LZ4 for compression
– Keychain for secure storage

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Device A"
    subgraph "App Entry"
      BA_A["BitchatApp"]:::external
    end
    subgraph "UI Layer"
      CVA["ContentView"]:::ui
      AIV["AppInfoView"]:::ui
    end
    subgraph "ViewModel Layer"
      CVM_A["ChatViewModel"]:::vm
    end
    subgraph "Service Layer"
      BMS_A["BluetoothMeshService"]:::service
      ES_A["EncryptionService"]:::service
      DT_A["DeliveryTracker"]:::service
      MRS_A["MessageRetryService"]:::service
      MRet_A["MessageRetentionService"]:::service
      NS_A["NotificationService"]:::service
      KM_A["KeychainManager"]:::service
    end
    subgraph "Protocol Layer"
      BP_A["BitchatProtocol"]:::protocol
      BN_A["BinaryProtocol"]:::protocol
    end
    subgraph "Utility Layer"
      CU_A["CompressionUtil"]:::util
      BF_A["OptimizedBloomFilter"]:::util
      BO_A["BatteryOptimizer"]:::util
    end
    subgraph "OS & Data Layer"
      IM_A["In-memory Caches"]:::os
      KCH_A["Keychain"]:::os
      CB_A["CoreBluetooth API"]:::os
    end
  end

  subgraph "Device B"
    subgraph "App Entry"
      BA_B["BitchatApp"]:::external
    end
    subgraph "UI Layer"
      CVB["ContentView"]:::ui
      AIV_B["AppInfoView"]:::ui
    end
    subgraph "ViewModel Layer"
      CVM_B["ChatViewModel"]:::vm
    end
    subgraph "Service Layer"
      BMS_B["BluetoothMeshService"]:::service
      ES_B["EncryptionService"]:::service
      DT_B["DeliveryTracker"]:::service
      MRS_B["MessageRetryService"]:::service
      MRet_B["MessageRetentionService"]:::service
      NS_B["NotificationService"]:::service
      KM_B["KeychainManager"]:::service
    end
    subgraph "Protocol Layer"
      BP_B["BitchatProtocol"]:::protocol
      BN_B["BinaryProtocol"]:::protocol
    end
    subgraph "Utility Layer"
      CU_B["CompressionUtil"]:::util
      BF_B["OptimizedBloomFilter"]:::util
      BO_B["BatteryOptimizer"]:::util
    end
    subgraph "OS & Data Layer"
      IM_B["In-memory Caches"]:::os
      KCH_B["Keychain"]:::os
      CB_B["CoreBluetooth API"]:::os
    end
  end

  %% Internal Flows A
  BA_A --> CVA
  BA_A --> AIV
  CVA --> CVM_A
  AIV --> CVM_A
  CVM_A --> ES_A
  ES_A --> BN_A
  BN_A --> BMS_A
  BMS_A --> CB_A
  CB_A -->|"Bluetooth LE mesh"| CB_B
  CB_B --> BMS_B
  BMS_B --> BN_B
  BN_B --> ES_B
  ES_B --> CVM_B
  CVM_B --> CVB

  %% Observers and utilities A
  ES_A -->|uses| KM_A
  ES_A -->|uses| CU_A
  BN_A -->|uses| BF_A
  BMS_A -->|uses| BO_A
  ES_A -.-> DT_A
  ES_A -.-> MRS_A
  ES_A -.-> MRet_A
  BN_A -.-> DT_A
  BN_A -.-> MRS_A
  BN_A -.-> MRet_A

  %% Observers and utilities B
  ES_B -->|uses| KM_B
  ES_B -->|uses| CU_B
  BN_B -->|uses| BF_B
  BMS_B -->|uses| BO_B
  ES_B -.-> DT_B
  ES_B -.-> MRS_B
  ES_B -.-> MRet_B
  BN_B -.-> DT_B
  BN_B -.-> MRS_B
  BN_B -.-> MRet_B

  %% Click Events
  click CVA "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Views/ContentView.swift"
  click AIV "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Views/AppInfoView.swift"
  click CVM_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/ViewModels/ChatViewModel.swift"
  click BMS_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/BluetoothMeshService.swift"
  click ES_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/EncryptionService.swift"
  click DT_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/DeliveryTracker.swift"
  click MRS_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/MessageRetryService.swift"
  click MRet_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/MessageRetentionService.swift"
  click NS_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/NotificationService.swift"
  click KM_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/KeychainManager.swift"
  click BP_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Protocols/BitchatProtocol.swift"
  click BN_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Protocols/BinaryProtocol.swift"
  click CU_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Utils/CompressionUtil.swift"
  click BF_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Utils/OptimizedBloomFilter.swift"
  click BO_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Utils/BatteryOptimizer.swift"
  click BA_A "https://github.com/jackjackbits/bitchat/blob/main/bitchat/BitchatApp.swift"
  click CVB "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Views/ContentView.swift"
  click AIV_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Views/AppInfoView.swift"
  click CVM_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/ViewModels/ChatViewModel.swift"
  click BMS_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/BluetoothMeshService.swift"
  click ES_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/EncryptionService.swift"
  click DT_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/DeliveryTracker.swift"
  click MRS_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/MessageRetryService.swift"
  click MRet_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/MessageRetentionService.swift"
  click NS_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/NotificationService.swift"
  click KM_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Services/KeychainManager.swift"
  click BP_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Protocols/BitchatProtocol.swift"
  click BN_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Protocols/BinaryProtocol.swift"
  click CU_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Utils/CompressionUtil.swift"
  click BF_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Utils/OptimizedBloomFilter.swift"
  click BO_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/Utils/BatteryOptimizer.swift"
  click BA_B "https://github.com/jackjackbits/bitchat/blob/main/bitchat/BitchatApp.swift"

  classDef ui fill:#cce5ff,stroke:#004085,color:#004085
  classDef vm fill:#e2e3e5,stroke:#6c757d,color:#383d41
  classDef service fill:#d4edda,stroke:#155724,color:#155724
  classDef protocol fill:#fff3cd,stroke:#856404,color:#856404
  classDef util fill:#ffe5b4,stroke:#cc8400,color:#663c00
  classDef os fill:#f8f9fa,stroke:#6c757d,color:#495057
  classDef external fill:#f1f1f1,stroke:#343a40,color:#343a40
```
