# ahakeyai/desktop architecture

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

- Interactive diagram: https://gitdiagram.com/ahakeyai/desktop
- Repository: https://github.com/ahakeyai/desktop

## Overview

AhaKey Desktop is a cross-platform companion suite for the AhaKey-X1 keyboard, with configuration, AI approval hooks, and voice features. The main workflow configures keyboard behavior and routes device events through a desktop client; macOS and Windows also have distinct agent and speech paths. The graph includes the documented plugin capability and sampled native-client components. Many modules are represented from the tree or README rather than inspected source; their connections are omitted unless documented or evidenced by the source index.

Main entry points: [`ahakey-studio-tauri/src-tauri/src/backend.rs`](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/backend.rs) (Command backend), [`ahakey-studio-tauri/src-tauri/src/main.rs`](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/main.rs) (Application runtime), [`ahakey-studio-tauri/src-tauri/src/device_routing.rs`](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/device_routing.rs) (Device routing), [`ahakey-studio-tauri/src-tauri/src/state.rs`](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/state.rs) (Runtime state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_studio["Native Studio"]
  node_tauri_ui["Studio interface<br/>[main.tsx]"]
  node_tauri_app["Application runtime<br/>[main.rs]"]
  node_backend["Command backend<br/>[backend.rs]"]
  node_runtime_state["Runtime state<br/>[state.rs]"]
  node_device["Device operations<br/>[device.rs]"]
  node_device_routing["Device routing<br/>[device_routing.rs]"]
  node_ble_protocol["BLE protocol<br/>[protocol.rs]"]
  node_ble_routing["BLE routing<br/>[routing.rs]"]
  node_usb_routing["USB routing<br/>[usb_routing.rs]"]
  node_voice["Voice capture<br/>[voice.rs]"]
  node_speech["Speech engine<br/>[lib.rs]"]
  node_cloud["Cloud sessions<br/>[session.rs]"]
  node_hooks["Approval hooks<br/>[hooks.rs]"]
  node_settings["Settings<br/>[settings.rs]"]
  node_recovery["BLE recovery<br/>[recovery.rs]"]
  node_platform["Platform services<br/>[platform.rs]"]
end

subgraph group_mac["macOS Companion"]
  node_mac_app["Mac configuration UI"]
  node_mac_ble["Mac BLE manager"]
  node_mac_agent["AI approval agent<br/>[AgentManager.swift]"]
  node_mac_plugin["Mac plugin manager"]
end

subgraph group_windows["Windows Companion"]
  node_windows_ui["Windows settings UI<br/>[main_window.py]"]
  node_windows_device["Windows device service<br/>[device_service.py]"]
  node_windows_capswriter["Capswriter client<br/>[core_client.py]"]
  node_windows_asr["Local speech engine<br/>[asr_engine.py]"]
  node_windows_llm["Text assistant<br/>[llm_handler.py]"]
  node_windows_hotwords["Hotword manager<br/>[manager.py]"]
end

subgraph group_plugins["Plugin SDK"]
  node_plugin_sdk["TypeScript SDK<br/>[index.ts]"]
end

node_user(("Keyboard user"))
node_plugin_author(("Plugin developer"))

node_user -.->|"configures"| node_tauri_ui
node_tauri_ui -->|"invokes commands"| node_tauri_app
node_tauri_app -->|"registers commands"| node_backend
node_tauri_app -->|"initializes state"| node_runtime_state
node_backend -->|"uses state"| node_runtime_state
node_device_routing -->|"references"| node_backend
node_device_routing -->|"uses state"| node_runtime_state
node_tauri_app -->|"registers commands"| node_device_routing
node_backend -.->|"uses BLE"| node_ble_routing
node_backend -.->|"uses USB"| node_usb_routing
node_backend -.->|"uses device"| node_device
node_ble_routing -->|"uses protocol"| node_ble_protocol
node_user -.->|"configures"| node_mac_app
node_mac_agent -->|"coordinates access"| node_mac_ble
node_mac_app -->|"uses BLE"| node_mac_ble
node_user -.->|"configures"| node_windows_ui
node_windows_ui -.->|"uses device service"| node_windows_device
node_windows_capswriter -.->|"uses speech engine"| node_windows_asr
node_windows_llm -->|"gets hotwords"| node_windows_hotwords
node_plugin_author -->|"develops plugins"| node_plugin_sdk
node_mac_plugin -.->|"uses SDK"| node_plugin_sdk

click node_tauri_ui "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src/main.tsx"
click node_tauri_app "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/main.rs"
click node_backend "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/backend.rs"
click node_runtime_state "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/state.rs"
click node_device "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/device.rs"
click node_device_routing "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/device_routing.rs"
click node_ble_protocol "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/ble/src/protocol.rs"
click node_ble_routing "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/ble/src/routing.rs"
click node_usb_routing "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/ble/src/usb_routing.rs"
click node_voice "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/voice.rs"
click node_speech "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/speech/src/lib.rs"
click node_cloud "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/cloud/src/session.rs"
click node_hooks "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/hooks.rs"
click node_settings "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/settings.rs"
click node_recovery "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/recovery.rs"
click node_platform "https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/platform.rs"
click node_mac_app "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-mac/Sources/Views/AhaKeyStudioView.swift"
click node_mac_ble "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-mac/Sources/BLE/AhaKeyBLEManager.swift"
click node_mac_agent "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-mac/Sources/Utilities/AgentManager.swift"
click node_mac_plugin "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-mac/Sources/AhaKeyPluginKit/PluginManager.swift"
click node_windows_ui "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/src/ui/main_window.py"
click node_windows_device "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/src/comm/device_service.py"
click node_windows_capswriter "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/Capswriter-master/Capswriter-master/core_client.py"
click node_windows_asr "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/fun_asr_gguf/asr_engine.py"
click node_windows_llm "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/llm/llm_handler.py"
click node_windows_hotwords "https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/hotword/manager.py"
click node_plugin_sdk "https://github.com/ahakeyai/desktop/blob/main/sdks/typescript/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_tauri_ui,node_tauri_app,node_backend,node_runtime_state,node_device,node_device_routing,node_ble_protocol,node_ble_routing,node_usb_routing,node_voice,node_speech,node_cloud,node_hooks,node_settings,node_recovery,node_platform,node_user toneBlue
class node_mac_app,node_mac_ble,node_mac_agent,node_mac_plugin toneAmber
class node_windows_ui,node_windows_device,node_windows_capswriter,node_windows_asr,node_windows_llm,node_windows_hotwords toneMint
class node_plugin_sdk toneRose
class node_plugin_author toneIndigo
```

## Components

### Native Studio

- [Studio interface](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src/main.tsx): `ahakey-studio-tauri/src/main.tsx`
- [Application runtime](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/main.rs): `ahakey-studio-tauri/src-tauri/src/main.rs`
- [Command backend](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/backend.rs): `ahakey-studio-tauri/src-tauri/src/backend.rs`
- [Runtime state](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/state.rs): `ahakey-studio-tauri/src-tauri/src/state.rs`
- [Device operations](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/device.rs): `ahakey-studio-tauri/src-tauri/src/device.rs`
- [Device routing](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/device_routing.rs): `ahakey-studio-tauri/src-tauri/src/device_routing.rs`
- [BLE protocol](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/ble/src/protocol.rs): `ahakey-studio-tauri/crates/ble/src/protocol.rs`
- [BLE routing](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/ble/src/routing.rs): `ahakey-studio-tauri/crates/ble/src/routing.rs`
- [USB routing](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/ble/src/usb_routing.rs): `ahakey-studio-tauri/crates/ble/src/usb_routing.rs`
- [Voice capture](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/voice.rs): `ahakey-studio-tauri/src-tauri/src/voice.rs`
- [Speech engine](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/speech/src/lib.rs): `ahakey-studio-tauri/crates/speech/src/lib.rs`
- [Cloud sessions](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/crates/cloud/src/session.rs): `ahakey-studio-tauri/crates/cloud/src/session.rs`
- [Approval hooks](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/hooks.rs): `ahakey-studio-tauri/src-tauri/src/hooks.rs`
- [Settings](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/settings.rs): `ahakey-studio-tauri/src-tauri/src/settings.rs`
- [BLE recovery](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/recovery.rs): `ahakey-studio-tauri/src-tauri/src/recovery.rs`
- [Platform services](https://github.com/ahakeyai/desktop/blob/main/ahakey-studio-tauri/src-tauri/src/platform.rs): `ahakey-studio-tauri/src-tauri/src/platform.rs`

### macOS Companion

- [Mac configuration UI](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-mac/Sources/Views/AhaKeyStudioView.swift): `ahakeyconfig-mac/Sources/Views/AhaKeyStudioView.swift`
- [Mac BLE manager](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-mac/Sources/BLE/AhaKeyBLEManager.swift): `ahakeyconfig-mac/Sources/BLE/AhaKeyBLEManager.swift`
- [AI approval agent](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-mac/Sources/Utilities/AgentManager.swift): `ahakeyconfig-mac/Sources/Utilities/AgentManager.swift`
- [Mac plugin manager](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-mac/Sources/AhaKeyPluginKit/PluginManager.swift): `ahakeyconfig-mac/Sources/AhaKeyPluginKit/PluginManager.swift`

### Windows Companion

- [Windows settings UI](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/src/ui/main_window.py): `ahakeyconfig-win-python/src/ui/main_window.py`
- [Windows device service](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/src/comm/device_service.py): `ahakeyconfig-win-python/src/comm/device_service.py`
- [Capswriter client](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/Capswriter-master/Capswriter-master/core_client.py): `ahakeyconfig-win-python/Capswriter-master/Capswriter-master/core_client.py`
- [Local speech engine](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/fun_asr_gguf/asr_engine.py): `ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/fun_asr_gguf/asr_engine.py`
- [Text assistant](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/llm/llm_handler.py): `ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/llm/llm_handler.py`
- [Hotword manager](https://github.com/ahakeyai/desktop/blob/main/ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/hotword/manager.py): `ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/hotword/manager.py`

### Plugin SDK

- [TypeScript SDK](https://github.com/ahakeyai/desktop/blob/main/sdks/typescript/src/index.ts): `sdks/typescript/src/index.ts`

### Other components

- **Keyboard user**
- **Plugin developer**

## Connections

- Keyboard user → Studio interface: configures (evidence: `README.md`)
- Studio interface → Application runtime: invokes commands (evidence: `ahakey-studio-tauri/src/main.tsx`)
- Application runtime → Command backend: registers commands (evidence: `ahakey-studio-tauri/src-tauri/src/main.rs`)
- Application runtime → Runtime state: initializes state (evidence: `ahakey-studio-tauri/src-tauri/src/main.rs`)
- Command backend → Runtime state: uses state (evidence: `ahakey-studio-tauri/src-tauri/src/backend.rs`)
- Device routing → Command backend: references (evidence: `ahakey-studio-tauri/src-tauri/src/device_routing.rs`)
- Device routing → Runtime state: uses state (evidence: `ahakey-studio-tauri/src-tauri/src/device_routing.rs`)
- Application runtime → Device routing: registers commands (evidence: `ahakey-studio-tauri/src-tauri/src/main.rs`)
- Command backend → BLE routing: uses BLE
- Command backend → USB routing: uses USB
- Command backend → Device operations: uses device (evidence: `ahakey-studio-tauri/src-tauri/src/backend.rs`)
- BLE routing → BLE protocol: uses protocol (evidence: `ahakey-studio-tauri/crates/ble/src/routing.rs`)
- Keyboard user → Mac configuration UI: configures (evidence: `README.md`)
- AI approval agent → Mac BLE manager: coordinates access (evidence: `ahakeyconfig-mac/Sources/Utilities/AgentManager.swift`)
- Mac configuration UI → Mac BLE manager: uses BLE
- Keyboard user → Windows settings UI: configures (evidence: `README.md`)
- Windows settings UI → Windows device service: uses device service
- Capswriter client → Local speech engine: uses speech engine
- Text assistant → Hotword manager: gets hotwords (evidence: `ahakeyconfig-win-python/Capswriter-master/Capswriter-master/util/llm/llm_handler.py`)
- Plugin developer → TypeScript SDK: develops plugins (evidence: `README.md`)
- Mac plugin manager → TypeScript SDK: uses SDK
