# zevxn/zcue architecture

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

- Interactive diagram: https://gitdiagram.com/zevxn/zcue
- Repository: https://github.com/zevxn/zcue

## Overview

ZCue is a Windows global prompt-completion tool: a user types a prompt name or its pinyin initials in a compatible application, chooses a suggestion, and ZCue replaces the trigger with the full prompt. The runtime path is coordinated by AppController, from keyboard input through matching and suggestion display to text insertion. Separate branches support prompt management, settings, import/export, tray controls, and previews. The README documents capabilities beyond the sampled excerpts; those are represented where the file tree supports them, while uncertain internal wiring is omitted.

Main entry points: [`Services/AppController.cs`](https://github.com/zevxn/zcue/blob/master/Services/AppController.cs) (App controller), [`Views/PromptManagerWindow.xaml.cs`](https://github.com/zevxn/zcue/blob/master/Views/PromptManagerWindow.xaml.cs) (Prompt manager), [`Services/PromptCatalogService.cs`](https://github.com/zevxn/zcue/blob/master/Services/PromptCatalogService.cs) (Prompt catalog), [`Services/PromptStorageService.cs`](https://github.com/zevxn/zcue/blob/master/Services/PromptStorageService.cs) (Prompt storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Completion runtime"]
  node_app["WPF application<br/>[App.xaml.cs]"]
  node_controller["App controller<br/>[AppController.cs]"]
  node_hook["Keyboard hook"]
  node_buffer["Input buffer"]
  node_match["Prompt matching"]
  node_suggestions["Suggestion window"]
  node_ghost["Ghost preview"]
  node_insertion["Text insertion"]
end

subgraph group_catalog["Prompt catalog"]
  node_variables["Prompt variables"]
  node_catalogsvc["Prompt catalog"]
  node_aliases["Pinyin aliases"]
  node_storage["Prompt storage"]
  node_json[("User JSON config")]
end

subgraph group_management["Management UI"]
  node_manager["Prompt manager"]
  node_managervm["Manager view model"]
  node_editor["Prompt editor"]
  node_export["Prompt export"]
end

subgraph group_platform["Windows integration"]
  node_caret["Caret positioning"]
  node_tray["Tray controls<br/>[TrayIconService.cs]"]
  node_filter["Application filter"]
  node_startup["Startup service<br/>[StartupService.cs]"]
  node_native["Win32 interop<br/>[NativeMethods.cs]"]
end

subgraph group_settings["Settings and updates"]
  node_settingsvm["Settings view model"]
  node_settingssvc["Settings service"]
  node_settingsfile[("Settings JSON")]
  node_updates["Update service<br/>[UpdateService.cs]"]
end

node_user(("User"))
node_target["Target input app"]
node_windows(("Windows services"))
node_files["Import/export files"]

node_user -->|"types into"| node_target
node_app -->|"starts"| node_controller
node_controller -->|"starts and handles"| node_hook
node_hook -->|"dispatches keys"| node_controller
node_controller -->|"updates input"| node_buffer
node_controller -->|"requests matches"| node_match
node_match -->|"reads prompts"| node_catalogsvc
node_match -->|"provides candidates"| node_suggestions
node_controller -->|"shows choices"| node_suggestions
node_controller -->|"requests position"| node_caret
node_caret -->|"queries caret"| node_native
node_controller -->|"shows preview"| node_ghost
node_controller -->|"resolves content"| node_variables
node_controller -->|"requests replacement"| node_insertion
node_insertion -->|"injects text"| node_target
node_insertion -->|"uses clipboard and input APIs"| node_native
node_controller -->|"controls lifecycle"| node_tray
node_tray -->|"toggles filtering"| node_filter
node_tray -->|"controls startup"| node_startup
node_controller -->|"checks target app"| node_filter
node_manager -->|"invokes management"| node_managervm
node_manager -->|"opens editor"| node_editor
node_manager -->|"opens export"| node_export
node_managervm -->|"manages prompts"| node_catalogsvc
node_catalogsvc -->|"refreshes aliases"| node_aliases
node_catalogsvc -->|"loads and persists"| node_storage
node_storage -->|"reads and writes"| node_json
node_manager -->|"imports and exports"| node_storage
node_storage -->|"reads and writes"| node_files
node_controller -->|"loads settings"| node_settingssvc
node_settingsvm -->|"updates settings"| node_settingssvc
node_settingssvc -->|"reads and writes"| node_settingsfile
node_controller -->|"checks updates"| node_updates
node_hook -->|"installs global hook"| node_windows
node_native -->|"calls Win32 APIs"| node_windows

click node_app "https://github.com/zevxn/zcue/blob/master/App.xaml.cs"
click node_controller "https://github.com/zevxn/zcue/blob/master/Services/AppController.cs"
click node_hook "https://github.com/zevxn/zcue/blob/master/Services/KeyboardHookService.cs"
click node_buffer "https://github.com/zevxn/zcue/blob/master/Services/InputBufferService.cs"
click node_match "https://github.com/zevxn/zcue/blob/master/Services/PromptMatchService.cs"
click node_suggestions "https://github.com/zevxn/zcue/blob/master/Views/SuggestionWindow.xaml.cs"
click node_ghost "https://github.com/zevxn/zcue/blob/master/Views/GhostPreviewWindow.xaml.cs"
click node_caret "https://github.com/zevxn/zcue/blob/master/Services/CaretPositionService.cs"
click node_insertion "https://github.com/zevxn/zcue/blob/master/Services/TextInsertionService.cs"
click node_variables "https://github.com/zevxn/zcue/blob/master/Services/PromptVariableService.cs"
click node_catalogsvc "https://github.com/zevxn/zcue/blob/master/Services/PromptCatalogService.cs"
click node_aliases "https://github.com/zevxn/zcue/blob/master/Services/PinyinAliasService.cs"
click node_storage "https://github.com/zevxn/zcue/blob/master/Services/PromptStorageService.cs"
click node_manager "https://github.com/zevxn/zcue/blob/master/Views/PromptManagerWindow.xaml.cs"
click node_managervm "https://github.com/zevxn/zcue/blob/master/ViewModels/PromptManagerViewModel.cs"
click node_editor "https://github.com/zevxn/zcue/blob/master/Views/PromptEditorWindow.xaml.cs"
click node_export "https://github.com/zevxn/zcue/blob/master/Views/PromptExportWindow.xaml.cs"
click node_settingsvm "https://github.com/zevxn/zcue/blob/master/ViewModels/SettingsViewModel.cs"
click node_settingssvc "https://github.com/zevxn/zcue/blob/master/Services/AppSettingsService.cs"
click node_tray "https://github.com/zevxn/zcue/blob/master/Infrastructure/TrayIconService.cs"
click node_filter "https://github.com/zevxn/zcue/blob/master/Services/ApplicationFilterService.cs"
click node_startup "https://github.com/zevxn/zcue/blob/master/Services/StartupService.cs"
click node_native "https://github.com/zevxn/zcue/blob/master/Infrastructure/NativeMethods.cs"
click node_updates "https://github.com/zevxn/zcue/blob/master/Services/UpdateService.cs"

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_app,node_controller,node_hook,node_buffer,node_match,node_suggestions,node_ghost,node_insertion,node_user toneBlue
class node_variables,node_catalogsvc,node_aliases,node_storage,node_json toneAmber
class node_manager,node_managervm,node_editor,node_export toneMint
class node_caret,node_tray,node_filter,node_startup,node_native toneRose
class node_settingsvm,node_settingssvc,node_settingsfile,node_updates,node_target,node_windows,node_files toneIndigo
```

## Components

### Completion runtime

- [WPF application](https://github.com/zevxn/zcue/blob/master/App.xaml.cs): `App.xaml.cs`
- [App controller](https://github.com/zevxn/zcue/blob/master/Services/AppController.cs): `Services/AppController.cs`
- [Keyboard hook](https://github.com/zevxn/zcue/blob/master/Services/KeyboardHookService.cs): `Services/KeyboardHookService.cs`
- [Input buffer](https://github.com/zevxn/zcue/blob/master/Services/InputBufferService.cs): `Services/InputBufferService.cs`
- [Prompt matching](https://github.com/zevxn/zcue/blob/master/Services/PromptMatchService.cs): `Services/PromptMatchService.cs`
- [Suggestion window](https://github.com/zevxn/zcue/blob/master/Views/SuggestionWindow.xaml.cs): `Views/SuggestionWindow.xaml.cs`
- [Ghost preview](https://github.com/zevxn/zcue/blob/master/Views/GhostPreviewWindow.xaml.cs): `Views/GhostPreviewWindow.xaml.cs`
- [Text insertion](https://github.com/zevxn/zcue/blob/master/Services/TextInsertionService.cs): `Services/TextInsertionService.cs`

### Prompt catalog

- [Prompt variables](https://github.com/zevxn/zcue/blob/master/Services/PromptVariableService.cs): `Services/PromptVariableService.cs`
- [Prompt catalog](https://github.com/zevxn/zcue/blob/master/Services/PromptCatalogService.cs): `Services/PromptCatalogService.cs`
- [Pinyin aliases](https://github.com/zevxn/zcue/blob/master/Services/PinyinAliasService.cs): `Services/PinyinAliasService.cs`
- [Prompt storage](https://github.com/zevxn/zcue/blob/master/Services/PromptStorageService.cs): `Services/PromptStorageService.cs`
- **User JSON config**

### Management UI

- [Prompt manager](https://github.com/zevxn/zcue/blob/master/Views/PromptManagerWindow.xaml.cs): `Views/PromptManagerWindow.xaml.cs`
- [Manager view model](https://github.com/zevxn/zcue/blob/master/ViewModels/PromptManagerViewModel.cs): `ViewModels/PromptManagerViewModel.cs`
- [Prompt editor](https://github.com/zevxn/zcue/blob/master/Views/PromptEditorWindow.xaml.cs): `Views/PromptEditorWindow.xaml.cs`
- [Prompt export](https://github.com/zevxn/zcue/blob/master/Views/PromptExportWindow.xaml.cs): `Views/PromptExportWindow.xaml.cs`

### Windows integration

- [Caret positioning](https://github.com/zevxn/zcue/blob/master/Services/CaretPositionService.cs): `Services/CaretPositionService.cs`
- [Tray controls](https://github.com/zevxn/zcue/blob/master/Infrastructure/TrayIconService.cs): `Infrastructure/TrayIconService.cs`
- [Application filter](https://github.com/zevxn/zcue/blob/master/Services/ApplicationFilterService.cs): `Services/ApplicationFilterService.cs`
- [Startup service](https://github.com/zevxn/zcue/blob/master/Services/StartupService.cs): `Services/StartupService.cs`
- [Win32 interop](https://github.com/zevxn/zcue/blob/master/Infrastructure/NativeMethods.cs): `Infrastructure/NativeMethods.cs`

### Settings and updates

- [Settings view model](https://github.com/zevxn/zcue/blob/master/ViewModels/SettingsViewModel.cs): `ViewModels/SettingsViewModel.cs`
- [Settings service](https://github.com/zevxn/zcue/blob/master/Services/AppSettingsService.cs): `Services/AppSettingsService.cs`
- **Settings JSON**
- [Update service](https://github.com/zevxn/zcue/blob/master/Services/UpdateService.cs): `Services/UpdateService.cs`

### Other components

- **User**
- **Target input app**
- **Windows services**
- **Import/export files**

## Connections

- User → Target input app: types into
- WPF application → App controller: starts
- App controller → Keyboard hook: starts and handles
- Keyboard hook → App controller: dispatches keys
- App controller → Input buffer: updates input
- App controller → Prompt matching: requests matches
- Prompt matching → Prompt catalog: reads prompts
- Prompt matching → Suggestion window: provides candidates
- App controller → Suggestion window: shows choices
- App controller → Caret positioning: requests position
- Caret positioning → Win32 interop: queries caret
- App controller → Ghost preview: shows preview
- App controller → Prompt variables: resolves content
- App controller → Text insertion: requests replacement
- Text insertion → Target input app: injects text
- Text insertion → Win32 interop: uses clipboard and input APIs
- App controller → Tray controls: controls lifecycle
- Tray controls → Application filter: toggles filtering
- Tray controls → Startup service: controls startup
- App controller → Application filter: checks target app
- Prompt manager → Manager view model: invokes management
- Prompt manager → Prompt editor: opens editor
- Prompt manager → Prompt export: opens export
- Manager view model → Prompt catalog: manages prompts
- Prompt catalog → Pinyin aliases: refreshes aliases
- Prompt catalog → Prompt storage: loads and persists
- Prompt storage → User JSON config: reads and writes
- Prompt manager → Prompt storage: imports and exports
- Prompt storage → Import/export files: reads and writes
- App controller → Settings service: loads settings
- Settings view model → Settings service: updates settings
- Settings service → Settings JSON: reads and writes
- App controller → Update service: checks updates
- Keyboard hook → Windows services: installs global hook
- Win32 interop → Windows services: calls Win32 APIs