# razaxq/vocal architecture

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

- Interactive diagram: https://gitdiagram.com/razaxq/vocal
- Repository: https://github.com/razaxq/vocal

## Overview

Vocal is a Windows desktop voice-input application: a user triggers capture, local recognition produces text, optional correction and cleanup refine it, and the result is inserted into the focused application. The graph preserves the documented model, dictionary, history, settings, AI-consolidation, and update capabilities. Several implementation links are based on the supplied AppController excerpts and README; unsampled subsystem wiring is omitted where uncertain.

Main entry points: [`native/src/AppController.cpp`](https://github.com/razaxq/vocal/blob/main/native/src/AppController.cpp) (App controller), [`native/src/TriggerController.cpp`](https://github.com/razaxq/vocal/blob/main/native/src/TriggerController.cpp) (Trigger handling), [`native/src/platform/WindowsPlatform.cpp`](https://github.com/razaxq/vocal/blob/main/native/src/platform/WindowsPlatform.cpp) (Windows input platform), [`native/src/ModelManager.cpp`](https://github.com/razaxq/vocal/blob/main/native/src/ModelManager.cpp) (Model downloads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop control"]
  node_ui["Desktop UI and tray<br/>[main.cpp]"]
  node_controller["App controller<br/>[AppController.cpp]"]
  node_triggers["Trigger handling"]
  node_platform["Windows input platform"]
end

subgraph group_audio["Audio and recognition"]
  node_capture["Audio capture<br/>[AudioCapture.cpp]"]
  node_segmenter["Audio segmentation<br/>[AudioSegmenter.cpp]"]
  node_speech["Offline recognition<br/>[SpeechWorker.cpp]"]
  node_stream["Streaming recognition<br/>[StreamWorker.cpp]"]
  node_process["Worker processes<br/>[WorkerProcess.cpp]"]
end

subgraph group_text["Text processing"]
  node_correction["Homophone correction"]
  node_cleanup["Spoken-text cleanup<br/>[TextCleanup.cpp]"]
  node_llm["AI text consolidation<br/>[LlmService.cpp]"]
  node_output["Text insertion<br/>[TextOutput.cpp]"]
end

subgraph group_resources["Models and resources"]
  node_catalog["Model catalog<br/>[ModelCatalog.cpp]"]
  node_manager["Model downloads<br/>[ModelManager.cpp]"]
  node_dictionary["Dictionary services"]
end

subgraph group_state["Settings and maintenance"]
  node_settings[("Settings and history<br/>[Settings.cpp]")]
  node_updates["Software updates<br/>[NativeUpdate.h]"]
end

node_user(("Voice-input user"))
node_target["Focused application"]
node_modelhost["Model download hosts"]
node_dictsource["Dictionary update source"]
node_llmservice["Configured AI service"]

node_user -->|"configures and views"| node_ui
node_ui -->|"invokes controls"| node_controller
node_controller -->|"reads and writes"| node_settings
node_controller -->|"configures"| node_triggers
node_triggers -->|"configures and receives input"| node_platform
node_platform -->|"reports input"| node_triggers
node_triggers -->|"signals recording"| node_controller
node_controller -->|"starts capture"| node_capture
node_capture -->|"supplies audio"| node_segmenter
node_controller -->|"dispatches recognition"| node_speech
node_controller -->|"dispatches preview"| node_stream
node_speech -->|"uses worker process"| node_process
node_stream -->|"uses worker process"| node_process
node_controller -->|"requests correction"| node_correction
node_controller -->|"cleans recognized text"| node_cleanup
node_controller -->|"requests consolidation"| node_llm
node_llm -.->|"sends text when enabled"| node_llmservice
node_controller -->|"sends final text"| node_output
node_output -->|"inserts into focused app"| node_platform
node_platform -->|"types text"| node_target
node_controller -->|"requests model operations"| node_manager
node_manager -->|"checks model metadata"| node_catalog
node_manager -->|"downloads models"| node_modelhost
node_controller -->|"coordinates dictionary"| node_dictionary
node_dictionary -->|"checks for updates"| node_dictsource
node_controller -->|"checks software updates"| node_updates

click node_ui "https://github.com/razaxq/vocal/blob/main/native/src/main.cpp"
click node_controller "https://github.com/razaxq/vocal/blob/main/native/src/AppController.cpp"
click node_triggers "https://github.com/razaxq/vocal/blob/main/native/src/TriggerController.cpp"
click node_platform "https://github.com/razaxq/vocal/blob/main/native/src/platform/WindowsPlatform.cpp"
click node_capture "https://github.com/razaxq/vocal/blob/main/native/src/AudioCapture.cpp"
click node_segmenter "https://github.com/razaxq/vocal/blob/main/native/src/AudioSegmenter.cpp"
click node_speech "https://github.com/razaxq/vocal/blob/main/native/src/SpeechWorker.cpp"
click node_stream "https://github.com/razaxq/vocal/blob/main/native/src/StreamWorker.cpp"
click node_process "https://github.com/razaxq/vocal/blob/main/native/src/WorkerProcess.cpp"
click node_correction "https://github.com/razaxq/vocal/blob/main/native/src/CorrectionWorker.cpp"
click node_cleanup "https://github.com/razaxq/vocal/blob/main/native/src/TextCleanup.cpp"
click node_llm "https://github.com/razaxq/vocal/blob/main/native/src/LlmService.cpp"
click node_output "https://github.com/razaxq/vocal/blob/main/native/src/TextOutput.cpp"
click node_catalog "https://github.com/razaxq/vocal/blob/main/native/src/ModelCatalog.cpp"
click node_manager "https://github.com/razaxq/vocal/blob/main/native/src/ModelManager.cpp"
click node_dictionary "https://github.com/razaxq/vocal/blob/main/native/src/DesktopServices.cpp"
click node_settings "https://github.com/razaxq/vocal/blob/main/native/src/Settings.cpp"
click node_updates "https://github.com/razaxq/vocal/blob/main/native/src/NativeUpdate.h"

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_controller,node_triggers,node_platform,node_user toneBlue
class node_capture,node_segmenter,node_speech,node_stream,node_process toneAmber
class node_correction,node_cleanup,node_llm,node_output toneMint
class node_catalog,node_manager,node_dictionary toneRose
class node_settings,node_updates,node_target,node_modelhost,node_dictsource,node_llmservice toneIndigo
```

## Components

### Desktop control

- [Desktop UI and tray](https://github.com/razaxq/vocal/blob/main/native/src/main.cpp): `native/src/main.cpp`
- [App controller](https://github.com/razaxq/vocal/blob/main/native/src/AppController.cpp): `native/src/AppController.cpp`
- [Trigger handling](https://github.com/razaxq/vocal/blob/main/native/src/TriggerController.cpp): `native/src/TriggerController.cpp`
- [Windows input platform](https://github.com/razaxq/vocal/blob/main/native/src/platform/WindowsPlatform.cpp): `native/src/platform/WindowsPlatform.cpp`

### Audio and recognition

- [Audio capture](https://github.com/razaxq/vocal/blob/main/native/src/AudioCapture.cpp): `native/src/AudioCapture.cpp`
- [Audio segmentation](https://github.com/razaxq/vocal/blob/main/native/src/AudioSegmenter.cpp): `native/src/AudioSegmenter.cpp`
- [Offline recognition](https://github.com/razaxq/vocal/blob/main/native/src/SpeechWorker.cpp): `native/src/SpeechWorker.cpp`
- [Streaming recognition](https://github.com/razaxq/vocal/blob/main/native/src/StreamWorker.cpp): `native/src/StreamWorker.cpp`
- [Worker processes](https://github.com/razaxq/vocal/blob/main/native/src/WorkerProcess.cpp): `native/src/WorkerProcess.cpp`

### Text processing

- [Homophone correction](https://github.com/razaxq/vocal/blob/main/native/src/CorrectionWorker.cpp): `native/src/CorrectionWorker.cpp`
- [Spoken-text cleanup](https://github.com/razaxq/vocal/blob/main/native/src/TextCleanup.cpp): `native/src/TextCleanup.cpp`
- [AI text consolidation](https://github.com/razaxq/vocal/blob/main/native/src/LlmService.cpp): `native/src/LlmService.cpp`
- [Text insertion](https://github.com/razaxq/vocal/blob/main/native/src/TextOutput.cpp): `native/src/TextOutput.cpp`

### Models and resources

- [Model catalog](https://github.com/razaxq/vocal/blob/main/native/src/ModelCatalog.cpp): `native/src/ModelCatalog.cpp`
- [Model downloads](https://github.com/razaxq/vocal/blob/main/native/src/ModelManager.cpp): `native/src/ModelManager.cpp`
- [Dictionary services](https://github.com/razaxq/vocal/blob/main/native/src/DesktopServices.cpp): `native/src/DesktopServices.cpp`

### Settings and maintenance

- [Settings and history](https://github.com/razaxq/vocal/blob/main/native/src/Settings.cpp): `native/src/Settings.cpp`
- [Software updates](https://github.com/razaxq/vocal/blob/main/native/src/NativeUpdate.h): `native/src/NativeUpdate.h`

### Other components

- **Voice-input user**
- **Focused application**
- **Model download hosts**
- **Dictionary update source**
- **Configured AI service**

## Connections

- Voice-input user → Desktop UI and tray: configures and views
- Desktop UI and tray → App controller: invokes controls
- App controller → Settings and history: reads and writes
- App controller → Trigger handling: configures
- Trigger handling → Windows input platform: configures and receives input
- Windows input platform → Trigger handling: reports input
- Trigger handling → App controller: signals recording
- App controller → Audio capture: starts capture
- Audio capture → Audio segmentation: supplies audio
- App controller → Offline recognition: dispatches recognition
- App controller → Streaming recognition: dispatches preview
- Offline recognition → Worker processes: uses worker process
- Streaming recognition → Worker processes: uses worker process
- App controller → Homophone correction: requests correction
- App controller → Spoken-text cleanup: cleans recognized text
- App controller → AI text consolidation: requests consolidation
- AI text consolidation → Configured AI service: sends text when enabled
- App controller → Text insertion: sends final text
- Text insertion → Windows input platform: inserts into focused app
- Windows input platform → Focused application: types text
- App controller → Model downloads: requests model operations
- Model downloads → Model catalog: checks model metadata
- Model downloads → Model download hosts: downloads models
- App controller → Dictionary services: coordinates dictionary
- Dictionary services → Dictionary update source: checks for updates
- App controller → Software updates: checks software updates