# voldemort9999/subxvoice-app architecture

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

- Interactive diagram: https://gitdiagram.com/voldemort9999/subxvoice-app
- Repository: https://github.com/voldemort9999/subxvoice-app

## Overview

SUBXVoice is a cross-platform desktop dictation app: the user holds a hotkey, audio is captured and streamed for speech recognition, transcript text is cleaned or rewritten, then inserted at the cursor with the clipboard restored. The graph also preserves the dashboard, local history, account/backend, native platform support, and planned voice-agent capabilities. Relationships among unsampled modules are limited to README-documented behavior; optional or pending capabilities are dashed.

Main entry points: [`apps/desktop/src/main/workflow.ts`](https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/workflow.ts) (Dictation workflow), [`packages/core/src/pipeline.ts`](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/core/src/pipeline.ts) (Transcript pipeline), [`apps/desktop/src/renderer/src/App.tsx`](https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/renderer/src/App.tsx) (Dashboard UI), [`packages/core/src/agent/loop.ts`](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/core/src/agent/loop.ts) (Voice command agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop_app["Desktop shell<br/>[index.ts]"]
  node_renderer["Dashboard UI<br/>[App.tsx]"]
  node_product_pages["Product pages"]
  node_pill["Live dictation pill<br/>[Pill.tsx]"]
  node_account["Account and sign-in<br/>[auth.ts]"]
  node_local_data[("Local recordings and history<br/>[recordings.ts]")]
end

subgraph group_dictation["Dictation pipeline"]
  node_workflow["Dictation workflow<br/>[workflow.ts]"]
  node_pipeline["Transcript pipeline<br/>[pipeline.ts]"]
  node_stt["Speech recognition<br/>[gnani.ts]"]
  node_rewrite["Text rewrite<br/>[openrouter.ts]"]
  node_dictionary["Dictionary and rules<br/>[rules.ts]"]
end

subgraph group_platforms["Platform integration"]
  node_mac_platform["macOS platform"]
  node_win_platform["Windows platform"]
  node_mac_helper["macOS native helper<br/>[main.swift]"]
end

subgraph group_services["Providers and backend"]
  node_backend["Supabase functions"]
  node_provider_factory["Provider selection<br/>[index.ts]"]
end

subgraph group_agent["Voice agent"]
  node_agent_loop["Voice command agent<br/>[loop.ts]"]
  node_agent_actions["Desktop actions<br/>[commands.ts]"]
  node_mcp["MCP integration<br/>[index.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_desktop_app
node_desktop_app -->|"opens"| node_renderer
node_renderer -->|"routes to"| node_product_pages
node_user -->|"holds hotkey"| node_workflow
node_workflow -.->|"processes audio"| node_pipeline
node_pipeline -->|"transcribes"| node_stt
node_pipeline -->|"rewrites text"| node_rewrite
node_pipeline -->|"applies rules"| node_dictionary
node_pipeline -->|"reads vocabulary"| node_local_data
node_workflow -->|"saves recordings"| node_local_data
node_workflow -->|"uses platform"| node_mac_platform
node_workflow -->|"uses platform"| node_win_platform
node_mac_platform -.->|"delegates capture"| node_mac_helper
node_workflow -->|"shows live status"| node_pill
node_stt -->|"may authenticate via"| node_backend
node_rewrite -->|"may authenticate via"| node_backend
node_user -->|"signs in"| node_account
node_account -.->|"requests account services"| node_backend
node_renderer -->|"shows history"| node_local_data
node_provider_factory -->|"creates provider"| node_stt
node_provider_factory -->|"creates provider"| node_rewrite
node_user -.->|"speaks commands"| node_agent_loop
node_agent_loop -.->|"runs actions"| node_agent_actions
node_agent_loop -.->|"may use tools"| node_mcp

click node_desktop_app "https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/index.ts"
click node_renderer "https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/renderer/src/App.tsx"
click node_product_pages "https://github.com/voldemort9999/subxvoice-app/tree/main/apps/desktop/src/renderer/src/pages"
click node_pill "https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/renderer/src/pill/Pill.tsx"
click node_account "https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/auth.ts"
click node_local_data "https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/recordings.ts"
click node_workflow "https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/workflow.ts"
click node_pipeline "https://github.com/voldemort9999/subxvoice-app/blob/main/packages/core/src/pipeline.ts"
click node_stt "https://github.com/voldemort9999/subxvoice-app/blob/main/packages/providers/src/stt/gnani.ts"
click node_rewrite "https://github.com/voldemort9999/subxvoice-app/blob/main/packages/providers/src/llm/openrouter.ts"
click node_dictionary "https://github.com/voldemort9999/subxvoice-app/blob/main/packages/core/src/rules.ts"
click node_mac_platform "https://github.com/voldemort9999/subxvoice-app/tree/main/packages/platform-mac/src"
click node_win_platform "https://github.com/voldemort9999/subxvoice-app/tree/main/packages/platform-win/src"
click node_mac_helper "https://github.com/voldemort9999/subxvoice-app/blob/main/native/mac-helper/Sources/main.swift"
click node_backend "https://github.com/voldemort9999/subxvoice-app/tree/main/supabase/functions"
click node_agent_loop "https://github.com/voldemort9999/subxvoice-app/blob/main/packages/core/src/agent/loop.ts"
click node_agent_actions "https://github.com/voldemort9999/subxvoice-app/blob/main/packages/platform-win/src/commands.ts"
click node_mcp "https://github.com/voldemort9999/subxvoice-app/blob/main/packages/mcp/src/index.ts"
click node_provider_factory "https://github.com/voldemort9999/subxvoice-app/blob/main/packages/providers/src/index.ts"

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_desktop_app,node_renderer,node_product_pages,node_pill,node_account,node_local_data,node_user toneBlue
class node_workflow,node_pipeline,node_stt,node_rewrite,node_dictionary toneAmber
class node_mac_platform,node_win_platform,node_mac_helper toneMint
class node_backend,node_provider_factory toneRose
class node_agent_loop,node_agent_actions,node_mcp toneIndigo
```

## Components

### Desktop experience

- [Desktop shell](https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/index.ts): `apps/desktop/src/main/index.ts`
- [Dashboard UI](https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/renderer/src/App.tsx): `apps/desktop/src/renderer/src/App.tsx`
- [Product pages](https://github.com/voldemort9999/subxvoice-app/tree/main/apps/desktop/src/renderer/src/pages): `apps/desktop/src/renderer/src/pages`
- [Live dictation pill](https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/renderer/src/pill/Pill.tsx): `apps/desktop/src/renderer/src/pill/Pill.tsx`
- [Account and sign-in](https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/auth.ts): `apps/desktop/src/main/auth.ts`
- [Local recordings and history](https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/recordings.ts): `apps/desktop/src/main/recordings.ts`

### Dictation pipeline

- [Dictation workflow](https://github.com/voldemort9999/subxvoice-app/blob/main/apps/desktop/src/main/workflow.ts): `apps/desktop/src/main/workflow.ts`
- [Transcript pipeline](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/core/src/pipeline.ts): `packages/core/src/pipeline.ts`
- [Speech recognition](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/providers/src/stt/gnani.ts): `packages/providers/src/stt/gnani.ts`
- [Text rewrite](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/providers/src/llm/openrouter.ts): `packages/providers/src/llm/openrouter.ts`
- [Dictionary and rules](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/core/src/rules.ts): `packages/core/src/rules.ts`

### Platform integration

- [macOS platform](https://github.com/voldemort9999/subxvoice-app/tree/main/packages/platform-mac/src): `packages/platform-mac/src`
- [Windows platform](https://github.com/voldemort9999/subxvoice-app/tree/main/packages/platform-win/src): `packages/platform-win/src`
- [macOS native helper](https://github.com/voldemort9999/subxvoice-app/blob/main/native/mac-helper/Sources/main.swift): `native/mac-helper/Sources/main.swift`

### Providers and backend

- [Supabase functions](https://github.com/voldemort9999/subxvoice-app/tree/main/supabase/functions): `supabase/functions`
- [Provider selection](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/providers/src/index.ts): `packages/providers/src/index.ts`

### Voice agent

- [Voice command agent](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/core/src/agent/loop.ts): `packages/core/src/agent/loop.ts`
- [Desktop actions](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/platform-win/src/commands.ts): `packages/platform-win/src/commands.ts`
- [MCP integration](https://github.com/voldemort9999/subxvoice-app/blob/main/packages/mcp/src/index.ts): `packages/mcp/src/index.ts`

### Other components

- **User**

## Connections

- User → Desktop shell: uses
- Desktop shell → Dashboard UI: opens
- Dashboard UI → Product pages: routes to (evidence: `apps/desktop/src/renderer/src/App.tsx`)
- User → Dictation workflow: holds hotkey
- Dictation workflow → Transcript pipeline: processes audio
- Transcript pipeline → Speech recognition: transcribes (evidence: `packages/core/src/pipeline.ts`)
- Transcript pipeline → Text rewrite: rewrites text (evidence: `packages/core/src/pipeline.ts`)
- Transcript pipeline → Dictionary and rules: applies rules (evidence: `packages/core/src/pipeline.ts`)
- Transcript pipeline → Local recordings and history: reads vocabulary (evidence: `packages/core/src/pipeline.ts`)
- Dictation workflow → Local recordings and history: saves recordings
- Dictation workflow → macOS platform: uses platform
- Dictation workflow → Windows platform: uses platform
- macOS platform → macOS native helper: delegates capture
- Dictation workflow → Live dictation pill: shows live status
- Speech recognition → Supabase functions: may authenticate via
- Text rewrite → Supabase functions: may authenticate via
- User → Account and sign-in: signs in
- Account and sign-in → Supabase functions: requests account services
- Dashboard UI → Local recordings and history: shows history
- Provider selection → Speech recognition: creates provider (evidence: `packages/providers/src/index.ts`)
- Provider selection → Text rewrite: creates provider (evidence: `packages/providers/src/index.ts`)
- User → Voice command agent: speaks commands
- Voice command agent → Desktop actions: runs actions
- Voice command agent → MCP integration: may use tools
