# jurek-zsl/swimble architecture

> Architecture diagram of the GitHub repository jurek-zsl/swimble, 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/jurek-zsl/swimble
- Repository: https://github.com/jurek-zsl/swimble

## Overview

Swimble is a native macOS Mumble voice client. The main workflow is a user selecting or opening a server, the app connecting and maintaining server state, then presenting channel/chat activity and carrying voice between the microphone and server. The graph also preserves documented audio, identity, positional-audio, shortcuts, local control, and public-directory capabilities. Arrows are limited to relationships stated in the README or visible in supplied excerpts/index references; several unsampled subsystem links are therefore omitted or shown as unverified.

Main entry points: [`MacClient/Sources/Store/MumbleStore.swift`](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Store/MumbleStore.swift) (Session store), [`rust-core/src/client.rs`](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/client.rs) (Mumble protocol client), [`MacClient/Sources/App.swift`](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/App.swift) (App shell), [`rust-core/src/audio_mixer.rs`](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/audio_mixer.rs) (Opus mixer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["macOS App"]
  node_app["App shell<br/>[App.swift]"]
  node_preferences[("Client preferences")]
  node_settings["Settings state"]
  node_serverui["Server and chat UI"]
end

subgraph group_server["Mumble Connection"]
  node_store["Session store<br/>[MumbleStore.swift]"]
  node_rustclient["Mumble protocol client<br/>[client.rs]"]
  node_conn["Transport and framing<br/>[connection.rs]"]
  node_dns["DNS and server ping<br/>[dns.rs]"]
  node_state[("Protocol state<br/>[state.rs]")]
  node_identity["Certificates and identity<br/>[cert.rs]"]
end

subgraph group_voice["Voice and Audio"]
  node_audioengine["macOS audio engine"]
  node_devices["Audio device routing"]
  node_audioio["Audio I/O<br/>[audio_io.rs]"]
  node_mixer["Opus mixer<br/>[audio_mixer.rs]"]
  node_packets["Voice packets<br/>[voice_packet.rs]"]
  node_crypto["Voice encryption<br/>[crypt_ocb2.rs]"]
  node_recording["WAV recording"]
end

subgraph group_extras["Client Features"]
  node_ptt["Global shortcuts<br/>[GlobalPTT.swift]"]
  node_positional["Positional audio and plugins<br/>[positional.rs]"]
  node_pluginmanager["Plugin manager<br/>[plugins.rs]"]
  node_notifications["Event notifications"]
  node_tts["Text-to-speech<br/>[TTSEngine.swift]"]
  node_directory["Public server directory"]
  node_url["Mumble links"]
  node_control["Local command control<br/>[LocalControl.swift]"]
end

node_user(("User"))
node_server[("Murmur server")]
node_macos["macOS audio and notifications"]

node_user -->|"uses"| node_app
node_app -->|"opens sessions"| node_store
node_app -->|"loads settings"| node_settings
node_app -->|"shows windows"| node_serverui
node_serverui -.->|"uses session"| node_store
node_preferences -->|"supplies preferences"| node_store
node_settings -->|"configures sessions"| node_store
node_store -->|"controls connection"| node_rustclient
node_rustclient -->|"uses transport"| node_conn
node_rustclient -->|"updates state"| node_state
node_rustclient -->|"resolves servers"| node_dns
node_store -.->|"loads identity"| node_identity
node_rustclient -->|"exchanges Mumble data"| node_server
node_store -->|"connects and sends requests"| node_server
node_user -->|"browses servers"| node_directory
node_directory -.->|"selects server"| node_store
node_user -->|"opens link"| node_url
node_url -->|"requests connection"| node_store
node_audioengine -->|"routes devices"| node_devices
node_audioengine -->|"exchanges PCM"| node_audioio
node_rustclient -->|"handles voice"| node_mixer
node_mixer -->|"encodes and decodes"| node_packets
node_rustclient -.->|"protects voice"| node_crypto
node_mixer -->|"renders positioning"| node_positional
node_mixer -->|"uses plugins"| node_pluginmanager
node_store -->|"manages audio"| node_audioengine
node_store -->|"manages recording"| node_recording
node_settings -->|"configures audio"| node_audioengine
node_user -->|"triggers shortcuts"| node_ptt
node_ptt -.->|"controls transmission"| node_store
node_store -->|"reports events"| node_notifications
node_notifications -->|"speaks events"| node_tts
node_notifications -->|"posts notifications and cues"| node_macos
node_user -->|"runs CLI commands"| node_control
node_control -.->|"dispatches commands"| node_store

click node_app "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/App.swift"
click node_preferences "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Models/ClientPreferences.swift"
click node_settings "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Views/Settings/SettingsState.swift"
click node_serverui "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Views/ServerSplitView.swift"
click node_store "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Store/MumbleStore.swift"
click node_rustclient "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/client.rs"
click node_conn "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/connection.rs"
click node_dns "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/dns.rs"
click node_state "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/state.rs"
click node_identity "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/cert.rs"
click node_audioengine "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/MacAudioEngine.swift"
click node_devices "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/CoreAudioDeviceManager.swift"
click node_audioio "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/audio_io.rs"
click node_mixer "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/audio_mixer.rs"
click node_packets "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/voice_packet.rs"
click node_crypto "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/crypt_ocb2.rs"
click node_recording "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/AudioRecorder.swift"
click node_ptt "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/GlobalPTT.swift"
click node_positional "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/positional.rs"
click node_pluginmanager "https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/plugins.rs"
click node_notifications "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Utils/EventNotificationManager.swift"
click node_tts "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/TTSEngine.swift"
click node_directory "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Utils/MumistService.swift"
click node_url "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Utils/MumbleURLHandler.swift"
click node_control "https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Utils/LocalControl.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_preferences,node_settings,node_serverui,node_user toneBlue
class node_store,node_rustclient,node_conn,node_dns,node_state,node_identity,node_server toneAmber
class node_audioengine,node_devices,node_audioio,node_mixer,node_packets,node_crypto,node_recording toneMint
class node_ptt,node_positional,node_pluginmanager,node_notifications,node_tts,node_directory,node_url,node_control toneRose
class node_macos toneIndigo
```

## Components

### macOS App

- [App shell](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/App.swift): `MacClient/Sources/App.swift`
- [Client preferences](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Models/ClientPreferences.swift): `MacClient/Sources/Models/ClientPreferences.swift`
- [Settings state](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Views/Settings/SettingsState.swift): `MacClient/Sources/Views/Settings/SettingsState.swift`
- [Server and chat UI](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Views/ServerSplitView.swift): `MacClient/Sources/Views/ServerSplitView.swift`

### Mumble Connection

- [Session store](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Store/MumbleStore.swift): `MacClient/Sources/Store/MumbleStore.swift`
- [Mumble protocol client](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/client.rs): `rust-core/src/client.rs`
- [Transport and framing](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/connection.rs): `rust-core/src/connection.rs`
- [DNS and server ping](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/dns.rs): `rust-core/src/dns.rs`
- [Protocol state](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/state.rs): `rust-core/src/state.rs`
- [Certificates and identity](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/cert.rs): `rust-core/src/cert.rs`

### Voice and Audio

- [macOS audio engine](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/MacAudioEngine.swift): `MacClient/Sources/Audio/MacAudioEngine.swift`
- [Audio device routing](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/CoreAudioDeviceManager.swift): `MacClient/Sources/Audio/CoreAudioDeviceManager.swift`
- [Audio I/O](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/audio_io.rs): `rust-core/src/audio_io.rs`
- [Opus mixer](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/audio_mixer.rs): `rust-core/src/audio_mixer.rs`
- [Voice packets](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/voice_packet.rs): `rust-core/src/voice_packet.rs`
- [Voice encryption](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/crypt_ocb2.rs): `rust-core/src/crypt_ocb2.rs`
- [WAV recording](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/AudioRecorder.swift): `MacClient/Sources/Audio/AudioRecorder.swift`

### Client Features

- [Global shortcuts](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/GlobalPTT.swift): `MacClient/Sources/Audio/GlobalPTT.swift`
- [Positional audio and plugins](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/positional.rs): `rust-core/src/positional.rs`
- [Plugin manager](https://github.com/jurek-zsl/swimble/blob/main/rust-core/src/plugins.rs): `rust-core/src/plugins.rs`
- [Event notifications](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Utils/EventNotificationManager.swift): `MacClient/Sources/Utils/EventNotificationManager.swift`
- [Text-to-speech](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Audio/TTSEngine.swift): `MacClient/Sources/Audio/TTSEngine.swift`
- [Public server directory](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Utils/MumistService.swift): `MacClient/Sources/Utils/MumistService.swift`
- [Mumble links](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Utils/MumbleURLHandler.swift): `MacClient/Sources/Utils/MumbleURLHandler.swift`
- [Local command control](https://github.com/jurek-zsl/swimble/blob/main/MacClient/Sources/Utils/LocalControl.swift): `MacClient/Sources/Utils/LocalControl.swift`

### Other components

- **User**
- **Murmur server**
- **macOS audio and notifications**

## Connections

- User → App shell: uses (evidence: `MacClient/Sources/App.swift`)
- App shell → Session store: opens sessions (evidence: `MacClient/Sources/App.swift`)
- App shell → Settings state: loads settings (evidence: `MacClient/Sources/App.swift`)
- App shell → Server and chat UI: shows windows (evidence: `MacClient/Sources/App.swift`)
- Server and chat UI → Session store: uses session
- Client preferences → Session store: supplies preferences (evidence: `MacClient/Sources/Models/ClientPreferences.swift`)
- Settings state → Session store: configures sessions (evidence: `MacClient/Sources/Views/Settings/SettingsState.swift`)
- Session store → Mumble protocol client: controls connection (evidence: `MacClient/Sources/Store/MumbleStore.swift`)
- Mumble protocol client → Transport and framing: uses transport (evidence: `rust-core/src/client.rs`)
- Mumble protocol client → Protocol state: updates state (evidence: `rust-core/src/client.rs`)
- Mumble protocol client → DNS and server ping: resolves servers (evidence: `rust-core/src/client.rs`)
- Session store → Certificates and identity: loads identity
- Mumble protocol client → Murmur server: exchanges Mumble data
- Session store → Murmur server: connects and sends requests (evidence: `MacClient/Sources/Store/MumbleStore.swift`)
- User → Public server directory: browses servers
- Public server directory → Session store: selects server
- User → Mumble links: opens link
- Mumble links → Session store: requests connection (evidence: `MacClient/Sources/Utils/MumbleURLHandler.swift`)
- macOS audio engine → Audio device routing: routes devices (evidence: `MacClient/Sources/Audio/MacAudioEngine.swift`)
- macOS audio engine → Audio I/O: exchanges PCM
- Mumble protocol client → Opus mixer: handles voice (evidence: `rust-core/src/client.rs`)
- Opus mixer → Voice packets: encodes and decodes (evidence: `rust-core/src/audio_mixer.rs`)
- Mumble protocol client → Voice encryption: protects voice (evidence: `rust-core/src/client.rs`)
- Opus mixer → Positional audio and plugins: renders positioning (evidence: `rust-core/src/audio_mixer.rs`)
- Opus mixer → Plugin manager: uses plugins (evidence: `rust-core/src/audio_mixer.rs`)
- Session store → macOS audio engine: manages audio (evidence: `MacClient/Sources/Store/MumbleStore.swift`)
- Session store → WAV recording: manages recording (evidence: `MacClient/Sources/Store/MumbleStore.swift`)
- Settings state → macOS audio engine: configures audio (evidence: `MacClient/Sources/Audio/MacAudioEngine.swift`)
- User → Global shortcuts: triggers shortcuts
- Global shortcuts → Session store: controls transmission (evidence: `MacClient/Sources/Store/MumbleStore.swift`)
- Session store → Event notifications: reports events (evidence: `MacClient/Sources/Utils/EventNotificationManager.swift`)
- Event notifications → Text-to-speech: speaks events (evidence: `MacClient/Sources/Utils/EventNotificationManager.swift`)
- Event notifications → macOS audio and notifications: posts notifications and cues (evidence: `MacClient/Sources/Utils/EventNotificationManager.swift`)
- User → Local command control: runs CLI commands
- Local command control → Session store: dispatches commands