# celldock/celldock-for-mac architecture

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

- Interactive diagram: https://gitdiagram.com/celldock/celldock-for-mac
- Repository: https://github.com/celldock/celldock-for-mac

## Overview

CellDock is a native macOS menu-bar application for using supported USB cellular modules for data, messaging, calls, and SIM management. A user works through the app’s menu-bar or communication windows; AppState coordinates module services and feature actions, while cellular networking and optional VoWiFi involve a privileged helper and separate runtime. The README also documents contacts, eSIM, call recording, SMS forwarding, and per-module SOCKS5 proxies. Some subsystem links are documented capabilities rather than inspected call sites; those are marked dashed where implementation wiring is uncertain.

Main entry points: [`Sources/CellDock/AppState.swift`](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/AppState.swift) (App state), [`Sources/CellDockNetworkHelper/main.swift`](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDockNetworkHelper/main.swift) (Network helper), [`Sources/CellDock/NetworkHelperClient.swift`](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/NetworkHelperClient.swift) (Privileged helper client), [`Sources/CellDock/MenuBarPanelController.swift`](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/MenuBarPanelController.swift) (Menu bar and windows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["App interface"]
  node_ui["Menu bar and windows"]
  node_orchestrator["App state<br/>[AppState.swift]"]
end

subgraph group_modem["Module communications"]
  node_inventory["Module discovery"]
  node_modem_service["Modem service<br/>[ModemService.swift]"]
  node_usb_bridge["USB modem bridge<br/>[ModemBridge.c]"]
end

subgraph group_network["Network services"]
  node_network_controller["Cellular network control"]
  node_network_client["Privileged helper client"]
  node_network_helper["Network helper<br/>[main.swift]"]
  node_network_mutator["Network configuration"]
  node_proxy["SOCKS5 proxies"]
  node_vowifi["VoWiFi control"]
  node_vowifi_host["VoWiFi host"]
  node_vowifi_runtime["VoWiFi runtime<br/>[main.go]"]
end

subgraph group_communications["Calls and messaging"]
  node_sms[("SMS and forwarding<br/>[MessageStore.swift]")]
  node_calls[("Calls and recording")]
  node_recordings[("Recording library")]
end

subgraph group_support["SIM and contacts"]
  node_esim["eSIM management<br/>[EUICCService.swift]"]
  node_contacts[("Contacts")]
end

node_user(("Mac user"))

node_user -->|"uses"| node_ui
node_ui -.->|"presents actions"| node_orchestrator
node_orchestrator -->|"starts discovery"| node_inventory
node_orchestrator -->|"starts services"| node_modem_service
node_modem_service -.->|"uses USB transport"| node_usb_bridge
node_orchestrator -->|"coordinates cellular"| node_network_controller
node_network_controller -->|"requests changes"| node_network_client
node_network_client -.->|"sends IPC"| node_network_helper
node_network_helper -->|"applies configuration"| node_network_mutator
node_orchestrator -->|"starts proxies"| node_proxy
node_orchestrator -->|"starts control"| node_vowifi
node_vowifi -.->|"requests host"| node_network_client
node_network_helper -->|"dispatches requests"| node_vowifi_host
node_vowifi_host -.->|"launches process"| node_vowifi_runtime
node_orchestrator -->|"manages messages"| node_sms
node_orchestrator -->|"manages call history"| node_calls
node_orchestrator -->|"manages recordings"| node_recordings
node_orchestrator -->|"manages profiles"| node_esim
node_orchestrator -.->|"uses contacts"| node_contacts

click node_ui "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/MenuBarPanelController.swift"
click node_orchestrator "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/AppState.swift"
click node_inventory "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/ModemInventoryService.swift"
click node_modem_service "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/ModemService.swift"
click node_usb_bridge "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CModemBridge/ModemBridge.c"
click node_network_controller "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/NetworkServiceController.swift"
click node_network_client "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/NetworkHelperClient.swift"
click node_network_helper "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDockNetworkHelper/main.swift"
click node_network_mutator "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDockNetworkHelper/RootNetworkMutator.swift"
click node_proxy "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/SOCKSProxyController.swift"
click node_vowifi "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/VoWiFiController.swift"
click node_vowifi_host "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDockNetworkHelper/VoWiFiHostManager.swift"
click node_vowifi_runtime "https://github.com/celldock/celldock-for-mac/blob/main/ThirdParty/vowifi-go/cmd/celldock-vowifi-runtime/main.go"
click node_sms "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/MessageStore.swift"
click node_calls "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/CallHistoryStore.swift"
click node_recordings "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/CallRecordingStore.swift"
click node_esim "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/EUICCService.swift"
click node_contacts "https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/SystemContactStore.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_ui,node_orchestrator,node_user toneBlue
class node_inventory,node_modem_service,node_usb_bridge toneAmber
class node_network_controller,node_network_client,node_network_helper,node_network_mutator,node_proxy,node_vowifi,node_vowifi_host,node_vowifi_runtime toneMint
class node_sms,node_calls,node_recordings toneRose
class node_esim,node_contacts toneIndigo
```

## Components

### App interface

- [Menu bar and windows](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/MenuBarPanelController.swift): `Sources/CellDock/MenuBarPanelController.swift`
- [App state](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/AppState.swift): `Sources/CellDock/AppState.swift`

### Module communications

- [Module discovery](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/ModemInventoryService.swift): `Sources/CellDock/ModemInventoryService.swift`
- [Modem service](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/ModemService.swift): `Sources/CellDock/ModemService.swift`
- [USB modem bridge](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CModemBridge/ModemBridge.c): `Sources/CModemBridge/ModemBridge.c`

### Network services

- [Cellular network control](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/NetworkServiceController.swift): `Sources/CellDock/NetworkServiceController.swift`
- [Privileged helper client](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/NetworkHelperClient.swift): `Sources/CellDock/NetworkHelperClient.swift`
- [Network helper](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDockNetworkHelper/main.swift): `Sources/CellDockNetworkHelper/main.swift`
- [Network configuration](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDockNetworkHelper/RootNetworkMutator.swift): `Sources/CellDockNetworkHelper/RootNetworkMutator.swift`
- [SOCKS5 proxies](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/SOCKSProxyController.swift): `Sources/CellDock/SOCKSProxyController.swift`
- [VoWiFi control](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/VoWiFiController.swift): `Sources/CellDock/VoWiFiController.swift`
- [VoWiFi host](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDockNetworkHelper/VoWiFiHostManager.swift): `Sources/CellDockNetworkHelper/VoWiFiHostManager.swift`
- [VoWiFi runtime](https://github.com/celldock/celldock-for-mac/blob/main/ThirdParty/vowifi-go/cmd/celldock-vowifi-runtime/main.go): `ThirdParty/vowifi-go/cmd/celldock-vowifi-runtime/main.go`

### Calls and messaging

- [SMS and forwarding](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/MessageStore.swift): `Sources/CellDock/MessageStore.swift`
- [Calls and recording](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/CallHistoryStore.swift): `Sources/CellDock/CallHistoryStore.swift`
- [Recording library](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/CallRecordingStore.swift): `Sources/CellDock/CallRecordingStore.swift`

### SIM and contacts

- [eSIM management](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/EUICCService.swift): `Sources/CellDock/EUICCService.swift`
- [Contacts](https://github.com/celldock/celldock-for-mac/blob/main/Sources/CellDock/SystemContactStore.swift): `Sources/CellDock/SystemContactStore.swift`

### Other components

- **Mac user**

## Connections

- Mac user → Menu bar and windows: uses (evidence: `README.md`)
- Menu bar and windows → App state: presents actions (evidence: `Sources/CellDock/MenuBarPanelController.swift`)
- App state → Module discovery: starts discovery (evidence: `Sources/CellDock/AppState.swift`)
- App state → Modem service: starts services (evidence: `Sources/CellDock/AppState.swift`)
- Modem service → USB modem bridge: uses USB transport
- App state → Cellular network control: coordinates cellular (evidence: `Sources/CellDock/AppState.swift`)
- Cellular network control → Privileged helper client: requests changes (evidence: `Sources/CellDock/NetworkServiceController.swift`)
- Privileged helper client → Network helper: sends IPC
- Network helper → Network configuration: applies configuration (evidence: `Sources/CellDockNetworkHelper/main.swift`)
- App state → SOCKS5 proxies: starts proxies (evidence: `Sources/CellDock/AppState.swift`)
- App state → VoWiFi control: starts control (evidence: `Sources/CellDock/AppState.swift`)
- VoWiFi control → Privileged helper client: requests host (evidence: `Sources/CellDock/VoWiFiController.swift`)
- Network helper → VoWiFi host: dispatches requests (evidence: `Sources/CellDockNetworkHelper/main.swift`)
- VoWiFi host → VoWiFi runtime: launches process
- App state → SMS and forwarding: manages messages (evidence: `Sources/CellDock/AppState.swift`)
- App state → Calls and recording: manages call history (evidence: `Sources/CellDock/AppState.swift`)
- App state → Recording library: manages recordings (evidence: `Sources/CellDock/AppState.swift`)
- App state → eSIM management: manages profiles (evidence: `Sources/CellDock/AppState.swift`)
- App state → Contacts: uses contacts (evidence: `Sources/CellDock/AppState.swift`)