# heeetz/heetkit-bot architecture

> Architecture diagram of the GitHub repository heeetz/heetkit-bot, 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/heeetz/heetkit-bot
- Repository: https://github.com/heeetz/heetkit-bot

## Overview

HeetKit is a desktop Twitch chat bot with a local React control panel. The main workflow is chat arriving from Twitch, dispatch through command and permission checks, then a reply or AI response; the panel manages configuration and displays live status/logs. The graph preserves documented command, filter, personality, memory, profile, and utility capabilities. Some runtime wiring is documented or named in the source index rather than shown in excerpts, so uncertain links are omitted or marked unverified.

Main entry points: [`app/webview_host.py`](https://github.com/heeetz/heetkit-bot/blob/main/app/webview_host.py) (Desktop host API), [`app/commands/registry.py`](https://github.com/heeetz/heetkit-bot/blob/main/app/commands/registry.py) (Command dispatch), [`app/services/facade.py`](https://github.com/heeetz/heetkit-bot/blob/main/app/services/facade.py) (Service facade), [`app/services/gemini_ai_service.py`](https://github.com/heeetz/heetkit-bot/blob/main/app/services/gemini_ai_service.py) (Gemini responder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop control"]
  node_panel["Control panel<br/>[App.tsx]"]
  node_bridge["Frontend bridge<br/>[bridge.ts]"]
  node_host["Desktop host API<br/>[webview_host.py]"]
  node_logs[("Live log buffer<br/>[logging.py]")]
end

subgraph group_chat["Twitch chat"]
  node_twitch["Twitch chat service<br/>[client.py]"]
  node_dispatcher["Command dispatch<br/>[registry.py]"]
  node_permissions["Role permissions<br/>[permissions.py]"]
  node_builtin["Built-in commands"]
  node_custom["Custom commands<br/>[custom_commands.py]"]
  node_cooldowns["Cooldown tracking<br/>[cooldown.py]"]
  node_triggers["Message triggers"]
end

subgraph group_ai["AI and filters"]
  node_ai_command["AI chat command<br/>[ai.py]"]
  node_gemini["Gemini responder"]
  node_personalities["AI personalities<br/>[personalities.py]"]
  node_filters["Chat and AI filters<br/>[filter_manager.py]"]
  node_memory[("Conversation memory<br/>[memory.py]")]
end

subgraph group_state["Settings and state"]
  node_database[("Local data store<br/>[database.py]")]
  node_repository["Data repository<br/>[repository.py]"]
  node_runtime[("Runtime controls<br/>[runtime_state.py]")]
  node_app_settings[("Profile settings<br/>[app_settings.py]")]
  node_command_settings["Command settings"]
  node_ai_config["AI model settings<br/>[ai_models.py]"]
  node_filter_config["Filter settings<br/>[filter_settings.py]"]
  node_profile[("Local profile files<br/>[runtime_paths.py]")]
end

subgraph group_services["Application services"]
  node_weather["Weather utility<br/>[weather.py]"]
  node_twitch_services["Twitch utilities<br/>[twitch.py]"]
  node_facade["Service facade<br/>[facade.py]"]
end

node_user(("Desktop user"))
node_twitch_user(("Twitch chat users"))
node_twitch_platform["Twitch"]
node_gemini_platform["Gemini API"]

node_user -->|"controls"| node_panel
node_panel -->|"calls API"| node_bridge
node_bridge -.->|"invokes"| node_host
node_host -->|"manages profiles"| node_app_settings
node_host -->|"updates controls"| node_runtime
node_host -->|"reads recent logs"| node_logs
node_twitch_user -->|"sends chat"| node_twitch_platform
node_twitch_platform -->|"delivers events"| node_twitch
node_twitch -->|"dispatches messages"| node_dispatcher
node_dispatcher -->|"checks roles"| node_permissions
node_dispatcher -->|"resolves custom commands"| node_custom
node_dispatcher -->|"reads command state"| node_runtime
node_dispatcher -->|"checks cooldowns"| node_cooldowns
node_dispatcher -->|"checks triggers"| node_triggers
node_dispatcher -.->|"dispatches built-ins"| node_builtin
node_dispatcher -->|"uses services"| node_facade
node_builtin -.->|"includes"| node_ai_command
node_ai_command -.->|"requests AI"| node_facade
node_facade -.->|"provides AI service"| node_gemini
node_gemini -->|"requests completions"| node_gemini_platform
node_gemini -->|"builds instructions"| node_personalities
node_gemini -->|"applies filters"| node_filters
node_facade -->|"provides memory"| node_memory
node_facade -->|"uses persistence"| node_repository
node_repository -->|"reads and writes"| node_database
node_facade -->|"provides Twitch utilities"| node_twitch_services
node_builtin -.->|"offers weather"| node_weather
node_host -->|"manages commands"| node_command_settings
node_host -->|"manages filters"| node_filter_config
node_host -->|"manages AI settings"| node_ai_config
node_runtime -.->|"persists profile state"| node_profile
node_host -->|"exposes log feed"| node_logs

click node_panel "https://github.com/heeetz/heetkit-bot/blob/main/frontend/src/App.tsx"
click node_bridge "https://github.com/heeetz/heetkit-bot/blob/main/frontend/src/bridge.ts"
click node_host "https://github.com/heeetz/heetkit-bot/blob/main/app/webview_host.py"
click node_logs "https://github.com/heeetz/heetkit-bot/blob/main/app/utils/logging.py"
click node_twitch "https://github.com/heeetz/heetkit-bot/blob/main/app/twitch/client.py"
click node_dispatcher "https://github.com/heeetz/heetkit-bot/blob/main/app/commands/registry.py"
click node_permissions "https://github.com/heeetz/heetkit-bot/blob/main/app/twitch/permissions.py"
click node_builtin "https://github.com/heeetz/heetkit-bot/tree/main/app/commands"
click node_custom "https://github.com/heeetz/heetkit-bot/blob/main/app/custom_commands.py"
click node_cooldowns "https://github.com/heeetz/heetkit-bot/blob/main/app/utils/cooldown.py"
click node_triggers "https://github.com/heeetz/heetkit-bot/blob/main/app/message_triggers.py"
click node_ai_command "https://github.com/heeetz/heetkit-bot/blob/main/app/commands/ai.py"
click node_gemini "https://github.com/heeetz/heetkit-bot/blob/main/app/services/gemini_ai_service.py"
click node_personalities "https://github.com/heeetz/heetkit-bot/blob/main/app/config/personalities.py"
click node_filters "https://github.com/heeetz/heetkit-bot/blob/main/app/services/filter_manager.py"
click node_memory "https://github.com/heeetz/heetkit-bot/blob/main/app/services/memory.py"
click node_weather "https://github.com/heeetz/heetkit-bot/blob/main/app/services/weather.py"
click node_twitch_services "https://github.com/heeetz/heetkit-bot/blob/main/app/services/twitch.py"
click node_facade "https://github.com/heeetz/heetkit-bot/blob/main/app/services/facade.py"
click node_database "https://github.com/heeetz/heetkit-bot/blob/main/app/database/database.py"
click node_repository "https://github.com/heeetz/heetkit-bot/blob/main/app/database/repository.py"
click node_runtime "https://github.com/heeetz/heetkit-bot/blob/main/app/runtime_state.py"
click node_app_settings "https://github.com/heeetz/heetkit-bot/blob/main/app/app_settings.py"
click node_command_settings "https://github.com/heeetz/heetkit-bot/blob/main/app/command_settings.py"
click node_ai_config "https://github.com/heeetz/heetkit-bot/blob/main/app/config/ai_models.py"
click node_filter_config "https://github.com/heeetz/heetkit-bot/blob/main/app/filter_settings.py"
click node_profile "https://github.com/heeetz/heetkit-bot/blob/main/app/runtime_paths.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_panel,node_bridge,node_host,node_logs,node_user,node_twitch_user toneBlue
class node_twitch,node_dispatcher,node_permissions,node_builtin,node_custom,node_cooldowns,node_triggers toneAmber
class node_ai_command,node_gemini,node_personalities,node_filters,node_memory,node_gemini_platform toneMint
class node_database,node_repository,node_runtime,node_app_settings,node_command_settings,node_ai_config,node_filter_config,node_profile toneRose
class node_weather,node_twitch_services,node_facade,node_twitch_platform toneIndigo
```

## Components

### Desktop control

- [Control panel](https://github.com/heeetz/heetkit-bot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Frontend bridge](https://github.com/heeetz/heetkit-bot/blob/main/frontend/src/bridge.ts): `frontend/src/bridge.ts`
- [Desktop host API](https://github.com/heeetz/heetkit-bot/blob/main/app/webview_host.py): `app/webview_host.py`
- [Live log buffer](https://github.com/heeetz/heetkit-bot/blob/main/app/utils/logging.py): `app/utils/logging.py`

### Twitch chat

- [Twitch chat service](https://github.com/heeetz/heetkit-bot/blob/main/app/twitch/client.py): `app/twitch/client.py`
- [Command dispatch](https://github.com/heeetz/heetkit-bot/blob/main/app/commands/registry.py): `app/commands/registry.py`
- [Role permissions](https://github.com/heeetz/heetkit-bot/blob/main/app/twitch/permissions.py): `app/twitch/permissions.py`
- [Built-in commands](https://github.com/heeetz/heetkit-bot/tree/main/app/commands): `app/commands`
- [Custom commands](https://github.com/heeetz/heetkit-bot/blob/main/app/custom_commands.py): `app/custom_commands.py`
- [Cooldown tracking](https://github.com/heeetz/heetkit-bot/blob/main/app/utils/cooldown.py): `app/utils/cooldown.py`
- [Message triggers](https://github.com/heeetz/heetkit-bot/blob/main/app/message_triggers.py): `app/message_triggers.py`

### AI and filters

- [AI chat command](https://github.com/heeetz/heetkit-bot/blob/main/app/commands/ai.py): `app/commands/ai.py`
- [Gemini responder](https://github.com/heeetz/heetkit-bot/blob/main/app/services/gemini_ai_service.py): `app/services/gemini_ai_service.py`
- [AI personalities](https://github.com/heeetz/heetkit-bot/blob/main/app/config/personalities.py): `app/config/personalities.py`
- [Chat and AI filters](https://github.com/heeetz/heetkit-bot/blob/main/app/services/filter_manager.py): `app/services/filter_manager.py`
- [Conversation memory](https://github.com/heeetz/heetkit-bot/blob/main/app/services/memory.py): `app/services/memory.py`

### Settings and state

- [Local data store](https://github.com/heeetz/heetkit-bot/blob/main/app/database/database.py): `app/database/database.py`
- [Data repository](https://github.com/heeetz/heetkit-bot/blob/main/app/database/repository.py): `app/database/repository.py`
- [Runtime controls](https://github.com/heeetz/heetkit-bot/blob/main/app/runtime_state.py): `app/runtime_state.py`
- [Profile settings](https://github.com/heeetz/heetkit-bot/blob/main/app/app_settings.py): `app/app_settings.py`
- [Command settings](https://github.com/heeetz/heetkit-bot/blob/main/app/command_settings.py): `app/command_settings.py`
- [AI model settings](https://github.com/heeetz/heetkit-bot/blob/main/app/config/ai_models.py): `app/config/ai_models.py`
- [Filter settings](https://github.com/heeetz/heetkit-bot/blob/main/app/filter_settings.py): `app/filter_settings.py`
- [Local profile files](https://github.com/heeetz/heetkit-bot/blob/main/app/runtime_paths.py): `app/runtime_paths.py`

### Application services

- [Weather utility](https://github.com/heeetz/heetkit-bot/blob/main/app/services/weather.py): `app/services/weather.py`
- [Twitch utilities](https://github.com/heeetz/heetkit-bot/blob/main/app/services/twitch.py): `app/services/twitch.py`
- [Service facade](https://github.com/heeetz/heetkit-bot/blob/main/app/services/facade.py): `app/services/facade.py`

### Other components

- **Desktop user**
- **Twitch chat users**
- **Twitch**
- **Gemini API**

## Connections

- Desktop user → Control panel: controls (evidence: `README.md`)
- Control panel → Frontend bridge: calls API (evidence: `frontend/src/App.tsx`)
- Frontend bridge → Desktop host API: invokes
- Desktop host API → Profile settings: manages profiles (evidence: `app/webview_host.py`)
- Desktop host API → Runtime controls: updates controls (evidence: `app/webview_host.py`)
- Desktop host API → Live log buffer: reads recent logs (evidence: `app/webview_host.py`)
- Twitch chat users → Twitch: sends chat (evidence: `README.md`)
- Twitch → Twitch chat service: delivers events (evidence: `app/twitch/client.py`)
- Twitch chat service → Command dispatch: dispatches messages (evidence: `app/twitch/client.py`)
- Command dispatch → Role permissions: checks roles (evidence: `app/commands/registry.py`)
- Command dispatch → Custom commands: resolves custom commands (evidence: `app/commands/registry.py`)
- Command dispatch → Runtime controls: reads command state (evidence: `app/commands/registry.py`)
- Command dispatch → Cooldown tracking: checks cooldowns (evidence: `app/commands/registry.py`)
- Command dispatch → Message triggers: checks triggers (evidence: `app/commands/registry.py`)
- Command dispatch → Built-in commands: dispatches built-ins (evidence: `app/commands/social.py`)
- Command dispatch → Service facade: uses services (evidence: `app/commands/registry.py`)
- Built-in commands → AI chat command: includes
- AI chat command → Service facade: requests AI
- Service facade → Gemini responder: provides AI service
- Gemini responder → Gemini API: requests completions (evidence: `app/services/gemini_ai_service.py`)
- Gemini responder → AI personalities: builds instructions (evidence: `app/services/gemini_ai_service.py`)
- Gemini responder → Chat and AI filters: applies filters (evidence: `app/services/gemini_ai_service.py`)
- Service facade → Conversation memory: provides memory (evidence: `app/services/facade.py`)
- Service facade → Data repository: uses persistence (evidence: `app/services/facade.py`)
- Data repository → Local data store: reads and writes (evidence: `app/database/repository.py`)
- Service facade → Twitch utilities: provides Twitch utilities (evidence: `app/services/facade.py`)
- Built-in commands → Weather utility: offers weather
- Desktop host API → Command settings: manages commands (evidence: `app/webview_host.py`)
- Desktop host API → Filter settings: manages filters (evidence: `app/webview_host.py`)
- Desktop host API → AI model settings: manages AI settings (evidence: `app/webview_host.py`)
- Runtime controls → Local profile files: persists profile state
- Desktop host API → Live log buffer: exposes log feed (evidence: `app/webview_host.py`)
