# moin-ansari-o8/auralyx architecture

> Architecture diagram of the GitHub repository moin-ansari-o8/auralyx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moin-ansari-o8/auralyx
- Repository: https://github.com/moin-ansari-o8/auralyx

## Overview

1. **Product shape**
   Auralyx is a Windows desktop dictation app, not a browser-only app. The Python backend runs the real-time voice pipeline and local API, while a React/Vite frontend renders the dashboard inside a PyWebView desktop window.

2. **Top-level runtime boundary**
   `launcher.py` is the main entry point for the desktop experience. It starts or attaches to the backend runtime, opens the native window, and acts as the bridge between the packaged Python process and the embedded web UI.

3. **Backend orchestration layer**
   The backend is centered around `backend/main.py` and `backend/runtime.py`. These coordinate the dictation lifecycle, background service threads, single-instance behavior, and the handoff between audio capture, transcription, refinement, persistence, and UI updates.

4. **Audio capture and speech pipeline**
   `backend/audio_recorder.py` captures microphone audio, `backend/speech_to_text.py` performs offline transcription with faster-whisper, and the surrounding logic uses VAD-related filtering to separate speech from silence. This is the core “input to raw text” path.

5. **AI refinement boundary**
   `backend/ai_provider_manager.py` routes refinement requests to configured providers, and `backend/ai_refiner.py` shapes the prompt/output based on the selected writing mode. The repo supports multiple AI backends, including local/offline and cloud providers, so this layer is the main external-service integration point.

6. **System integration for dictation output**
   `backend/paste_manager.py` handles clipboard/writeback behavior and automatic pasting into the active application. Hotkey and global-input concerns are isolated in `backend/hotkey_diagnostic.py` and the main dictation controller, which is important because the app operates outside the browser sandbox and interacts with the OS.

7. **API and real-time UI sync**
   `backend/api/server.py` exposes the local FastAPI service. It provides REST endpoints for commands, settings, history, and refinement, plus a WebSocket channel for live status such as recording state, processing state, and audio level. The frontend depends on this channel for real-time dashboards and waveform visualization.

8. **Persistence and local state**
   `backend/data_storage.py`, `backend/settings_store.py`, and the `data/auralyx.db` / JSON files represent local persistence. The app stores transcriptions, app settings, and operational history on disk rather than in a remote database, reinforcing the offline-first design.

9. **Frontend structure**
   The React app lives under `frontend/src` and is organized into pages, layout components, sidebar/titlebar controls, and reusable UI primitives. `frontend/src/hooks/useWebSocket.js` and `useAudioAnalyser.js` connect the UI to backend status and visual audio feedback. The pages (`Home`, `Insights`, `Dictionary`, `Snippets`, `Settings`) suggest a dashboard-centric workspace around dictation history and configuration.

10. **Desktop UI shell**
   The frontend is styled as a custom application shell with `AppShell`, `MainWorkspace`, `Sidebar`, `Titlebar`, modals, and floating panels. This indicates the UI is intended to behave like a native app window rather than a conventional website.

11. **Packaging and distribution**
   `build-exe.ps1`, `Auralyx.spec`, and `build-installer.ps1` show a two-stage packaging flow: build the React assets, then bundle Python plus the frontend into a single executable, and optionally wrap it in an installer. This affects architecture because the frontend is embedded as static build output, not served by a separate web host in production.

12. **Operational safety and single-instance control**
   The repo includes lock/PID-based single-instance protection, tray behavior, and encoding safeguards in the backend/runtime path. These are important architectural boundaries because the app is designed to live in the system tray and avoid multiple active dictation workers.

13. **Tests and validation**
   The `tests/` folder covers backend behavior, provider fallback, hotkeys, icon/logo integration, and faster-whisper integration points. That suggests the most important failure modes are in OS integration, provider routing, and packaging assets rather than in isolated UI logic.

14. **How the main data flow works**
   User action enters through a global hotkey or tray-driven command, audio is captured and transcribed locally, text is optionally refined through a chosen AI provider, the result is saved to local history/settings stores, and the polished text is pasted into the active application. In parallel, the backend pushes state updates to the React dashboard over WebSocket so the UI reflects the live session.

Main entry points: [`backend/main.py`](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/main.py) (main), [`frontend/src/components/layout/AppShell.jsx`](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/components/layout/AppShell.jsx) (App shell), [`frontend/src/pages/HomePage.jsx`](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/HomePage.jsx) (Home), [`launcher.py`](https://github.com/moin-ansari-o8/auralyx/blob/master/launcher.py) (launcher.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_desktop["Desktop shell"]
  node_launcher_py["launcher.py<br/>desktop entrypoint<br/>[launcher.py]"]
end

subgraph group_group_backend["Backend pipeline"]
  node_backend_main["main<br/>orchestrator<br/>[main.py]"]
  node_backend_runtime["runtime<br/>process control<br/>[runtime.py]"]
  node_audio_recorder(("Recorder<br/>audio capture<br/>[audio_recorder.py]"))
  node_speech_to_text(("Speech STT<br/>transcription<br/>[speech_to_text.py]"))
  node_ai_refiner(("Refiner<br/>prompt shaping<br/>[ai_refiner.py]"))
  node_ai_provider_manager["Provider mgr<br/>ai routing"]
  node_paste_manager["Paste mgr<br/>os writeback<br/>[paste_manager.py]"]
  node_data_storage[("Storage<br/>history store<br/>[data_storage.py]")]
  node_settings_store[("Settings<br/>local config<br/>[settings_store.py]")]
  node_hotkey_diagnostic["Hotkey diag<br/>global input"]
end

subgraph group_group_api["Local API"]
  node_api_server["API server<br/>fastapi service<br/>[server.py]"]
end

subgraph group_group_frontend["Frontend UI"]
  node_frontend_main["main.jsx<br/>ui bootstrap<br/>[main.jsx]"]
  node_app_shell["App shell<br/>desktop layout<br/>[AppShell.jsx]"]
  node_home_page["Home<br/>dashboard page<br/>[HomePage.jsx]"]
  node_insights_page["Insights<br/>dashboard page<br/>[InsightsPage.jsx]"]
  node_settings_page["Settings<br/>dashboard page<br/>[SettingsPage.jsx]"]
  node_dictionary_page["Dictionary<br/>dashboard page<br/>[DictionaryPage.jsx]"]
  node_snippets_page["Snippets<br/>dashboard page<br/>[SnippetsPage.jsx]"]
  node_use_websocket["WS hook<br/>realtime sync<br/>[useWebSocket.js]"]
  node_use_audio_analyser["Audio hook<br/>visual feedback"]
end

node_launcher_py -->|"starts"| node_backend_runtime
node_launcher_py -->|"opens"| node_app_shell
node_backend_runtime -->|"boots"| node_backend_main
node_backend_main -->|"captures"| node_audio_recorder
node_backend_main -->|"transcribes"| node_speech_to_text
node_backend_main -->|"refines"| node_ai_refiner
node_ai_refiner -->|"routes via"| node_ai_provider_manager
node_backend_main -->|"writes back"| node_paste_manager
node_backend_main -->|"persists"| node_data_storage
node_backend_main -->|"reads/writes"| node_settings_store
node_backend_main -->|"monitors"| node_hotkey_diagnostic
node_backend_main -->|"publishes state"| node_api_server
node_api_server -->|"streams"| node_use_websocket
node_frontend_main -->|"mounts"| node_app_shell
node_app_shell -->|"navigates to"| node_home_page
node_app_shell -->|"navigates to"| node_insights_page
node_app_shell -->|"navigates to"| node_settings_page
node_app_shell -->|"navigates to"| node_dictionary_page
node_app_shell -->|"navigates to"| node_snippets_page
node_home_page -->|"subscribes"| node_use_websocket
node_home_page -->|"visualizes"| node_use_audio_analyser
node_settings_page -->|"configures"| node_settings_store

click node_launcher_py "https://github.com/moin-ansari-o8/auralyx/blob/master/launcher.py"
click node_backend_main "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/main.py"
click node_backend_runtime "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/runtime.py"
click node_audio_recorder "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/audio_recorder.py"
click node_speech_to_text "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/speech_to_text.py"
click node_ai_refiner "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/ai_refiner.py"
click node_ai_provider_manager "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/ai_provider_manager.py"
click node_paste_manager "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/paste_manager.py"
click node_data_storage "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/data_storage.py"
click node_settings_store "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/settings_store.py"
click node_hotkey_diagnostic "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/hotkey_diagnostic.py"
click node_api_server "https://github.com/moin-ansari-o8/auralyx/blob/master/backend/api/server.py"
click node_frontend_main "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/main.jsx"
click node_app_shell "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/components/layout/AppShell.jsx"
click node_home_page "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/HomePage.jsx"
click node_insights_page "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/InsightsPage.jsx"
click node_settings_page "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/SettingsPage.jsx"
click node_dictionary_page "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/DictionaryPage.jsx"
click node_snippets_page "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/SnippetsPage.jsx"
click node_use_websocket "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/hooks/useWebSocket.js"
click node_use_audio_analyser "https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/hooks/useAudioAnalyser.js"

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_launcher_py toneBlue
class node_backend_main,node_backend_runtime,node_audio_recorder,node_speech_to_text,node_ai_refiner,node_ai_provider_manager,node_paste_manager,node_data_storage,node_settings_store,node_hotkey_diagnostic toneAmber
class node_api_server toneMint
class node_frontend_main,node_app_shell,node_home_page,node_insights_page,node_settings_page,node_dictionary_page,node_snippets_page,node_use_websocket,node_use_audio_analyser toneRose
```

## Components

### Desktop shell

Native entrypoint and window/runtime boundary for the packaged app.

- [launcher.py](https://github.com/moin-ansari-o8/auralyx/blob/master/launcher.py): desktop entrypoint · Starts or attaches to the backend runtime and opens the native PyWebView window. · `launcher.py`

### Backend pipeline

Python services for capture, transcription, refinement, persistence, and OS integration.

- [main](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/main.py): orchestrator · Coordinates the dictation app lifecycle and delegates work across backend subsystems. · `backend/main.py`
- [runtime](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/runtime.py): process control · Manages startup, single-instance behavior, and the long-lived backend process. · `backend/runtime.py`
- [Recorder](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/audio_recorder.py): audio capture · Captures microphone audio for the live dictation pipeline. · `backend/audio_recorder.py`
- [Speech STT](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/speech_to_text.py): transcription · Runs offline speech-to-text using faster-whisper and returns raw text. · `backend/speech_to_text.py`
- [Refiner](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/ai_refiner.py): prompt shaping · Transforms raw text into polished output based on writing mode. · `backend/ai_refiner.py`
- [Provider mgr](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/ai_provider_manager.py): ai routing · Selects and routes refinement requests across local and cloud AI providers. · `backend/ai_provider_manager.py`
- [Paste mgr](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/paste_manager.py): os writeback · Writes finalized text back into the active application via clipboard or paste actions. · `backend/paste_manager.py`
- [Storage](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/data_storage.py): history store · Persists transcription history and operational records on disk. · `backend/data_storage.py`
- [Settings](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/settings_store.py): local config · Loads and saves application settings and user preferences. · `backend/settings_store.py`
- [Hotkey diag](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/hotkey_diagnostic.py): global input · Diagnoses global hotkey and OS input behavior for dictation control. · `backend/hotkey_diagnostic.py`

### Local API

FastAPI server and realtime status channel consumed by the desktop UI.

- [API server](https://github.com/moin-ansari-o8/auralyx/blob/master/backend/api/server.py): fastapi service · Exposes local REST commands, settings, history, and refinement endpoints. · `backend/api/server.py`

### Frontend UI

React/Vite dashboard embedded in the desktop window.

- [main.jsx](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/main.jsx): ui bootstrap · Bootstraps the React application inside the desktop window. · `frontend/src/main.jsx`
- [App shell](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/components/layout/AppShell.jsx): desktop layout · Provides the native-style application frame, workspace, sidebar, and titlebar. · `frontend/src/components/layout/AppShell.jsx`
- [Home](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/HomePage.jsx): dashboard page · Primary workspace for live dictation status, history, and quick actions. · `frontend/src/pages/HomePage.jsx`
- [Insights](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/InsightsPage.jsx): dashboard page · Shows usage and analysis views for stored dictation data. · `frontend/src/pages/InsightsPage.jsx`
- [Settings](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/SettingsPage.jsx): dashboard page · Manages configuration and app preferences from the UI. · `frontend/src/pages/SettingsPage.jsx`
- [Dictionary](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/DictionaryPage.jsx): dashboard page · Manages custom vocabulary used by the dictation workflow. · `frontend/src/pages/DictionaryPage.jsx`
- [Snippets](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/pages/SnippetsPage.jsx): dashboard page · Organizes reusable text snippets for faster insertion. · `frontend/src/pages/SnippetsPage.jsx`
- [WS hook](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/hooks/useWebSocket.js): realtime sync · Consumes backend status updates for recording state, processing state, and audio levels. · `frontend/src/hooks/useWebSocket.js`
- [Audio hook](https://github.com/moin-ansari-o8/auralyx/blob/master/frontend/src/hooks/useAudioAnalyser.js): visual feedback · Drives waveform and audio level visualization from live input. · `frontend/src/hooks/useAudioAnalyser.js`

## Connections

- launcher.py → runtime: starts · Launches or attaches to the backend process.
- launcher.py → App shell: opens · Creates the native desktop window that hosts the UI.
- runtime → main: boots · Hands control to the main backend orchestrator.
- main → Recorder: captures · Initiates microphone capture for dictation.
- main → Speech STT: transcribes · Sends captured audio to offline speech recognition.
- main → Refiner: refines · Applies writing-mode aware refinement to raw text.
- Refiner → Provider mgr: routes via · Delegates provider selection and external model calls.
- main → Paste mgr: writes back · Pastes finalized text into the active application.
- main → Storage: persists · Stores history and session artifacts locally.
- main → Settings: reads/writes · Uses local settings for runtime behavior and preferences.
- main → Hotkey diag: monitors · Tracks global input and hotkey health.
- main → API server: publishes state · Feeds command and status data to the local API.
- API server → WS hook: streams · Pushes live recording and processing updates to the UI.
- main.jsx → App shell: mounts · Bootstraps the desktop-oriented React shell.
- App shell → Home: navigates to · Hosts the main dashboard page.
- App shell → Insights: navigates to · Hosts analytics and history views.
- App shell → Settings: navigates to · Hosts configuration screens.
- App shell → Dictionary: navigates to · Hosts vocabulary management.
- App shell → Snippets: navigates to · Hosts reusable snippets.
- Home → WS hook: subscribes · Consumes live backend status for the dashboard.
- Home → Audio hook: visualizes · Renders audio feedback and waveform state.
- Settings → Settings: configures · Reflects and updates persisted settings through the backend.
