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

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 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. 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 displays real-time speech recognition
• Command mode interface — CommandModeView.swift handles voice-driven tool execution
• Rewrite mode interface — RewriteModeView.swift manages text transformation workflows
• Menu-bar integration — anchored from 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	CoreAudio buffer acquisition and stream management
ASR orchestration	ASRService.swift	Routes audio to active transcription provider
External providers	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. 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 extracts reasoning tokens from model responses
• Tool call surfacing — structured output for function execution

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	Voice-triggered tool execution with ASR → LLM → action pipeline
Rewrite mode	RewriteModeService.swift	Text transformation and style rewriting
Dictation post-processing	DictationPostProcessingService.swift	Cleanup and formatting of raw transcription output
Speaker diarization	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.

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 — Registers and manages global keyboard shortcuts using macOS event taps
• AppNavigationRouter.swift — Centralized view state management and overlay presentation

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 — Spoken feedback and audio confirmation cues
• AudioBufferConverter.swift — Format conversion between capture and processing stages
• 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	Learns from user corrections
Endpoint detection	DictionaryTrainingEndpointDetector.swift	Identifies training boundaries
Private AI provider	PrivateAIProvider.swift	On-device "Fluid Intelligence" post-processor

---

Networking and Model Management

The networking layer handles external dependencies:

• ModelDownloader.swift — Progressive download of speech recognition models
• FunctionCallingProvider.swift — LLM provider abstraction for tool-capable models
• LocalAPIServer.swift — Lightweight HTTP server exposing internal services to the UI

---

Analytics and Infrastructure

• AnalyticsService.swift — Opt-in, locally-stored anonymous usage metrics
• DebugLogger.swift — Structured logging with configurable verbosity
• 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 — Application bootstrap
• Sources/Fluid/Services/LLMClient.swift — Language model integration
• Sources/Fluid/Services/CommandModeService.swift — Core workflow orchestration
• 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 and 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 establishes a chunked HTTP connection and yields partial responses through Swift's AsyncSequence pattern, parsed by 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), transcription (ASRService.swift), and business logic (mode services) provides a template for building domain-specific voice interfaces without modifying low-level components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}