# khaled-dragon/waey architecture

> Architecture diagram of the GitHub repository khaled-dragon/waey, 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/khaled-dragon/waey
- Repository: https://github.com/khaled-dragon/waey

## Overview

Waey is a screen-aware desktop AI assistant. A user opens its overlay, captures a screen region or uses fresh readable desktop context, then submits a prompt; the app streams a model response and can save the conversation locally. Separate workflows support stepwise Guide Mode, approval-gated desktop actions, and optional workspace-aware developer help. The graph combines sampled call sites with README-documented capabilities; several feature implementations are listed in the tree but were not sampled, so their specific internal calls are not asserted.

Main entry points: [`src/App.tsx`](https://github.com/khaled-dragon/waey/blob/main/src/App.tsx) (Overlay UI), [`src-tauri/src/llm.rs`](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/llm.rs) (Model streaming), [`src-tauri/src/dev_context.rs`](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/dev_context.rs) (Developer context), [`src-tauri/src/storage.rs`](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/storage.rs) (SQLite storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Desktop interaction"]
  node_overlay["Overlay UI<br/>[App.tsx]"]
  node_composer["Chat composer<br/>[ChatComposer.tsx]"]
  node_responses["Response panel<br/>[ResponsePanel.tsx]"]
end

subgraph group_assistant["Assistant workflows"]
  node_chat_hook["Chat workflow<br/>[useLlmChat.ts]"]
  node_llm["Model streaming<br/>[llm.rs]"]
  node_guide["Guide session<br/>[useGuideSession.ts]"]
  node_guide_backend["Guide service<br/>[guide.rs]"]
  node_action["Action mode<br/>[action.rs]"]
end

subgraph group_context["Screen and workspace context"]
  node_capture["Screen capture<br/>[capture.rs]"]
  node_capture_ui["Capture events"]
  node_screen_context["UI context<br/>[ui_context.rs]"]
  node_context_cache["Context cache<br/>[context_cache.rs]"]
  node_uia["UI automation<br/>[windows_uia.rs]"]
  node_native_uia["Native UIA"]
  node_developer_context["Developer context<br/>[dev_context.rs]"]
  node_workspace["Workspace access<br/>[workspace.rs]"]
  node_spreadsheet["Spreadsheet support<br/>[spreadsheet.rs]"]
end

subgraph group_platform["Desktop services"]
  node_updates["App updates<br/>[useAppUpdates.ts]"]
end

subgraph group_configuration["Configuration and history"]
  node_provider_service["Provider service<br/>[providers.rs]"]
  node_settings["App settings<br/>[settings.rs]"]
  node_personas["Personas<br/>[personas.rs]"]
  node_history["Conversation history<br/>[history.rs]"]
  node_storage[("SQLite storage<br/>[storage.rs]")]
end

node_user(("User"))
node_model_provider{{"Model provider"}}

node_user -->|"opens and prompts"| node_overlay
node_overlay -->|"presents"| node_composer
node_overlay -->|"requests capture"| node_capture
node_capture -->|"emits capture events"| node_capture_ui
node_capture_ui -->|"provides capture state"| node_overlay
node_overlay -->|"requests fresh context"| node_screen_context
node_screen_context -->|"captures or reuses"| node_context_cache
node_context_cache -.->|"collects UI structure"| node_uia
node_uia -.->|"uses native collection"| node_native_uia
node_composer -.->|"submits prompt"| node_chat_hook
node_chat_hook -->|"sends prompt"| node_llm
node_llm -->|"streams completion"| node_model_provider
node_provider_service -.->|"configures endpoint"| node_model_provider
node_llm -->|"uses screen facts"| node_screen_context
node_llm -->|"uses developer access settings"| node_developer_context
node_chat_hook -->|"streams updates"| node_responses
node_responses -->|"handles guide responses"| node_guide
node_guide -.->|"requests guide steps"| node_guide_backend
node_guide -->|"shows guide UI"| node_overlay
node_overlay -->|"applies approved action"| node_action
node_action -->|"verifies and acts"| node_native_uia
node_overlay -->|"builds context"| node_developer_context
node_developer_context -->|"checks workspace access"| node_workspace
node_developer_context -->|"handles spreadsheet context"| node_spreadsheet
node_settings -->|"reads and writes settings"| node_storage
node_provider_service -->|"uses persistent storage"| node_storage
node_history -.->|"persists chats"| node_storage
node_personas -.->|"persists personas"| node_storage
node_overlay -.->|"browses saved chats"| node_history
node_overlay -.->|"selects personas"| node_personas
node_overlay -.->|"edits preferences"| node_settings
node_overlay -.->|"checks for updates"| node_updates

click node_overlay "https://github.com/khaled-dragon/waey/blob/main/src/App.tsx"
click node_composer "https://github.com/khaled-dragon/waey/blob/main/src/components/ChatComposer.tsx"
click node_responses "https://github.com/khaled-dragon/waey/blob/main/src/components/ResponsePanel.tsx"
click node_capture "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/capture.rs"
click node_capture_ui "https://github.com/khaled-dragon/waey/blob/main/src/features/capture/useScreenCaptureEvents.ts"
click node_screen_context "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/ui_context.rs"
click node_context_cache "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/screen_intelligence/context_cache.rs"
click node_uia "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/screen_intelligence/windows_uia.rs"
click node_native_uia "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/screen_intelligence/windows_native_uia.rs"
click node_chat_hook "https://github.com/khaled-dragon/waey/blob/main/src/features/chat/useLlmChat.ts"
click node_llm "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/llm.rs"
click node_provider_service "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/providers.rs"
click node_guide "https://github.com/khaled-dragon/waey/blob/main/src/features/guide/useGuideSession.ts"
click node_guide_backend "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/guide.rs"
click node_action "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/screen_intelligence/action.rs"
click node_developer_context "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/dev_context.rs"
click node_workspace "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/workspace.rs"
click node_spreadsheet "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/spreadsheet.rs"
click node_settings "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/settings.rs"
click node_personas "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/personas.rs"
click node_history "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/history.rs"
click node_storage "https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/storage.rs"
click node_updates "https://github.com/khaled-dragon/waey/blob/main/src/features/updates/useAppUpdates.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_overlay,node_composer,node_responses,node_user toneBlue
class node_chat_hook,node_llm,node_guide,node_guide_backend,node_action toneAmber
class node_capture,node_capture_ui,node_screen_context,node_context_cache,node_uia,node_native_uia,node_developer_context,node_workspace,node_spreadsheet toneMint
class node_updates toneRose
class node_provider_service,node_settings,node_personas,node_history,node_storage,node_model_provider toneIndigo
```

## Components

### Desktop interaction

- [Overlay UI](https://github.com/khaled-dragon/waey/blob/main/src/App.tsx): `src/App.tsx`
- [Chat composer](https://github.com/khaled-dragon/waey/blob/main/src/components/ChatComposer.tsx): `src/components/ChatComposer.tsx`
- [Response panel](https://github.com/khaled-dragon/waey/blob/main/src/components/ResponsePanel.tsx): `src/components/ResponsePanel.tsx`

### Assistant workflows

- [Chat workflow](https://github.com/khaled-dragon/waey/blob/main/src/features/chat/useLlmChat.ts): `src/features/chat/useLlmChat.ts`
- [Model streaming](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/llm.rs): `src-tauri/src/llm.rs`
- [Guide session](https://github.com/khaled-dragon/waey/blob/main/src/features/guide/useGuideSession.ts): `src/features/guide/useGuideSession.ts`
- [Guide service](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/guide.rs): `src-tauri/src/guide.rs`
- [Action mode](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/screen_intelligence/action.rs): `src-tauri/src/screen_intelligence/action.rs`

### Screen and workspace context

- [Screen capture](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/capture.rs): `src-tauri/src/capture.rs`
- [Capture events](https://github.com/khaled-dragon/waey/blob/main/src/features/capture/useScreenCaptureEvents.ts): `src/features/capture/useScreenCaptureEvents.ts`
- [UI context](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/ui_context.rs): `src-tauri/src/ui_context.rs`
- [Context cache](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/screen_intelligence/context_cache.rs): `src-tauri/src/screen_intelligence/context_cache.rs`
- [UI automation](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/screen_intelligence/windows_uia.rs): `src-tauri/src/screen_intelligence/windows_uia.rs`
- [Native UIA](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/screen_intelligence/windows_native_uia.rs): `src-tauri/src/screen_intelligence/windows_native_uia.rs`
- [Developer context](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/dev_context.rs): `src-tauri/src/dev_context.rs`
- [Workspace access](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/workspace.rs): `src-tauri/src/workspace.rs`
- [Spreadsheet support](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/spreadsheet.rs): `src-tauri/src/spreadsheet.rs`

### Desktop services

- [App updates](https://github.com/khaled-dragon/waey/blob/main/src/features/updates/useAppUpdates.ts): `src/features/updates/useAppUpdates.ts`

### Configuration and history

- [Provider service](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/providers.rs): `src-tauri/src/providers.rs`
- [App settings](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/settings.rs): `src-tauri/src/settings.rs`
- [Personas](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/personas.rs): `src-tauri/src/personas.rs`
- [Conversation history](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/history.rs): `src-tauri/src/history.rs`
- [SQLite storage](https://github.com/khaled-dragon/waey/blob/main/src-tauri/src/storage.rs): `src-tauri/src/storage.rs`

### Other components

- **User**
- **Model provider**

## Connections

- User → Overlay UI: opens and prompts
- Overlay UI → Chat composer: presents (evidence: `src/App.tsx`)
- Overlay UI → Screen capture: requests capture (evidence: `src/App.tsx`)
- Screen capture → Capture events: emits capture events
- Capture events → Overlay UI: provides capture state (evidence: `src/features/capture/useScreenCaptureEvents.ts`)
- Overlay UI → UI context: requests fresh context (evidence: `src/App.tsx`)
- UI context → Context cache: captures or reuses
- Context cache → UI automation: collects UI structure
- UI automation → Native UIA: uses native collection
- Chat composer → Chat workflow: submits prompt
- Chat workflow → Model streaming: sends prompt (evidence: `src/features/chat/useLlmChat.ts`)
- Model streaming → Model provider: streams completion (evidence: `src-tauri/src/llm.rs`)
- Provider service → Model provider: configures endpoint
- Model streaming → UI context: uses screen facts (evidence: `src-tauri/src/llm.rs`)
- Model streaming → Developer context: uses developer access settings (evidence: `src-tauri/src/llm.rs`)
- Chat workflow → Response panel: streams updates (evidence: `src/features/chat/useLlmChat.ts`)
- Response panel → Guide session: handles guide responses (evidence: `src/components/ResponsePanel.tsx`)
- Guide session → Guide service: requests guide steps
- Guide session → Overlay UI: shows guide UI (evidence: `src/App.tsx`)
- Overlay UI → Action mode: applies approved action (evidence: `src/App.tsx`)
- Action mode → Native UIA: verifies and acts
- Overlay UI → Developer context: builds context (evidence: `src/App.tsx`)
- Developer context → Workspace access: checks workspace access (evidence: `src-tauri/src/dev_context.rs`)
- Developer context → Spreadsheet support: handles spreadsheet context (evidence: `src-tauri/src/dev_context.rs`)
- App settings → SQLite storage: reads and writes settings (evidence: `src-tauri/src/settings.rs`)
- Provider service → SQLite storage: uses persistent storage (evidence: `src-tauri/src/providers.rs`)
- Conversation history → SQLite storage: persists chats
- Personas → SQLite storage: persists personas
- Overlay UI → Conversation history: browses saved chats
- Overlay UI → Personas: selects personas
- Overlay UI → App settings: edits preferences
- Overlay UI → App updates: checks for updates
