# anoop-kumar-31/ghost-ai architecture

> Architecture diagram of the GitHub repository anoop-kumar-31/ghost-ai, 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/anoop-kumar-31/ghost-ai
- Repository: https://github.com/anoop-kumar-31/ghost-ai

## Overview

Ghost AI is a floating desktop chat workspace: users open or create conversations, configure a provider, submit prompts, and receive streamed responses; they can also transcribe microphone or system audio into the composer for review. The main window coordinates chat/history views and persists workspace state. Separate branches cover provider configuration and credentials, voice transcription, and native window behavior. The graph follows the supplied excerpts and SOURCE INDEX; some documented capabilities, including attachments and shortcuts, are not separately mapped because their implementation details were not shown.

Main entry points: [`ghost_ai/main_window.py`](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/main_window.py) (Main window), [`ghost_ai/chat_view.py`](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/chat_view.py) (Chat composer), [`ghost_ai/ai_service.py`](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/ai_service.py) (AI request worker), [`ghost_ai/config.py`](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/config.py) (Provider configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Desktop workspace"]
  node_window["Main window<br/>[main_window.py]"]
  node_header["Header and tabs<br/>[header_bar.py]"]
  node_controls["Window controls<br/>[controls.py]"]
  node_icons["Icon rendering<br/>[icon_manager.py]"]
end

subgraph group_conversation["Conversation experience"]
  node_history["Chat history<br/>[history_view.py]"]
  node_chat["Chat composer<br/>[chat_view.py]"]
  node_markdown["Markdown rendering"]
  node_voice["Voice transcription<br/>[voice_worker.py]"]
end

subgraph group_provider["AI and configuration"]
  node_settings["Settings dialog<br/>[settings_dialog.py]"]
  node_config["Provider configuration<br/>[config.py]"]
  node_ai["AI request worker<br/>[ai_service.py]"]
end

subgraph group_privacy["Local privacy"]
  node_persistence["Workspace persistence<br/>[persistence.py]"]
  node_history_file[("Local chat data")]
  node_secure_store["Credential management<br/>[secure_store.py]"]
end

subgraph group_platform["Platform integration"]
  node_platform_dispatch["Platform dispatch<br/>[platform_utils.py]"]
  node_windows["Windows integration<br/>[win32_utils.py]"]
  node_macos["macOS integration<br/>[macos_utils.py]"]
end

node_user(("Desktop user"))
node_launcher["Application launcher<br/>[main.py]"]
node_provider_service{{"AI provider APIs"}}
node_keyring[("OS credential store")]
node_native_os{{"Native window APIs"}}
node_audio_devices{{"Audio input devices"}}

node_user -->|"launches"| node_launcher
node_launcher -->|"starts"| node_window
node_user -->|"uses"| node_window
node_window -->|"coordinates"| node_header
node_window -->|"updates"| node_history
node_window -->|"coordinates"| node_chat
node_window -->|"loads and saves"| node_persistence
node_window -->|"uses"| node_controls
node_window -->|"uses"| node_platform_dispatch
node_chat -->|"starts requests"| node_ai
node_ai -->|"sends requests"| node_provider_service
node_ai -->|"uses provider settings"| node_config
node_chat -->|"loads configuration"| node_config
node_chat -->|"starts transcription"| node_voice
node_voice -->|"captures audio"| node_audio_devices
node_chat -->|"renders responses"| node_markdown
node_chat -->|"uses icons"| node_icons
node_history -->|"uses icons"| node_icons
node_header -->|"uses icons"| node_icons
node_window -->|"opens"| node_settings
node_settings -->|"loads and saves"| node_config
node_settings -->|"tests connection"| node_ai
node_config -->|"loads API keys"| node_secure_store
node_persistence -->|"gets encryption key"| node_secure_store
node_secure_store -->|"stores credentials"| node_keyring
node_persistence -->|"reads and writes"| node_history_file
node_platform_dispatch -->|"dispatches on Windows"| node_windows
node_platform_dispatch -->|"dispatches on macOS"| node_macos
node_windows -.->|"controls windows"| node_native_os
node_macos -.->|"controls windows"| node_native_os

click node_launcher "https://github.com/anoop-kumar-31/ghost-ai/blob/main/main.py"
click node_window "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/main_window.py"
click node_header "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/header_bar.py"
click node_controls "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/controls.py"
click node_history "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/history_view.py"
click node_chat "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/chat_view.py"
click node_markdown "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/markdown_renderer.py"
click node_icons "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/icon_manager.py"
click node_voice "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/voice_worker.py"
click node_settings "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/settings_dialog.py"
click node_config "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/config.py"
click node_ai "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/ai_service.py"
click node_persistence "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/persistence.py"
click node_secure_store "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/secure_store.py"
click node_platform_dispatch "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/platform_utils.py"
click node_windows "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/win32_utils.py"
click node_macos "https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/macos_utils.py"

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_window,node_header,node_controls,node_icons,node_user toneBlue
class node_history,node_chat,node_markdown,node_voice,node_keyring toneAmber
class node_settings,node_config,node_ai,node_provider_service,node_native_os toneMint
class node_persistence,node_history_file,node_secure_store toneRose
class node_platform_dispatch,node_windows,node_macos,node_audio_devices toneIndigo
class node_launcher toneTeal
```

## Components

### Desktop workspace

- [Main window](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/main_window.py): `ghost_ai/main_window.py`
- [Header and tabs](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/header_bar.py): `ghost_ai/header_bar.py`
- [Window controls](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/controls.py): `ghost_ai/controls.py`
- [Icon rendering](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/icon_manager.py): `ghost_ai/icon_manager.py`

### Conversation experience

- [Chat history](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/history_view.py): `ghost_ai/history_view.py`
- [Chat composer](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/chat_view.py): `ghost_ai/chat_view.py`
- [Markdown rendering](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/markdown_renderer.py): `ghost_ai/markdown_renderer.py`
- [Voice transcription](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/voice_worker.py): `ghost_ai/voice_worker.py`

### AI and configuration

- [Settings dialog](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/settings_dialog.py): `ghost_ai/settings_dialog.py`
- [Provider configuration](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/config.py): `ghost_ai/config.py`
- [AI request worker](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/ai_service.py): `ghost_ai/ai_service.py`

### Local privacy

- [Workspace persistence](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/persistence.py): `ghost_ai/persistence.py`
- **Local chat data**
- [Credential management](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/secure_store.py): `ghost_ai/secure_store.py`

### Platform integration

- [Platform dispatch](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/platform_utils.py): `ghost_ai/platform_utils.py`
- [Windows integration](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/win32_utils.py): `ghost_ai/win32_utils.py`
- [macOS integration](https://github.com/anoop-kumar-31/ghost-ai/blob/main/ghost_ai/macos_utils.py): `ghost_ai/macos_utils.py`

### Other components

- **Desktop user**
- [Application launcher](https://github.com/anoop-kumar-31/ghost-ai/blob/main/main.py): `main.py`
- **AI provider APIs**
- **OS credential store**
- **Native window APIs**
- **Audio input devices**

## Connections

- Desktop user → Application launcher: launches (evidence: `main.py`)
- Application launcher → Main window: starts (evidence: `main.py`)
- Desktop user → Main window: uses (evidence: `README.md`)
- Main window → Header and tabs: coordinates (evidence: `ghost_ai/main_window.py`)
- Main window → Chat history: updates (evidence: `ghost_ai/main_window.py`)
- Main window → Chat composer: coordinates (evidence: `ghost_ai/main_window.py`)
- Main window → Workspace persistence: loads and saves (evidence: `ghost_ai/main_window.py`)
- Main window → Window controls: uses (evidence: `ghost_ai/main_window.py`)
- Main window → Platform dispatch: uses (evidence: `ghost_ai/main_window.py`)
- Chat composer → AI request worker: starts requests (evidence: `ghost_ai/chat_view.py`)
- AI request worker → AI provider APIs: sends requests (evidence: `ghost_ai/ai_service.py`)
- AI request worker → Provider configuration: uses provider settings (evidence: `ghost_ai/ai_service.py`)
- Chat composer → Provider configuration: loads configuration (evidence: `ghost_ai/chat_view.py`)
- Chat composer → Voice transcription: starts transcription (evidence: `ghost_ai/chat_view.py`)
- Voice transcription → Audio input devices: captures audio (evidence: `README.md`)
- Chat composer → Markdown rendering: renders responses (evidence: `ghost_ai/chat_view.py`)
- Chat composer → Icon rendering: uses icons (evidence: `ghost_ai/chat_view.py`)
- Chat history → Icon rendering: uses icons (evidence: `ghost_ai/history_view.py`)
- Header and tabs → Icon rendering: uses icons (evidence: `ghost_ai/header_bar.py`)
- Main window → Settings dialog: opens (evidence: `ghost_ai/main_window.py`)
- Settings dialog → Provider configuration: loads and saves (evidence: `ghost_ai/settings_dialog.py`)
- Settings dialog → AI request worker: tests connection (evidence: `ghost_ai/settings_dialog.py`)
- Provider configuration → Credential management: loads API keys (evidence: `ghost_ai/config.py`)
- Workspace persistence → Credential management: gets encryption key (evidence: `ghost_ai/persistence.py`)
- Credential management → OS credential store: stores credentials (evidence: `ghost_ai/secure_store.py`)
- Workspace persistence → Local chat data: reads and writes (evidence: `README.md`)
- Platform dispatch → Windows integration: dispatches on Windows (evidence: `ghost_ai/platform_utils.py`)
- Platform dispatch → macOS integration: dispatches on macOS (evidence: `ghost_ai/platform_utils.py`)
- Windows integration → Native window APIs: controls windows
- macOS integration → Native window APIs: controls windows
