# misyaguziya/vrct architecture

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

- Interactive diagram: https://gitdiagram.com/misyaguziya/vrct
- Repository: https://github.com/misyaguziya/vrct

## Overview

1. **Overall shape**
   - VRCT is a desktop application for VRChat conversation support, built as a three-part system: a **Tauri shell** for desktop integration, a **React/Vite UI** for the user experience, and a **Python backend** for audio, translation, overlay, and integrations.
   - The architecture is centered on the frontend driving user interaction, while the Python process performs most runtime work.

2. **Desktop host and process boundary**
   - `src-tauri` is the native desktop container. It packages the app, manages the window, permissions/capabilities, and platform-specific build/release behavior.
   - The Tauri layer is the boundary between the OS and the app: it launches the Python backend, hosts the web UI, and handles native capabilities such as window control and system integration.

3. **Frontend application layer**
   - `src-ui` is the main user-facing app, organized around **pages** (`main_page`, `config_page`) and reusable common components.
   - It is a React codebase with state/logics separated from presentation: `views` contains UI, while `logics` holds hooks and state coordination.

4. **UI responsibility split**
   - The **main page** is the operational screen for live transcription/translation/chat flow.
   - The **config page** manages settings for devices, transcription, translation providers, hotkeys, plugins, appearance, VR-related behavior, and app metadata.
   - The UI also includes splash/loading, updating, modal, snackbar, and error boundary subsystems, which means startup, update, and failure states are first-class parts of the architecture.

5. **Frontend state and backend communication**
   - `src-ui/logics` contains hooks for backend readiness, network handling, receiving routes, volume, LLM connectivity, software updates, and stdout forwarding from Python.
   - This indicates the UI does not just render data; it actively orchestrates configuration, subscribes to backend status, and reacts to asynchronous backend events.
   - The UI talks to the backend through message/route-style communication rather than direct shared memory.

6. **Python backend as service core**
   - `src-python` is the computational core, with modules for `mainloop`, `controller`, `model`, `utils`, and error handling.
   - The backend appears structured as a long-running service that coordinates device access, transcription pipelines, translation pipelines, overlay output, websocket serving, watchdog behavior, and telemetry.

7. **Audio and speech pipeline**
   - The transcription subsystem is split into recorder, transcriber, Whisper-based transcription, and language definitions.
   - This suggests an audio flow of: device selection in the UI → backend capture via the recorder → transcription via the transcriber/Whisper layer → delivery of recognized text to downstream consumers.
   - `device_manager.py` and related docs imply explicit management of input/output audio devices and compute device selection.

8. **Translation subsystem**
   - Translation is provider-based, with support modules for **OpenAI, OpenRouter, Gemini, Groq, LM Studio, Ollama, and Plamo**.
   - There is a shared translation layer plus provider-specific adapters and settings/prompt templates under `models/translation/translation_settings`.
   - This makes translation a pluggable integration boundary: the backend normalizes requests, then dispatches to the selected provider.

9. **Output and integration channels**
   - The backend includes modules for **overlay**, **clipboard**, **OSC**, and **websocket server** output.
   - These are distinct delivery paths for translated or transcribed content:
     - overlay for on-screen rendering,
     - clipboard for copy/paste workflows,
     - OSC for external control/integration,
     - websocket for local network or UI clients.
   - The architecture therefore supports multiple consumers of the same language-processing results.

10. **Overlay and presentation support**
   - `models/overlay` contains image/font utilities and overlay rendering logic, indicating the app can present text in a dedicated always-on-top style surface.
   - The UI also has runtime controls for transparency, corner radius, font family, and window behavior, which means overlay appearance is part of the product’s core behavior, not just a theme setting.

11. **Telemetry and update awareness**
   - Telemetry is explicitly modeled under `models/telemetry`, with client/core/state modules, and the README states anonymous usage data is collected via Aptabase.
   - Updates are also integrated into the app flow through frontend update modals and backend/software-version hooks.
   - So operationally, the app includes lifecycle concerns: startup progress, update availability, and anonymous usage tracking.

12. **Plugins and extensibility**
   - The UI has a plugin system in `src-ui/plugins` and plugin controllers in the app layer.
   - The presence of plugin loading/merging/fetching latest plugin data indicates the app supports extension points rather than being a fixed monolith.
   - For a diagram, plugins should be shown as an optional externalized extension layer attached mainly to the UI/app orchestration layer.

13. **Configuration and localization**
   - Configuration is a first-class subsystem spanning the config page, backend config modules, and locale files.
   - Localization is handled through `locales/*.yml` and includes multiple languages for the UI and docs, which materially affects the rendering layer but not backend computation.
   - Settings appear to drive almost every subsystem: device choice, language selection, translation provider, hotkeys, appearance, and VR behaviors.

14. **Build, packaging, and verification**
   - The repository is a multi-toolchain desktop project:
     - **React/Vite** for frontend build,
     - **Tauri/Rust** for desktop packaging,
     - **Python** for backend runtime,
     - Windows batch scripts under `bat/` for build/install variants including CUDA support.
   - Tests are split between Python backend specs and endpoint/test-client utilities, reflecting that the backend can be validated independently of the UI.
   - For an architecture diagram, the important deployment boundary is a packaged desktop app that contains a native shell, a web UI, and a separate Python service process.

Main entry points: [`src-ui`](https://github.com/misyaguziya/vrct/tree/develop/src-ui) (UI app), [`src-python`](https://github.com/misyaguziya/vrct/tree/develop/src-python) (Python service), [`src-python/controller.py`](https://github.com/misyaguziya/vrct/blob/develop/src-python/controller.py) (Controller), [`src-tauri`](https://github.com/misyaguziya/vrct/tree/develop/src-tauri) (Tauri shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["VRCT Desktop"]
  node_vrct_app["VRCT<br/>desktop app"]
end

subgraph group_desktop["Desktop shell"]
  node_tauri_shell["Tauri shell<br/>native host"]
  node_tauri_main["Main entry<br/>rust entry<br/>[main.rs]"]
  node_tauri_lib["App bridge<br/>rust bridge<br/>[lib.rs]"]
  node_tauri_caps["Capabilities<br/>permissions"]
end

subgraph group_ui["React UI"]
  node_ui_app["UI app<br/>react app"]
  node_ui_entry["UI entry<br/>react entry<br/>[index.jsx]"]
  node_main_page["Main page<br/>operational screen"]
  node_config_page["Config page<br/>settings screen"]
  node_app_controllers["App controllers<br/>ui orchestration"]
  node_ui_logics["UI logics<br/>state/hooks"]
  node_others_layer["UI runtime<br/>shell states"]
end

subgraph group_backend["Python backend"]
  node_python_core["Python service<br/>service core"]
  node_mainloop["Main loop<br/>runtime loop<br/>[mainloop.py]"]
  node_controller["Controller<br/>orchestrator<br/>[controller.py]"]
  node_device_manager["Device manager<br/>audio devices<br/>[device_manager.py]"]
  node_transcription["Transcription<br/>speech pipeline"]
  node_translation["Translation<br/>provider pipeline"]
  node_outputs["Outputs<br/>delivery channels"]
  node_overlay["Overlay<br/>rendering"]
end

subgraph group_runtime["Runtime support"]
  node_telemetry["Telemetry<br/>usage analytics"]
  node_plugins["Plugins<br/>extensibility"]
  node_locales["Locales<br/>i18n"]
end

node_vrct_app -->|"contains"| node_tauri_shell
node_vrct_app -->|"hosts"| node_ui_app
node_vrct_app -->|"runs"| node_python_core
node_tauri_shell -->|"entry"| node_tauri_main
node_tauri_shell -->|"bridge"| node_tauri_lib
node_tauri_shell -->|"governs"| node_tauri_caps
node_ui_app -->|"boots"| node_ui_entry
node_ui_app -->|"renders"| node_main_page
node_ui_app -->|"renders"| node_config_page
node_ui_app -->|"orchestrates"| node_app_controllers
node_ui_app -->|"coordinates"| node_ui_logics
node_ui_app -->|"includes"| node_others_layer
node_ui_app -->|"extends"| node_plugins
node_ui_app -->|"localizes"| node_locales
node_python_core -->|"runs"| node_mainloop
node_python_core -->|"coordinates"| node_controller
node_controller -->|"uses"| node_device_manager
node_controller -->|"drives"| node_transcription
node_controller -->|"drives"| node_translation
node_controller -->|"emits"| node_outputs
node_outputs -->|"includes"| node_overlay
node_python_core -->|"reports"| node_telemetry
node_ui_logics -->|"messages"| node_python_core
node_app_controllers -->|"launches"| node_python_core
node_plugins -->|"hooks into"| node_app_controllers
node_locales -->|"supports"| node_config_page

click node_tauri_shell "https://github.com/misyaguziya/vrct/tree/develop/src-tauri"
click node_tauri_main "https://github.com/misyaguziya/vrct/blob/develop/src-tauri/src/main.rs"
click node_tauri_lib "https://github.com/misyaguziya/vrct/blob/develop/src-tauri/src/lib.rs"
click node_tauri_caps "https://github.com/misyaguziya/vrct/tree/develop/src-tauri/capabilities"
click node_ui_app "https://github.com/misyaguziya/vrct/tree/develop/src-ui"
click node_ui_entry "https://github.com/misyaguziya/vrct/blob/develop/src-ui/views/app/index.jsx"
click node_main_page "https://github.com/misyaguziya/vrct/tree/develop/src-ui/views/app/main_page"
click node_config_page "https://github.com/misyaguziya/vrct/tree/develop/src-ui/views/app/config_page"
click node_app_controllers "https://github.com/misyaguziya/vrct/tree/develop/src-ui/views/app/_app_controllers"
click node_ui_logics "https://github.com/misyaguziya/vrct/tree/develop/src-ui/logics"
click node_others_layer "https://github.com/misyaguziya/vrct/tree/develop/src-ui/views/app/others"
click node_python_core "https://github.com/misyaguziya/vrct/tree/develop/src-python"
click node_mainloop "https://github.com/misyaguziya/vrct/blob/develop/src-python/mainloop.py"
click node_controller "https://github.com/misyaguziya/vrct/blob/develop/src-python/controller.py"
click node_device_manager "https://github.com/misyaguziya/vrct/blob/develop/src-python/device_manager.py"
click node_transcription "https://github.com/misyaguziya/vrct/tree/develop/src-python/models/transcription"
click node_translation "https://github.com/misyaguziya/vrct/tree/develop/src-python/models/translation"
click node_outputs "https://github.com/misyaguziya/vrct/tree/develop/src-python/models"
click node_overlay "https://github.com/misyaguziya/vrct/tree/develop/src-python/models/overlay"
click node_telemetry "https://github.com/misyaguziya/vrct/tree/develop/src-python/models/telemetry"
click node_plugins "https://github.com/misyaguziya/vrct/tree/develop/src-ui/plugins"
click node_locales "https://github.com/misyaguziya/vrct/tree/develop/locales"

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_vrct_app toneBlue
class node_tauri_shell,node_tauri_main,node_tauri_lib,node_tauri_caps toneAmber
class node_ui_app,node_ui_entry,node_main_page,node_config_page,node_app_controllers,node_ui_logics,node_others_layer toneMint
class node_python_core,node_mainloop,node_controller,node_device_manager,node_transcription,node_translation,node_outputs,node_overlay toneRose
class node_telemetry,node_plugins,node_locales toneIndigo
```

## Components

### VRCT Desktop

Packaged desktop app split across Tauri, React UI, and Python service.

- **VRCT**: desktop app · Top-level desktop application combining native shell, web UI, and Python worker.

### Desktop shell

Native container, packaging, and process boundary.

- [Tauri shell](https://github.com/misyaguziya/vrct/tree/develop/src-tauri): native host · Desktop container that packages the app, manages capabilities, and bridges OS interactions. · `src-tauri`
- [Main entry](https://github.com/misyaguziya/vrct/blob/develop/src-tauri/src/main.rs): rust entry · Native process entry point for launching the desktop application. · `src-tauri/src/main.rs`
- [App bridge](https://github.com/misyaguziya/vrct/blob/develop/src-tauri/src/lib.rs): rust bridge · Tauri library layer for desktop commands and integration glue. · `src-tauri/src/lib.rs`
- [Capabilities](https://github.com/misyaguziya/vrct/tree/develop/src-tauri/capabilities): permissions · Native capability policies for windowing and system access. · `src-tauri/capabilities`

### React UI

User-facing app, state orchestration, and presentation.

- [UI app](https://github.com/misyaguziya/vrct/tree/develop/src-ui): react app · Frontend application for live operation and settings management. · `src-ui`
- [UI entry](https://github.com/misyaguziya/vrct/blob/develop/src-ui/views/app/index.jsx): react entry · Frontend bootstrap and top-level app mounting. · `src-ui/views/app/index.jsx`
- [Main page](https://github.com/misyaguziya/vrct/tree/develop/src-ui/views/app/main_page): operational screen · Live transcription, translation, and message flow screen. · `src-ui/views/app/main_page`
- [Config page](https://github.com/misyaguziya/vrct/tree/develop/src-ui/views/app/config_page): settings screen · Settings hub for devices, translation, hotkeys, plugins, appearance, and VR behavior. · `src-ui/views/app/config_page`
- [App controllers](https://github.com/misyaguziya/vrct/tree/develop/src-ui/views/app/_app_controllers): ui orchestration · Frontend controllers for window state, startup, language, sizing, and plugin loading. · `src-ui/views/app/_app_controllers`
- [UI logics](https://github.com/misyaguziya/vrct/tree/develop/src-ui/logics): state/hooks · Hooks and state coordination for backend readiness, routing, network, updates, and volume. · `src-ui/logics`
- [UI runtime](https://github.com/misyaguziya/vrct/tree/develop/src-ui/views/app/others): shell states · Splash, update, modal, snackbar, and error handling surfaces. · `src-ui/views/app/others`

### Python backend

Long-running service for audio, translation, overlay, and integrations.

- [Python service](https://github.com/misyaguziya/vrct/tree/develop/src-python): service core · Backend runtime coordinating device access, pipelines, outputs, and watchdog behavior. · `src-python`
- [Main loop](https://github.com/misyaguziya/vrct/blob/develop/src-python/mainloop.py): runtime loop · Long-running backend coordination loop. · `src-python/mainloop.py`
- [Controller](https://github.com/misyaguziya/vrct/blob/develop/src-python/controller.py): orchestrator · Coordinates backend subsystems and app-facing actions. · `src-python/controller.py`
- [Device manager](https://github.com/misyaguziya/vrct/blob/develop/src-python/device_manager.py): audio devices · Manages input/output and compute device selection. · `src-python/device_manager.py`
- [Transcription](https://github.com/misyaguziya/vrct/tree/develop/src-python/models/transcription): speech pipeline · Recorder, transcriber, Whisper layer, and language definitions. · `src-python/models/transcription`
- [Translation](https://github.com/misyaguziya/vrct/tree/develop/src-python/models/translation): provider pipeline · Pluggable translation layer with provider adapters and prompt/language settings. · `src-python/models/translation`
- [Outputs](https://github.com/misyaguziya/vrct/tree/develop/src-python/models): delivery channels · Clipboard, OSC, websocket, and overlay delivery paths. · `src-python/models`
- [Overlay](https://github.com/misyaguziya/vrct/tree/develop/src-python/models/overlay): rendering · On-screen presentation utilities and overlay rendering logic. · `src-python/models/overlay`

### Runtime support

Cross-cutting startup, updates, telemetry, and extension points.

- [Telemetry](https://github.com/misyaguziya/vrct/tree/develop/src-python/models/telemetry): usage analytics · Anonymous usage collection and telemetry client/state handling. · `src-python/models/telemetry`
- [Plugins](https://github.com/misyaguziya/vrct/tree/develop/src-ui/plugins): extensibility · Optional extension layer loaded and merged by the UI app. · `src-ui/plugins`
- [Locales](https://github.com/misyaguziya/vrct/tree/develop/locales): i18n · UI translation resources and locale helpers. · `locales`

## Connections

- VRCT → Tauri shell: contains · The desktop app is packaged through the native shell.
- VRCT → UI app: hosts · The app presents its main interface through the React frontend.
- VRCT → Python service: runs · A separate Python process performs backend work.
- Tauri shell → Main entry: entry · Native startup begins at the Tauri entrypoint.
- Tauri shell → App bridge: bridge · Desktop commands and OS integration are implemented in the Tauri library layer.
- Tauri shell → Capabilities: governs · Capabilities constrain native access and window behavior.
- UI app → UI entry: boots · Frontend rendering starts from the app entry.
- UI app → Main page: renders · Primary operational screen for live interaction.
- UI app → Config page: renders · Settings and configuration screen.
- UI app → App controllers: orchestrates · Top-level controllers manage app-wide UI behavior.
- UI app → UI logics: coordinates · Hooks and state logic drive backend communication and UI state.
- UI app → UI runtime: includes · Startup, modal, snackbar, updating, and error states are part of the UI runtime.
- UI app → Plugins: extends · Plugin loading and UI extension points attach to the frontend.
- UI app → Locales: localizes · Language resources shape the rendered UI.
- Python service → Main loop: runs · Backend work is coordinated through a persistent loop.
- Python service → Controller: coordinates · Subsystem orchestration lives in the controller layer.
- Controller → Device manager: uses · Controller relies on device selection and hardware access.
- Controller → Transcription: drives · Audio capture and speech recognition flow through the transcription pipeline.
- Controller → Translation: drives · Recognized text is routed to the provider-based translation pipeline.
- Controller → Outputs: emits · Processed results are delivered through multiple output channels.
- Outputs → Overlay: includes · Overlay is one major presentation/output path.
- Python service → Telemetry: reports · Backend state can feed anonymous usage telemetry.
- UI logics → Python service: messages · Frontend hooks communicate with the backend through route/message-style interactions.
- App controllers → Python service: launches · UI controllers start and supervise the backend process.
- Plugins → App controllers: hooks into · Plugin lifecycle is managed through app-level controllers.
- Locales → Config page: supports · Configuration UI is language-aware.