# FluidVoice Architecture: A Deep Dive Into Its Core Components and Modular Design

> Explore the FluidVoice architecture and its core components. Discover how its modular macOS design ensures independent testing and easy extension of UI, audio capture, speech-to-text, LLM, and services.

- Repository: [ALTIC/FluidVoice](https://github.com/altic-dev/FluidVoice)
- Tags: deep-dive
- Published: 2026-08-16

---

**FluidVoice is built as a modular macOS application with clean separation between UI, audio capture, speech-to-text, LLM integration, and auxiliary services, enabling independent testing and easy extension of any layer.**

The **FluidVoice architecture** follows a layered service-oriented design where each major capability is encapsulated in dedicated Swift components. This structure, implemented in the [altic-dev/FluidVoice](https://github.com/altic-dev/FluidVoice) repository, keeps the SwiftUI interface thin while delegating heavy work—audio processing, transcription, and language model calls—to specialized services.

---

## Application Entrypoint and Bootstrap

The **application entrypoint** lives in [`Sources/Fluid/fluidApp.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/fluidApp.swift). This file launches the SwiftUI app, configures global services, and wires the root view hierarchy. It establishes the dependency graph that downstream services consume, ensuring consistent configuration across audio, networking, and analytics subsystems.

---

## User Interface Layer

The **FluidVoice UI layer** renders four primary interaction surfaces through SwiftUI views:

- **Live transcription overlay** — [`BottomOverlayView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/BottomOverlayView.swift) displays real-time speech recognition
- **Command mode interface** — [`CommandModeView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/CommandModeView.swift) handles voice-driven tool execution
- **Rewrite mode interface** — [`RewriteModeView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/RewriteModeView.swift) manages text transformation workflows
- **Menu-bar integration** — anchored from [`ContentView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ContentView.swift)

All views delegate actual processing to service objects, maintaining the architecture's clean separation principle.

---

## Audio Capture and Speech Recognition (ASR)

The **audio and ASR pipeline** combines low-level CoreAudio capture with pluggable transcription providers.

| Component | File | Responsibility |
|-----------|------|----------------|
| Audio capture | [`DirectCoreAudioInput.swift`](https://github.com/altic-dev/FluidVoice/blob/main/DirectCoreAudioInput.swift) | CoreAudio buffer acquisition and stream management |
| ASR orchestration | [`ASRService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ASRService.swift) | Routes audio to active transcription provider |
| External providers | [`ExternalCoreMLTranscriptionProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ExternalCoreMLTranscriptionProvider.swift) | Apple Speech, Whisper, Nemotron, Parakeet, and custom CoreML models |

This provider pattern allows runtime switching between speech engines without UI changes.

---

## LLM Integration and Parsing

The **LLM integration layer** centralizes all language model communication through [`LLMClient.swift`](https://github.com/altic-dev/FluidVoice/blob/main/LLMClient.swift). Key capabilities include:

- **OpenAI-compatible request building** — unified request format across providers
- **Streaming and non-streaming modes** — configurable per-call via the `streaming` parameter
- **Thinking tag parsing** — [`ThinkingParsers.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ThinkingParsers.swift) extracts reasoning tokens from model responses
- **Tool call surfacing** — structured output for function execution

```swift
import Fluid

let config = LLMClient.Config(
    model: "gpt-4o-mini",
    providerID: .openAI,
    streaming: false,
    messages: [
        ["role": "system", "content": "You are a helpful assistant."],
        ["role": "user",   "content": "Summarise the last paragraph."]
    ]
)

Task {
    do {
        let response = try await LLMClient.shared.call(config)
        print("LLM answer:", response.content)
    } catch {
        print("LLM error:", error)
    }
}

```

---

## Mode Services: Business Logic Layer

The **mode services** implement domain-specific workflows for each interaction pattern:

| Service | File | Purpose |
|---------|------|---------|
| Command mode | [`CommandModeService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/CommandModeService.swift) | Voice-triggered tool execution with ASR → LLM → action pipeline |
| Rewrite mode | [`RewriteModeService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/RewriteModeService.swift) | Text transformation and style rewriting |
| Dictation post-processing | [`DictationPostProcessingService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/DictationPostProcessingService.swift) | Cleanup and formatting of raw transcription output |
| Speaker diarization | [`SpeakerDiarizationService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/SpeakerDiarizationService.swift) | Multi-speaker identification and segmentation |

The `CommandModeService.startSession()` method demonstrates the architecture's compositional approach: it wires `TranscriptionProvider`, `ASRService`, and `LLMClient` into a cohesive data flow.

```swift
import Fluid

let commandService = CommandModeService()
Task {
    do {
        let result = try await commandService.startSession()
        print("Command result:", result)
    } catch {
        print("Command mode failed:", error)
    }
}

```

---

## Global Coordination and Hot-Keys

The **global coordination layer** handles system-wide interaction:

- **[`GlobalHotkeyManager.swift`](https://github.com/altic-dev/FluidVoice/blob/main/GlobalHotkeyManager.swift)** — Registers and manages global keyboard shortcuts using macOS event taps
- **[`AppNavigationRouter.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AppNavigationRouter.swift)** — Centralized view state management and overlay presentation

```swift
import Fluid

GlobalHotkeyManager.shared.register(
    hotkey: .init(key: .space, modifiers: [.control, .option])
) {
    AppNavigationRouter.shared.showOverlay()
}

```

---

## Audio Pipeline and Media Services

Supporting the core ASR flow, the **media layer** provides:

- [`MediaPlaybackService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/MediaPlaybackService.swift) — Spoken feedback and audio confirmation cues
- [`AudioBufferConverter.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AudioBufferConverter.swift) — Format conversion between capture and processing stages
- [`AudioEngineRetirementDrain.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AudioEngineRetirementDrain.swift) — Graceful teardown of audio resources

---

## Dictionary and AI Enhancement

The **dictionary and enhancement subsystem** enables personalization and on-device intelligence:

| Component | File | Function |
|-----------|------|----------|
| Correction tracking | [`AutomaticDictionaryCorrectionTracker.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AutomaticDictionaryCorrectionTracker.swift) | Learns from user corrections |
| Endpoint detection | [`DictionaryTrainingEndpointDetector.swift`](https://github.com/altic-dev/FluidVoice/blob/main/DictionaryTrainingEndpointDetector.swift) | Identifies training boundaries |
| Private AI provider | [`PrivateAIProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/PrivateAIProvider.swift) | On-device "Fluid Intelligence" post-processor |

---

## Networking and Model Management

The **networking layer** handles external dependencies:

- [`ModelDownloader.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ModelDownloader.swift) — Progressive download of speech recognition models
- [`FunctionCallingProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/FunctionCallingProvider.swift) — LLM provider abstraction for tool-capable models
- [`LocalAPIServer.swift`](https://github.com/altic-dev/FluidVoice/blob/main/LocalAPIServer.swift) — Lightweight HTTP server exposing internal services to the UI

---

## Analytics and Infrastructure

- **[`AnalyticsService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AnalyticsService.swift)** — Opt-in, locally-stored anonymous usage metrics
- **[`DebugLogger.swift`](https://github.com/altic-dev/FluidVoice/blob/main/DebugLogger.swift)** — Structured logging with configurable verbosity
- **[`ClipboardService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ClipboardService.swift)** — Pasteboard integration for text output

---

## Summary

The **FluidVoice architecture** achieves several design goals through its component structure:

- **Testability** — Each service can be exercised independently (see `Tests/FluidDictationIntegrationTests/`)
- **Extensibility** — Swappable providers for ASR and LLM without UI changes
- **Maintainability** — Clear file organization by functional domain
- **Performance** — Streaming audio pipelines and lazy service initialization

Key architectural files to explore:

- [`Sources/Fluid/fluidApp.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/fluidApp.swift) — Application bootstrap
- [`Sources/Fluid/Services/LLMClient.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/LLMClient.swift) — Language model integration
- [`Sources/Fluid/Services/CommandModeService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/CommandModeService.swift) — Core workflow orchestration
- [`Sources/Fluid/Services/ASRService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/ASRService.swift) — Speech recognition abstraction

---

## Frequently Asked Questions

### What programming language is FluidVoice built in?

FluidVoice is implemented entirely in **Swift**, using **SwiftUI** for the interface and **Combine** for reactive data flows. The codebase targets macOS and leverages Apple's CoreAudio and CoreML frameworks for native performance.

### Can I replace the speech recognition engine in FluidVoice?

Yes. The **ASR provider pattern** in [`ASRService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ASRService.swift) and [`ExternalCoreMLTranscriptionProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ExternalCoreMLTranscriptionProvider.swift) allows swapping Apple Speech for Whisper, Nemotron, Parakeet, or custom CoreML models. The UI remains unchanged because transcription is abstracted behind protocol-based providers.

### How does FluidVoice handle streaming LLM responses?

The `LLMClient.Config` struct includes a `streaming` boolean parameter. When enabled, [`LLMClient.swift`](https://github.com/altic-dev/FluidVoice/blob/main/LLMClient.swift) establishes a chunked HTTP connection and yields partial responses through Swift's `AsyncSequence` pattern, parsed by [`ThinkingParsers.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ThinkingParsers.swift) for reasoning token extraction.

### Is FluidVoice's architecture suitable for other voice applications?

The **layered service architecture** transfers well to other voice-enabled macOS apps. The separation of audio capture ([`DirectCoreAudioInput.swift`](https://github.com/altic-dev/FluidVoice/blob/main/DirectCoreAudioInput.swift)), transcription ([`ASRService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ASRService.swift)), and business logic (mode services) provides a template for building domain-specific voice interfaces without modifying low-level components.