# itzkitb/butterbror2 architecture

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

- Interactive diagram: https://gitdiagram.com/itzkitb/butterbror2
- Repository: https://github.com/itzkitb/butterbror2

## Overview

ButterBror2 is a modular chatbot host whose main workflow is to receive platform chat, pass messages into the bot core, dispatch commands, and return command results. Its documented plugin system loads chat and command modules from `.pag` packages; Twitch is the only substantial platform implementation visible in the supplied source. The graph also retains documented dashboard, localization, persistence, and runtime service-provider capabilities. Some subsystem links are based on README descriptions or source-index references; unsampled implementation details are not asserted.

Main entry points: [`ButterBror.Host/Program.cs`](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Host/Program.cs) (Application host), [`ButterBror.ChatModules.Twitch/Services/TwitchClient.cs`](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Services/TwitchClient.cs) (Twitch client), [`ButterBror.Infrastructure/Services/BotCore.cs`](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/BotCore.cs) (Bot core), [`ButterBror.Infrastructure/Services/PlatformModuleManager.cs`](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/PlatformModuleManager.cs) (Module manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Host and runtime"]
  node_host["Application host<br/>[Program.cs]"]
  node_hosted["Bot lifecycle"]
  node_module_manager["Module manager"]
  node_module_loader["Package loader"]
  node_command_loader["Command loader"]
  node_load_context["Assembly context"]
end

subgraph group_modules["Chat and commands"]
  node_chat_transport["Twitch transport"]
  node_twitch_client["Twitch client<br/>[TwitchClient.cs]"]
  node_twitch_module["Twitch module<br/>[TwitchModule.cs]"]
  node_app_commands["Application commands<br/>[UserInfoCommand.cs]"]
  node_twitch_auth["Twitch authorization"]
end

subgraph group_services["Core services"]
  node_core["Bot core<br/>[BotCore.cs]"]
  node_dispatcher["Command processing"]
  node_registry["Command registry<br/>[CommandRegistry.cs]"]
  node_dynamic_services["Dynamic services"]
  node_localization["Localization"]
  node_locale_registry["Locale registry"]
  node_translation_loader["Translation loader"]
end

subgraph group_data["Data and dashboard"]
  node_redis[("Redis service")]
  node_channel_manager["Twitch channels"]
  node_banphrases["Banphrase repository"]
  node_user_repository["User repository"]
  node_dashboard["Dashboard services"]
  node_dashboard_bridge["Dashboard bridge<br/>[DashboardBridge.cs]"]
end

node_chat_user(("Chat user"))
node_twitch_api{{"Twitch API"}}
node_auth_service{{"Auth API"}}

node_host -->|"hosts"| node_hosted
node_host -->|"registers"| node_core
node_host -->|"registers"| node_dynamic_services
node_host -->|"registers"| node_user_repository
node_host -->|"registers"| node_dashboard_bridge
node_hosted -->|"starts"| node_core
node_core -.->|"initializes"| node_module_manager
node_module_manager -.->|"loads modules"| node_module_loader
node_module_manager -->|"loads commands"| node_command_loader
node_module_loader -.->|"loads assemblies"| node_load_context
node_chat_user -.->|"sends chat"| node_chat_transport
node_chat_transport -->|"raises messages"| node_twitch_client
node_twitch_client -.->|"raises message"| node_core
node_twitch_module -.->|"uses"| node_twitch_client
node_core -.->|"processes commands"| node_dispatcher
node_dispatcher -.->|"resolves commands"| node_registry
node_module_manager -->|"registers exports"| node_registry
node_dispatcher -.->|"executes command"| node_app_commands
node_twitch_client -->|"resolves channels"| node_channel_manager
node_channel_manager -->|"reads and writes"| node_redis
node_banphrases -->|"reads and writes"| node_redis
node_user_repository -.->|"stores users"| node_redis
node_host -.->|"registers"| node_localization
node_localization -->|"resolves locales"| node_locale_registry
node_locale_registry -->|"loads registry"| node_translation_loader
node_twitch_auth -->|"polls tokens"| node_auth_service
node_twitch_auth -->|"validates tokens"| node_twitch_client
node_twitch_client -->|"validates tokens"| node_twitch_api
node_dashboard -.->|"publishes metrics"| node_dashboard_bridge

click node_host "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Host/Program.cs"
click node_hosted "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Host/BotHostedService.cs"
click node_module_manager "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/PlatformModuleManager.cs"
click node_module_loader "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Loader/ChatModuleLoader.cs"
click node_command_loader "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Loader/CommandModuleLoader.cs"
click node_load_context "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Loader/ModuleAssemblyLoadContext.cs"
click node_chat_transport "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Services/ChatTransports/TwitchChatTransport.cs"
click node_twitch_client "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Services/TwitchClient.cs"
click node_twitch_module "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/TwitchModule.cs"
click node_app_commands "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Application/Commands/UserInfoCommand.cs"
click node_core "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/BotCore.cs"
click node_dispatcher "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/CommandDispatcher.cs"
click node_registry "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/CommandRegistry.cs"
click node_dynamic_services "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Core/DynamicServiceProvider.cs"
click node_localization "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Localization/Services/LocalizationService.cs"
click node_locale_registry "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Localization/Services/LocaleRegistryService.cs"
click node_translation_loader "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Localization/Services/TranslationFileLoader.cs"
click node_channel_manager "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Models/TwitchChannelManager.cs"
click node_banphrases "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Data/Repositories/BanphraseRepository.cs"
click node_user_repository "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Data/Repositories/RedisUserRepository.cs"
click node_dashboard "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Dashboard/Services/MetricsCollector.cs"
click node_dashboard_bridge "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Dashboard/Services/DashboardBridge.cs"
click node_twitch_auth "https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Services/Auth/TwitchAuthPollingService.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_host,node_hosted,node_module_manager,node_module_loader,node_command_loader,node_load_context,node_chat_user toneBlue
class node_chat_transport,node_twitch_client,node_twitch_module,node_app_commands,node_twitch_auth toneAmber
class node_core,node_dispatcher,node_registry,node_dynamic_services,node_localization,node_locale_registry,node_translation_loader,node_twitch_api,node_auth_service toneMint
class node_redis,node_channel_manager,node_banphrases,node_user_repository,node_dashboard,node_dashboard_bridge toneRose
```

## Components

### Host and runtime

- [Application host](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Host/Program.cs): `ButterBror.Host/Program.cs`
- [Bot lifecycle](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Host/BotHostedService.cs): `ButterBror.Host/BotHostedService.cs`
- [Module manager](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/PlatformModuleManager.cs): `ButterBror.Infrastructure/Services/PlatformModuleManager.cs`
- [Package loader](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Loader/ChatModuleLoader.cs): `ButterBror.ChatModules.Loader/ChatModuleLoader.cs`
- [Command loader](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Loader/CommandModuleLoader.cs): `ButterBror.ChatModules.Loader/CommandModuleLoader.cs`
- [Assembly context](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Loader/ModuleAssemblyLoadContext.cs): `ButterBror.ChatModules.Loader/ModuleAssemblyLoadContext.cs`

### Chat and commands

- [Twitch transport](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Services/ChatTransports/TwitchChatTransport.cs): `ButterBror.ChatModules.Twitch/Services/ChatTransports/TwitchChatTransport.cs`
- [Twitch client](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Services/TwitchClient.cs): `ButterBror.ChatModules.Twitch/Services/TwitchClient.cs`
- [Twitch module](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/TwitchModule.cs): `ButterBror.ChatModules.Twitch/TwitchModule.cs`
- [Application commands](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Application/Commands/UserInfoCommand.cs): `ButterBror.Application/Commands/UserInfoCommand.cs`
- [Twitch authorization](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Services/Auth/TwitchAuthPollingService.cs): `ButterBror.ChatModules.Twitch/Services/Auth/TwitchAuthPollingService.cs`

### Core services

- [Bot core](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/BotCore.cs): `ButterBror.Infrastructure/Services/BotCore.cs`
- [Command processing](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/CommandDispatcher.cs): `ButterBror.Infrastructure/Services/CommandDispatcher.cs`
- [Command registry](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Infrastructure/Services/CommandRegistry.cs): `ButterBror.Infrastructure/Services/CommandRegistry.cs`
- [Dynamic services](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Core/DynamicServiceProvider.cs): `ButterBror.Core/DynamicServiceProvider.cs`
- [Localization](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Localization/Services/LocalizationService.cs): `ButterBror.Localization/Services/LocalizationService.cs`
- [Locale registry](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Localization/Services/LocaleRegistryService.cs): `ButterBror.Localization/Services/LocaleRegistryService.cs`
- [Translation loader](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Localization/Services/TranslationFileLoader.cs): `ButterBror.Localization/Services/TranslationFileLoader.cs`

### Data and dashboard

- **Redis service**
- [Twitch channels](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.ChatModules.Twitch/Models/TwitchChannelManager.cs): `ButterBror.ChatModules.Twitch/Models/TwitchChannelManager.cs`
- [Banphrase repository](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Data/Repositories/BanphraseRepository.cs): `ButterBror.Data/Repositories/BanphraseRepository.cs`
- [User repository](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Data/Repositories/RedisUserRepository.cs): `ButterBror.Data/Repositories/RedisUserRepository.cs`
- [Dashboard services](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Dashboard/Services/MetricsCollector.cs): `ButterBror.Dashboard/Services/MetricsCollector.cs`
- [Dashboard bridge](https://github.com/itzkitb/butterbror2/blob/main/ButterBror.Dashboard/Services/DashboardBridge.cs): `ButterBror.Dashboard/Services/DashboardBridge.cs`

### Other components

- **Chat user**
- **Twitch API**
- **Auth API**

## Connections

- Application host → Bot lifecycle: hosts (evidence: `ButterBror.Host/Program.cs`)
- Application host → Bot core: registers (evidence: `ButterBror.Host/Program.cs`)
- Application host → Dynamic services: registers (evidence: `ButterBror.Host/Program.cs`)
- Application host → User repository: registers (evidence: `ButterBror.Host/Program.cs`)
- Application host → Dashboard bridge: registers (evidence: `ButterBror.Host/Program.cs`)
- Bot lifecycle → Bot core: starts (evidence: `ButterBror.Host/BotHostedService.cs`)
- Bot core → Module manager: initializes
- Module manager → Package loader: loads modules
- Module manager → Command loader: loads commands (evidence: `ButterBror.Infrastructure/Services/PlatformModuleManager.cs`)
- Package loader → Assembly context: loads assemblies
- Chat user → Twitch transport: sends chat
- Twitch transport → Twitch client: raises messages (evidence: `ButterBror.ChatModules.Twitch/Services/TwitchClient.cs`)
- Twitch client → Bot core: raises message
- Twitch module → Twitch client: uses
- Bot core → Command processing: processes commands
- Command processing → Command registry: resolves commands
- Module manager → Command registry: registers exports (evidence: `ButterBror.Infrastructure/Services/PlatformModuleManager.cs`)
- Command processing → Application commands: executes command
- Twitch client → Twitch channels: resolves channels (evidence: `ButterBror.ChatModules.Twitch/Services/TwitchClient.cs`)
- Twitch channels → Redis service: reads and writes (evidence: `ButterBror.ChatModules.Twitch/Models/TwitchChannelManager.cs`)
- Banphrase repository → Redis service: reads and writes (evidence: `ButterBror.Data/Repositories/BanphraseRepository.cs`)
- User repository → Redis service: stores users
- Application host → Localization: registers
- Localization → Locale registry: resolves locales (evidence: `ButterBror.Localization/Services/LocalizationService.cs`)
- Locale registry → Translation loader: loads registry (evidence: `ButterBror.Localization/Services/LocaleRegistryService.cs`)
- Twitch authorization → Auth API: polls tokens (evidence: `ButterBror.ChatModules.Twitch/Services/Auth/TwitchAuthPollingService.cs`)
- Twitch authorization → Twitch client: validates tokens (evidence: `ButterBror.ChatModules.Twitch/Services/Auth/TwitchAuthPollingService.cs`)
- Twitch client → Twitch API: validates tokens (evidence: `ButterBror.ChatModules.Twitch/Services/TwitchClient.cs`)
- Dashboard services → Dashboard bridge: publishes metrics
