# janvarev/irene-voice-assistant architecture

> Architecture diagram of the GitHub repository janvarev/irene-voice-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/janvarev/irene-voice-assistant
- Repository: https://github.com/janvarev/irene-voice-assistant

## Overview

##### Project Type and Purpose
- This is an offline voice assistant application built in Python. Its core purpose is to perform offline speech recognition (primarily using Vosk) and text-to-speech (using pyttsx-based solutions) while processing commands via a modular plugin (or “skill”) architecture.
- The README clarifies that it supports both voice interaction and text-based command simulation, with additional support for configuration via a settings manager and optional web APIs. It also explains integrations like Docker deployments, and even multi-microphone/client-server modes.

##### File Structure for Architectural Clues
- There are top-level components for core functionality (e.g., vacore.py, runva_cmdline.py, runva_vosk.py, runva_webapi.py) which indicate the main operational engine.
- The “lingua_franca” folder contains modules for language parsing/formatting and resource files for different languages – this forms the natural language processing (NLP) component.
- The “plugins”, “plugins_inactive”, and “plugins_vasi” directories group the skill extensions that add specialized behaviors. Also, the inclusion of “jaa.py” (the lightweight plugin engine) emphasizes that plugin orchestration is a core design pattern.
- There are supporting directories:
- “docs” for installation/deployment instructions,
- “model” for ASR models and related configuration,
- “mpcapi” for potential integration with external media players (like MPC-HC),
- “mic_client” and “webapi_client” which are front-end interfaces.
- Multiple configuration and Docker-related files (Dockerfile, options_docker etc.) indicate that the deployment and environment management are designed to be modular and containerized.

##### Main Components
A. Core Engine:
- The main control center is likely housed in “vacore.py” along with supporting scripts (runva_* files). This is responsible for initializing components, processing voice commands, and orchestrating responses.
- It interacts with configuration files (options/core.json) to load settings.
B. Speech Recognition:
- The project offers offline recognition primarily using Vosk (runva_vosk.py) and optionally the SpeechRecognition alternative (runva_speechrecognition.py). The “model” folder contains ASR models and resources needed for these.
- A helper component “vosk_asr_server.py” hints at a service-oriented approach for speech-to-text.
C. Text-to-Speech (TTS):
- The assistant leverages TTS engines (pyttsx, Silero, Elevenlabs, etc.) as indicated in both README and plugin implementations like “plugin_tts_*”.
D. Plugin (Skill) Engine:
E. Language Processing:
- The “lingua_franca” modules manage natural language parsing, number-to-text conversion, and language-specific formatting/expansion, crucial for correctly interpreting spoken commands.
F. External Interfaces:
- Web API integration (runva_webapi.py and the “webapi_client” folder) adds a network/HTTP layer for remote control or integration.
- The mic_client (with HTML/JS) provides an additional UI for audio input/output.
G. Configuration and Deployment:
- The “options” folder (created upon first run) and provided configuration JSON files determine runtime settings.
- Docker support is integrated (Dockerfile, docs/INSTALL_DOCKER.md, etc.) making containerized deployment central.

##### Relationships and Interactions
- Speech Recognition Engine (Vosk-based or SpeechRecognition alternative)
- TTS Engine(s)
- Plugin Manager (powered by Jaa.py and loading from various plugins folders)
- Language Processing Module (lingua_franca)
- The processed command then routes to the Plugin Manager which dynamically activates the corresponding plugin from the “plugins” directory.
- Data flows from the Plugin Manager to external systems (like MPC-HC via mpcapi) or web interfaces (webapi_client).
- Configuration flows: settings loaded into the core from options files.
- Deployment aspects: Docker-ized components and web manager (via runva_settings_manager.py) used for administrative tasks.

##### Architectural Patterns and Technologies
- The design uses a modular and pluggable architecture allowing for dynamic skill loading, which is essential for extensibility.
- The separation between core processing, speech-to-text, TTS, and plugin handling enforces the Single Responsibility Principle.
- The use of multiple deployment strategies (native Python execution and Docker containers) suggests a layered and environment-agnostic design.
- Integration with external hardware (microphones, MPC-HC) and web-based clients underscores a hybrid (client-server) design pattern in parts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Components
    subgraph "Backend Components"
        VACORE["VACore / Main Controller"]:::core
        subgraph "Speech Recognition"
            VOSK["Speech Recognition (runva_vosk.py)"]:::engine
            ASRServer["ASR Server (vosk_asr_server.py)"]:::engine
            ASRModels["ASR Models (model/)"]:::config
        end
        subgraph "TTS Engine"
            TTS_PY["TTS Module (plugin_tts_pyttsx.py)"]:::engine
            TTS_CON["TTS Console (plugin_tts_console.py)"]:::engine
            TTS_SV3["TTS Silero V3 (plugin_tts_silero_v3.py)"]:::engine
            TTS_SV4["TTS Silero V4 (plugin_tts_silero_v4.py)"]:::engine
            TTS_EL["TTS Elevenlabs (plugin_tts_elevenlabs.py)"]:::engine
        end
        subgraph "Plugin Manager"
            JAA["Plugin Engine (jaa.py)"]:::engine
            Plugins["Active Plugins (plugins/)"]:::engine
            PluginsInactive["Inactive Plugins (plugins_inactive/)"]:::engine
            PluginsVasi["Vasi Plugins (plugins_vasi/)"]:::engine
        end
        Language["Language Processing (lingua_franca/)"]:::engine
        Config["Configuration & Settings"]:::config

        %% Data Flow in Backend
        VACORE -->|"sends audio"| VOSK
        VOSK -->|"outputs text"| Language
        Language -->|"interprets"| JAA
        JAA -->|"triggers"| Plugins
        JAA -->|"fallback"| PluginsInactive
        JAA -->|"specialized skills"| PluginsVasi
        Plugins -->|"calls TTS"| TTS_PY
        Plugins -->|"calls TTS"| TTS_CON
        Plugins -->|"calls TTS"| TTS_SV3
        Plugins -->|"calls TTS"| TTS_SV4
        Plugins -->|"calls TTS"| TTS_EL
        Config -->|"loads settings"| VACORE
    end

    %% Interface Components
    subgraph "Interface Components"
        WebAPI["Web API Module (runva_webapi.py)"]:::interface
        WebClient["Web API Client (webapi_client/)"]:::interface
        MicClient["Mic Client Interface (mic_client/)"]:::interface
        WebAPI -->|"communicates with"| WebClient
    end

    %% External Integration
    subgraph "External Integration"
        MPC["MPC API (mpcapi/)"]:::external
        JAA -->|"integrates with"| MPC
    end

    %% Deployment & Configuration
    subgraph "Deployment & Configuration"
        Settings["Settings Manager (runva_settings_manager.py)"]:::config
        CoreConfig["Core Config (options_docker/core.json)"]:::config
        DockerFile["Docker Setup (Dockerfile)"]:::config
        DockerDocs["Docker Docs (docs/INSTALL_DOCKER.md)"]:::config
    end

    %% Inter-zone Connections
    VACORE -->|"manages"| WebAPI
    VACORE -->|"manages"| MicClient
    Settings -->|"configures"| VACORE
    CoreConfig -->|"provides config"| Config
    DockerFile -->|"deploys"| VACORE
    DockerDocs -->|"instructions"| DockerFile

    %% Click Events
    click VACORE "https://github.com/janvarev/irene-voice-assistant/blob/master/vacore.py"
    click VOSK "https://github.com/janvarev/irene-voice-assistant/blob/master/runva_vosk.py"
    click ASRServer "https://github.com/janvarev/irene-voice-assistant/blob/master/vosk_asr_server.py"
    click ASRModels "https://github.com/janvarev/irene-voice-assistant/tree/master/model/"
    click TTS_PY "https://github.com/janvarev/irene-voice-assistant/blob/master/plugins/plugin_tts_pyttsx.py"
    click TTS_CON "https://github.com/janvarev/irene-voice-assistant/blob/master/plugins/plugin_tts_console.py"
    click TTS_SV3 "https://github.com/janvarev/irene-voice-assistant/blob/master/plugins/plugin_tts_silero_v3.py"
    click TTS_SV4 "https://github.com/janvarev/irene-voice-assistant/blob/master/plugins/plugin_tts_silero_v4.py"
    click TTS_EL "https://github.com/janvarev/irene-voice-assistant/blob/master/plugins/plugin_tts_elevenlabs.py"
    click JAA "https://github.com/janvarev/irene-voice-assistant/blob/master/jaa.py"
    click Plugins "https://github.com/janvarev/irene-voice-assistant/tree/master/plugins/"
    click PluginsInactive "https://github.com/janvarev/irene-voice-assistant/tree/master/plugins_inactive/"
    click PluginsVasi "https://github.com/janvarev/irene-voice-assistant/tree/master/plugins_vasi/"
    click Language "https://github.com/janvarev/irene-voice-assistant/tree/master/lingua_franca/"
    click WebAPI "https://github.com/janvarev/irene-voice-assistant/blob/master/runva_webapi.py"
    click WebClient "https://github.com/janvarev/irene-voice-assistant/tree/master/webapi_client/"
    click MicClient "https://github.com/janvarev/irene-voice-assistant/tree/master/mic_client/"
    click CoreConfig "https://github.com/janvarev/irene-voice-assistant/blob/master/options_docker/core.json"
    click DockerFile "https://github.com/janvarev/irene-voice-assistant/tree/master/Dockerfile"
    click Settings "https://github.com/janvarev/irene-voice-assistant/blob/master/runva_settings_manager.py"
    click DockerDocs "https://github.com/janvarev/irene-voice-assistant/blob/master/docs/INSTALL_DOCKER.md"
    click MPC "https://github.com/janvarev/irene-voice-assistant/tree/master/mpcapi/"

    %% Styles
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef engine fill:#cfc,stroke:#333,stroke-width:2px;
    classDef interface fill:#fcf,stroke:#333,stroke-width:2px;
    classDef config fill:#ff9,stroke:#333,stroke-width:2px;
    classDef external fill:#fbb,stroke:#333,stroke-width:2px;
```
