# krapmatt/krapbott architecture

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

## Overview

Krapbott is a multi-platform chat bot with queue management and a web-based OBS control surface. Its main runtime receives Twitch and Kick chat events, routes them through channel-specific command dispatch, performs queue or moderation work, and sends replies; queue changes can also publish SSE updates. The tree documents additional Bungie, alias, channel-configuration, OAuth, and web-session capabilities. Sampled excerpts support the central event, queue, persistence, and authentication paths; wiring for other commands and web handlers is shown only where the tree establishes the subsystem, not as inferred calls.

Main entry points: [`src/bot/db`](https://github.com/krapmatt/krapbott/tree/master/src/bot/db) (Database access), [`src/bot/web`](https://github.com/krapmatt/krapbott/tree/master/src/bot/web) (Web endpoints), [`src/bot/dispatcher/dispatcher.rs`](https://github.com/krapmatt/krapbott/blob/master/src/bot/dispatcher/dispatcher.rs) (Command dispatcher), [`src/bot/commands/queue/commands.rs`](https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/queue/commands.rs) (Queue commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Chat runtime"]
  node_main["Application startup<br/>[main.rs]"]
  node_eventloop["Event loop<br/>[mod.rs]"]
  node_handler["Event handler<br/>[handler.rs]"]
  node_dispatcher["Command dispatcher<br/>[dispatcher.rs]"]
  node_state["Application state<br/>[def.rs]"]
  node_lifecycle["Channel lifecycle"]
end

subgraph group_features["Bot features"]
  node_registry["Command registry<br/>[commands.rs]"]
  node_queuecmd["Queue commands<br/>[commands.rs]"]
  node_queuelogic["Queue logic<br/>[logic.rs]"]
  node_modcmd["Moderation commands<br/>[commands.rs]"]
  node_permissions["Permissions<br/>[permissions.rs]"]
end

subgraph group_web["Web control"]
  node_websurface["Web endpoints"]
  node_auth["Web authentication<br/>[auth.rs]"]
  node_sessions["Web sessions<br/>[sessions.rs]"]
  node_obs["OBS queue controls<br/>[obs.rs]"]
  node_sse["Queue event stream<br/>[sse.rs]"]
end

subgraph group_integrations["Platform integrations"]
  node_platforms["Platform event loops"]
  node_chatclient["Unified chat client<br/>[handler.rs]"]
  node_twitch["Twitch adapter"]
  node_kick["Kick adapter"]
  node_api["Platform APIs"]
  node_kickoauth["Kick OAuth<br/>[kick_oauth.rs]"]
end

subgraph group_storage["Persistence"]
  node_db["Database access"]
  node_postgres[("PostgreSQL")]
end

node_viewer(("Chat participant"))
node_externalchat(("Twitch and Kick"))
node_kickservice(("Kick OAuth service"))
node_twitchservice(("Twitch OAuth API"))
node_obsclient(("OBS dashboard"))
node_browser(("Web user"))

node_viewer -->|"sends chat"| node_externalchat
node_externalchat -->|"delivers events"| node_platforms
node_main -->|"starts runtime"| node_eventloop
node_main -->|"serves routes"| node_websurface
node_main -->|"connects"| node_postgres
node_eventloop -->|"handles events"| node_handler
node_handler -->|"starts channels"| node_lifecycle
node_handler -->|"dispatches event"| node_dispatcher
node_platforms -->|"sends events"| node_eventloop
node_dispatcher -->|"resolves commands"| node_registry
node_dispatcher -->|"checks access"| node_permissions
node_queuecmd -->|"uses queue rules"| node_queuelogic
node_queuecmd -->|"reads and updates"| node_db
node_modcmd -->|"updates configuration"| node_db
node_modcmd -->|"refreshes dispatch"| node_dispatcher
node_queuecmd -->|"sends replies"| node_chatclient
node_chatclient -->|"sends and joins"| node_twitch
node_chatclient -->|"sends and joins"| node_kick
node_kick -->|"obtains access token"| node_kickoauth
node_twitch -->|"connects to"| node_externalchat
node_kick -->|"connects to"| node_externalchat
node_api -.->|"calls platform API"| node_twitchservice
node_kickoauth -->|"requests tokens"| node_kickservice
node_auth -->|"exchanges credentials"| node_twitchservice
node_auth -->|"builds authorization"| node_kickoauth
node_websurface -->|"routes auth"| node_auth
node_websurface -->|"routes OBS actions"| node_obs
node_websurface -->|"routes event stream"| node_sse
node_browser -->|"requests controls"| node_websurface
node_auth -->|"stores sessions"| node_db
node_sessions -->|"reads sessions"| node_db
node_obs -->|"validates cookies"| node_sessions
node_obs -->|"reads and updates queue"| node_db
node_obs -->|"publishes queue updates"| node_sse
node_sse -->|"streams events"| node_obsclient
node_queuecmd -->|"publishes queue updates"| node_sse
node_db -->|"queries and persists"| node_postgres
node_state -->|"holds runtime dispatchers"| node_dispatcher
node_lifecycle -->|"joins configured channels"| node_platforms

click node_main "https://github.com/krapmatt/krapbott/blob/master/src/main.rs"
click node_eventloop "https://github.com/krapmatt/krapbott/blob/master/src/bot/mod.rs"
click node_platforms "https://github.com/krapmatt/krapbott/tree/master/src/bot/platforms"
click node_handler "https://github.com/krapmatt/krapbott/blob/master/src/bot/handler/handler.rs"
click node_dispatcher "https://github.com/krapmatt/krapbott/blob/master/src/bot/dispatcher/dispatcher.rs"
click node_registry "https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/commands.rs"
click node_queuecmd "https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/queue/commands.rs"
click node_queuelogic "https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/queue/logic.rs"
click node_modcmd "https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/moderation/commands.rs"
click node_permissions "https://github.com/krapmatt/krapbott/blob/master/src/bot/permissions/permissions.rs"
click node_state "https://github.com/krapmatt/krapbott/blob/master/src/bot/state/def.rs"
click node_lifecycle "https://github.com/krapmatt/krapbott/blob/master/src/bot/runtime/channel_lifecycle.rs"
click node_chatclient "https://github.com/krapmatt/krapbott/blob/master/src/bot/handler/handler.rs"
click node_twitch "https://github.com/krapmatt/krapbott/tree/master/src/bot/platforms/twitch"
click node_kick "https://github.com/krapmatt/krapbott/tree/master/src/bot/platforms/kick"
click node_api "https://github.com/krapmatt/krapbott/tree/master/src/api"
click node_kickoauth "https://github.com/krapmatt/krapbott/blob/master/src/api/kick_oauth.rs"
click node_websurface "https://github.com/krapmatt/krapbott/tree/master/src/bot/web"
click node_auth "https://github.com/krapmatt/krapbott/blob/master/src/bot/web/auth.rs"
click node_sessions "https://github.com/krapmatt/krapbott/blob/master/src/bot/web/sessions.rs"
click node_obs "https://github.com/krapmatt/krapbott/blob/master/src/bot/web/obs.rs"
click node_sse "https://github.com/krapmatt/krapbott/blob/master/src/bot/web/sse.rs"
click node_db "https://github.com/krapmatt/krapbott/tree/master/src/bot/db"

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_main,node_eventloop,node_handler,node_dispatcher,node_state,node_lifecycle,node_browser toneBlue
class node_registry,node_queuecmd,node_queuelogic,node_modcmd,node_permissions toneAmber
class node_websurface,node_auth,node_sessions,node_obs,node_sse,node_twitchservice toneMint
class node_platforms,node_chatclient,node_twitch,node_kick,node_api,node_kickoauth toneRose
class node_db,node_postgres,node_viewer,node_externalchat,node_kickservice,node_obsclient toneIndigo
```

## Components

### Chat runtime

- [Application startup](https://github.com/krapmatt/krapbott/blob/master/src/main.rs): `src/main.rs`
- [Event loop](https://github.com/krapmatt/krapbott/blob/master/src/bot/mod.rs): `src/bot/mod.rs`
- [Event handler](https://github.com/krapmatt/krapbott/blob/master/src/bot/handler/handler.rs): `src/bot/handler/handler.rs`
- [Command dispatcher](https://github.com/krapmatt/krapbott/blob/master/src/bot/dispatcher/dispatcher.rs): `src/bot/dispatcher/dispatcher.rs`
- [Application state](https://github.com/krapmatt/krapbott/blob/master/src/bot/state/def.rs): `src/bot/state/def.rs`
- [Channel lifecycle](https://github.com/krapmatt/krapbott/blob/master/src/bot/runtime/channel_lifecycle.rs): `src/bot/runtime/channel_lifecycle.rs`

### Bot features

- [Command registry](https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/commands.rs): `src/bot/commands/commands.rs`
- [Queue commands](https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/queue/commands.rs): `src/bot/commands/queue/commands.rs`
- [Queue logic](https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/queue/logic.rs): `src/bot/commands/queue/logic.rs`
- [Moderation commands](https://github.com/krapmatt/krapbott/blob/master/src/bot/commands/moderation/commands.rs): `src/bot/commands/moderation/commands.rs`
- [Permissions](https://github.com/krapmatt/krapbott/blob/master/src/bot/permissions/permissions.rs): `src/bot/permissions/permissions.rs`

### Web control

- [Web endpoints](https://github.com/krapmatt/krapbott/tree/master/src/bot/web): `src/bot/web`
- [Web authentication](https://github.com/krapmatt/krapbott/blob/master/src/bot/web/auth.rs): `src/bot/web/auth.rs`
- [Web sessions](https://github.com/krapmatt/krapbott/blob/master/src/bot/web/sessions.rs): `src/bot/web/sessions.rs`
- [OBS queue controls](https://github.com/krapmatt/krapbott/blob/master/src/bot/web/obs.rs): `src/bot/web/obs.rs`
- [Queue event stream](https://github.com/krapmatt/krapbott/blob/master/src/bot/web/sse.rs): `src/bot/web/sse.rs`

### Platform integrations

- [Platform event loops](https://github.com/krapmatt/krapbott/tree/master/src/bot/platforms): `src/bot/platforms`
- [Unified chat client](https://github.com/krapmatt/krapbott/blob/master/src/bot/handler/handler.rs): `src/bot/handler/handler.rs`
- [Twitch adapter](https://github.com/krapmatt/krapbott/tree/master/src/bot/platforms/twitch): `src/bot/platforms/twitch`
- [Kick adapter](https://github.com/krapmatt/krapbott/tree/master/src/bot/platforms/kick): `src/bot/platforms/kick`
- [Platform APIs](https://github.com/krapmatt/krapbott/tree/master/src/api): `src/api`
- [Kick OAuth](https://github.com/krapmatt/krapbott/blob/master/src/api/kick_oauth.rs): `src/api/kick_oauth.rs`

### Persistence

- [Database access](https://github.com/krapmatt/krapbott/tree/master/src/bot/db): `src/bot/db`
- **PostgreSQL**

### Other components

- **Chat participant**
- **Twitch and Kick**
- **Kick OAuth service**
- **Twitch OAuth API**
- **OBS dashboard**
- **Web user**

## Connections

- Chat participant → Twitch and Kick: sends chat
- Twitch and Kick → Platform event loops: delivers events
- Application startup → Event loop: starts runtime
- Application startup → Web endpoints: serves routes
- Application startup → PostgreSQL: connects
- Event loop → Event handler: handles events
- Event handler → Channel lifecycle: starts channels
- Event handler → Command dispatcher: dispatches event
- Platform event loops → Event loop: sends events
- Command dispatcher → Command registry: resolves commands
- Command dispatcher → Permissions: checks access
- Queue commands → Queue logic: uses queue rules
- Queue commands → Database access: reads and updates
- Moderation commands → Database access: updates configuration
- Moderation commands → Command dispatcher: refreshes dispatch
- Queue commands → Unified chat client: sends replies
- Unified chat client → Twitch adapter: sends and joins
- Unified chat client → Kick adapter: sends and joins
- Kick adapter → Kick OAuth: obtains access token
- Twitch adapter → Twitch and Kick: connects to
- Kick adapter → Twitch and Kick: connects to
- Platform APIs → Twitch OAuth API: calls platform API
- Kick OAuth → Kick OAuth service: requests tokens
- Web authentication → Twitch OAuth API: exchanges credentials
- Web authentication → Kick OAuth: builds authorization
- Web endpoints → Web authentication: routes auth
- Web endpoints → OBS queue controls: routes OBS actions
- Web endpoints → Queue event stream: routes event stream
- Web user → Web endpoints: requests controls
- Web authentication → Database access: stores sessions
- Web sessions → Database access: reads sessions
- OBS queue controls → Web sessions: validates cookies
- OBS queue controls → Database access: reads and updates queue
- OBS queue controls → Queue event stream: publishes queue updates
- Queue event stream → OBS dashboard: streams events
- Queue commands → Queue event stream: publishes queue updates
- Database access → PostgreSQL: queries and persists
- Application state → Command dispatcher: holds runtime dispatchers
- Channel lifecycle → Platform event loops: joins configured channels