# jatinkrmalik/vocalinux architecture

> Architecture diagram of the GitHub repository jatinkrmalik/vocalinux, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jatinkrmalik/vocalinux
- Repository: https://github.com/jatinkrmalik/vocalinux

## Overview

##### Project Type and Purpose
- Vocalinux is primarily a desktop voice-dictation application for Linux (Python-based, offline speech-to-text with injection into arbitrary apps)
- It also contains a separate Next.js/React-based static “web” folder for the project’s website/documentation

##### File-Structure Analysis
Top-level directories and their roles:
- .github/ – CI pipelines (release, unified-pipeline)
- docs/ – Installation and user guides
- src/vocalinux/ – Core application code
– common_types.py – shared data types
– main.py – CLI entrypoint & startup orchestration
– speech_recognition/ – RecognitionManager + CommandProcessor
– text_injection/ – TextInjector & OS-injection logic
– ui/ – TrayIndicator, dialogs, config & logging managers, keyboard shortcut handling, audio feedback
- tests/ – Pytest suite for each module
- web/ – Next.js site (React components, hooks, Tailwind, Dockerfile)

##### Key README Insights
- Hot-key activation (double-tap Ctrl)
- Offline engines: VOSK or Whisper
- Real-time transcription → command processing (“new line”, “period”) → keystroke injection
- Configurable via JSON in ~/.config/vocalinux/
- Separate “web” site purely for marketing/documentation

a. Main Components
- CLI Entrypoint (main.py)
- Hotkey Listener & UI Layer
– TrayIndicator, SettingsDialog, LoggingDialog
- Core Orchestrator
– RecognitionManager (manages engines & recording sessions)
– CommandProcessor (maps transcripts to actions)
- Speech-Recognition Engines
– VOSK engine wrapper
– Whisper engine wrapper
- TextInjector
– Injects keystrokes/text into active window (X11/Wayland)
- AudioFeedback
– Plays start/stop/error sounds via ResourceManager
- ResourceManager
- ConfigManager
– Loads/saves JSON config; injected wherever needed
- OS & External Layers
– X11/Wayland desktop environment
– System audio input/output
– Keyboard event APIs
– Next.js app (layout.tsx, page.tsx)
– React components, hooks, API utilities
– Static hosting / Dockerized build

b. Relationships & Data Flows
1. User double-taps Ctrl → Hotkey Listener in UI
2. UI notifies RecognitionManager → start audio capture
3. Audio data → chosen engine (VOSK/Whisper) → transcript
4. Transcript → CommandProcessor → either:
– Plain text → TextInjector → OS → active window
– Control commands (new line, delete) → OS actions
5. RecognitionManager emits events → AudioFeedback (start/stop/error)
7. ConfigManager consults user settings at startup & on-the-fly

c. Architectural Patterns & Principles
- Layered architecture (Entrypoint → UI → Core → OS)
- Separation of concerns (recognition, injection, UI, config, resources)
- Event-driven flows (hotkey events, recognition events, UI events)
- Plug-in style for engines (VOSK vs. Whisper)

d. Key Technologies
- Python 3.8+, virtualenv (activate-vocalinux.sh)
- Speech engines: VOSK, Whisper
- GTK/PyGObject or equivalent for tray & dialogs
- OS hooks: evdev/libinput or xdotool for injection
- JSON for config (~/.config/vocalinux/config.json)
- Node.js, Next.js, React, Tailwind CSS for the web site
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Desktop Application
    subgraph "Desktop Application"
        direction TB
        CLI["CLI Entrypoint\n(main.py)"]:::pythoncore
        subgraph "UI & Resources"
            direction TB
            Tray["TrayIndicator"]:::uires
            Settings["SettingsDialog"]:::uires
            LoggingDlg["LoggingDialog"]:::uires
            KeyShort["KeyboardShortcuts"]:::uires
            AudioFB["AudioFeedback"]:::uires
            LogMgr["LoggingManager"]:::uires
            ConfigMgr["ConfigManager"]:::uires
            ResourceMgr["ResourceManager"]:::uires
        end
        subgraph "Core Orchestrator"
            direction TB
            RecogMgr["RecognitionManager"]:::pythoncore
            CmdProc["CommandProcessor"]:::pythoncore
        end
        TextInj["TextInjector"]:::pythoncore
        CommonTypes["Common Data Types"]:::pythoncore
        Version["Version Info"]:::pythoncore
    end

    %% Web Documentation Site
    subgraph "Web Documentation Site"
        direction TB
        Layout["Next.js Layout"]:::web
        Home["Next.js Home Page"]:::web
        Components["React Components"]:::web
        Hooks["Hooks"]:::web
        APIUtil["API Utilities"]:::web
        Docker["Docker Build"]:::web
    end

    %% External OS & Services
    subgraph "External OS & Services"
        direction TB
        X11["X11/Wayland"]:::external
        AudioAPI["System Audio I/O"]:::external
        KeyAPI["Keyboard Event API"]:::external
        ConfigStore["Config Storage\n(~/.config/vocalinux)"]:::external
    end

    %% Flows
    CLI -->|"initializes"| ConfigMgr
    CLI -->|"reads version/types"| Version
    CLI -->|"reads version/types"| CommonTypes
    CLI -->|"launches UI"| Tray
    Tray -->|"hotkey event"| KeyShort
    KeyShort -->|"double-tap Ctrl"| RecogMgr
    RecogMgr -->|"start audio"| AudioAPI
    AudioAPI -->|"audio data"| RecogMgr
    RecogMgr -->|"transcript"| CmdProc
    CmdProc -->|"plain text"| TextInj
    TextInj -->|"inject text"| KeyAPI
    CmdProc -->|"control commands"| KeyAPI
    RecogMgr -->|"events"| AudioFB
    RecogMgr -->|"events"| Tray
    AudioFB -->|"plays sounds"| AudioAPI
    Tray -->|"update icon/logs"| LogMgr
    ConfigMgr -->|"loads/saves config"| ConfigStore
    ResourceMgr -->|"provides assets"| Tray
    ResourceMgr -->|"provides assets"| AudioFB

    %% Web flows
    Layout --> Home
    Home --> Components
    Home --> Hooks
    Home --> APIUtil
    Layout --> Docker

    %% Click Events
    click CLI "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/main.py"
    click Tray "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/ui/tray_indicator.py"
    click Settings "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/ui/settings_dialog.py"
    click LoggingDlg "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/ui/logging_dialog.py"
    click RecogMgr "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/speech_recognition/recognition_manager.py"
    click CmdProc "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/speech_recognition/command_processor.py"
    click TextInj "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/text_injection/text_injector.py"
    click AudioFB "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/ui/audio_feedback.py"
    click ResourceMgr "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/utils/resource_manager.py"
    click ConfigMgr "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/ui/config_manager.py"
    click KeyShort "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/ui/keyboard_shortcuts.py"
    click LogMgr "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/ui/logging_manager.py"
    click CommonTypes "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/common_types.py"
    click Version "https://github.com/jatinkrmalik/vocalinux/blob/main/src/vocalinux/version.py"
    click X11 "https://github.com/jatinkrmalik/vocalinux/tree/main/resources/icons/scalable/"
    click AudioAPI "https://github.com/jatinkrmalik/vocalinux/tree/main/resources/sounds/"
    click Layout "https://github.com/jatinkrmalik/vocalinux/blob/main/web/src/app/layout.tsx"
    click Home "https://github.com/jatinkrmalik/vocalinux/blob/main/web/src/app/page.tsx"
    click Components "https://github.com/jatinkrmalik/vocalinux/tree/main/web/src/components/"
    click Hooks "https://github.com/jatinkrmalik/vocalinux/blob/main/web/src/hooks/use-double-press.ts"
    click APIUtil "https://github.com/jatinkrmalik/vocalinux/blob/main/web/src/lib/api/util.ts"
    click Docker "https://github.com/jatinkrmalik/vocalinux/tree/main/web/Dockerfile"

    %% Styles
    classDef pythoncore fill:#d4f4dd,stroke:#333,stroke-width:1px
    classDef uires fill:#d8eafb,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef web fill:#fde2c7,stroke:#333,stroke-width:1px
```
