# ioniccompound/kasumi architecture

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

- Interactive diagram: https://gitdiagram.com/ioniccompound/kasumi
- Repository: https://github.com/ioniccompound/kasumi

## Overview

Kasumi.js is a TypeScript framework/SDK for building KOOK chatbots. Its documented scope is broad, but the supplied README gives little workflow detail; source excerpts show API calls through a shared REST client, card construction for messages and threads, and two WebSocket connection implementations. The graph preserves the major API, event, plugin, messaging, and configuration branches visible in the tree. Some subsystem links are omitted where the supplied excerpts do not establish runtime wiring.

Main entry points: [`src/api/index.ts`](https://github.com/ioniccompound/kasumi/blob/main/src/api/index.ts) (API facade), [`src/requestor/index.ts`](https://github.com/ioniccompound/kasumi/blob/main/src/requestor/index.ts) (REST requestor), [`src/api/message/index.ts`](https://github.com/ioniccompound/kasumi/blob/main/src/api/message/index.ts) (Messages), [`src/api/thread/index.ts`](https://github.com/ioniccompound/kasumi/blob/main/src/api/thread/index.ts) (Threads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["KOOK API"]
  node_rest["REST requestor<br/>[index.ts]"]
  node_apiroot["API facade<br/>[index.ts]"]
  node_channels["Channels<br/>[index.ts]"]
  node_guilds["Guilds<br/>[index.ts]"]
  node_messages["Messages<br/>[index.ts]"]
  node_threads["Threads<br/>[index.ts]"]
  node_otherapis["Other API domains"]
end

subgraph group_realtime["Realtime Transport"]
  node_botrootws["BotRoot WebSocket<br/>[index.ts]"]
  node_botrootmessages["BotRoot messages<br/>[messageSource.ts]"]
  node_kooktsws["KookTS WebSocket<br/>[websocket.ts]"]
  node_kooktsbase["KookTS client base<br/>[base.ts]"]
  node_wshelper["WebSocket helpers"]
end

subgraph group_bot["Bot Features"]
  node_events["Event handling"]
  node_plugins["Plugins and commands<br/>[plugin.ts]"]
  node_middleware["Command middleware"]
  node_cards["Card messages<br/>[card.ts]"]
  node_cardbuilder["Card builder<br/>[builder.ts]"]
  node_webhooks["Webhook support<br/>[index.ts]"]
end

subgraph group_state["Configuration"]
  node_config["Bot configuration<br/>[config.ts]"]
  node_mongodb[("MongoDB storage<br/>[index.ts]")]
end

node_developer(("Bot developer"))
node_kook(("KOOK platform"))

node_apiroot -->|"constructs"| node_rest
node_apiroot -->|"creates"| node_channels
node_apiroot -->|"creates"| node_guilds
node_apiroot -->|"creates"| node_messages
node_apiroot -->|"creates"| node_threads
node_apiroot -->|"creates"| node_otherapis
node_channels -->|"requests"| node_rest
node_messages -->|"requests"| node_rest
node_threads -->|"requests"| node_rest
node_threads -->|"formats with"| node_cards
node_messages -->|"accepts"| node_cards
node_cards -->|"creates"| node_cardbuilder
node_botrootws -->|"imports"| node_botrootmessages
node_kooktsws -->|"uses"| node_wshelper
node_kooktsbase -->|"imports"| node_kooktsws
node_developer -.->|"uses"| node_apiroot
node_developer -.->|"configures"| node_plugins
node_rest -.->|"sends requests"| node_kook
node_botrootws -.->|"connects"| node_kook
node_kooktsws -.->|"connects"| node_kook
node_config -.->|"configures"| node_mongodb

click node_rest "https://github.com/ioniccompound/kasumi/blob/main/src/requestor/index.ts"
click node_apiroot "https://github.com/ioniccompound/kasumi/blob/main/src/api/index.ts"
click node_channels "https://github.com/ioniccompound/kasumi/blob/main/src/api/channel/index.ts"
click node_guilds "https://github.com/ioniccompound/kasumi/blob/main/src/api/guild/index.ts"
click node_messages "https://github.com/ioniccompound/kasumi/blob/main/src/api/message/index.ts"
click node_threads "https://github.com/ioniccompound/kasumi/blob/main/src/api/thread/index.ts"
click node_otherapis "https://github.com/ioniccompound/kasumi/tree/main/src/api"
click node_botrootws "https://github.com/ioniccompound/kasumi/blob/main/src/websocket-botroot/index.ts"
click node_botrootmessages "https://github.com/ioniccompound/kasumi/blob/main/src/websocket-botroot/messageSource.ts"
click node_kooktsws "https://github.com/ioniccompound/kasumi/blob/main/src/websocket-kookts/event-receiver/websocket.ts"
click node_kooktsbase "https://github.com/ioniccompound/kasumi/blob/main/src/websocket-kookts/base.ts"
click node_wshelper "https://github.com/ioniccompound/kasumi/blob/main/src/websocket-kookts/event-receiver/websocket.helper.ts"
click node_events "https://github.com/ioniccompound/kasumi/tree/main/src/events"
click node_plugins "https://github.com/ioniccompound/kasumi/blob/main/src/plugin/plugin.ts"
click node_middleware "https://github.com/ioniccompound/kasumi/tree/main/src/plugin/middlewares"
click node_cards "https://github.com/ioniccompound/kasumi/blob/main/src/card/card.ts"
click node_cardbuilder "https://github.com/ioniccompound/kasumi/blob/main/src/card/builder.ts"
click node_webhooks "https://github.com/ioniccompound/kasumi/blob/main/src/webhook/index.ts"
click node_config "https://github.com/ioniccompound/kasumi/blob/main/src/config/config.ts"
click node_mongodb "https://github.com/ioniccompound/kasumi/blob/main/src/config/database/mongodb/index.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_rest,node_apiroot,node_channels,node_guilds,node_messages,node_threads,node_otherapis toneBlue
class node_botrootws,node_botrootmessages,node_kooktsws,node_kooktsbase,node_wshelper toneAmber
class node_events,node_plugins,node_middleware,node_cards,node_cardbuilder,node_webhooks toneMint
class node_config,node_mongodb toneRose
class node_developer,node_kook toneIndigo
```

## Components

### KOOK API

- [REST requestor](https://github.com/ioniccompound/kasumi/blob/main/src/requestor/index.ts): `src/requestor/index.ts`
- [API facade](https://github.com/ioniccompound/kasumi/blob/main/src/api/index.ts): `src/api/index.ts`
- [Channels](https://github.com/ioniccompound/kasumi/blob/main/src/api/channel/index.ts): `src/api/channel/index.ts`
- [Guilds](https://github.com/ioniccompound/kasumi/blob/main/src/api/guild/index.ts): `src/api/guild/index.ts`
- [Messages](https://github.com/ioniccompound/kasumi/blob/main/src/api/message/index.ts): `src/api/message/index.ts`
- [Threads](https://github.com/ioniccompound/kasumi/blob/main/src/api/thread/index.ts): `src/api/thread/index.ts`
- [Other API domains](https://github.com/ioniccompound/kasumi/tree/main/src/api): `src/api`

### Realtime Transport

- [BotRoot WebSocket](https://github.com/ioniccompound/kasumi/blob/main/src/websocket-botroot/index.ts): `src/websocket-botroot/index.ts`
- [BotRoot messages](https://github.com/ioniccompound/kasumi/blob/main/src/websocket-botroot/messageSource.ts): `src/websocket-botroot/messageSource.ts`
- [KookTS WebSocket](https://github.com/ioniccompound/kasumi/blob/main/src/websocket-kookts/event-receiver/websocket.ts): `src/websocket-kookts/event-receiver/websocket.ts`
- [KookTS client base](https://github.com/ioniccompound/kasumi/blob/main/src/websocket-kookts/base.ts): `src/websocket-kookts/base.ts`
- [WebSocket helpers](https://github.com/ioniccompound/kasumi/blob/main/src/websocket-kookts/event-receiver/websocket.helper.ts): `src/websocket-kookts/event-receiver/websocket.helper.ts`

### Bot Features

- [Event handling](https://github.com/ioniccompound/kasumi/tree/main/src/events): `src/events`
- [Plugins and commands](https://github.com/ioniccompound/kasumi/blob/main/src/plugin/plugin.ts): `src/plugin/plugin.ts`
- [Command middleware](https://github.com/ioniccompound/kasumi/tree/main/src/plugin/middlewares): `src/plugin/middlewares`
- [Card messages](https://github.com/ioniccompound/kasumi/blob/main/src/card/card.ts): `src/card/card.ts`
- [Card builder](https://github.com/ioniccompound/kasumi/blob/main/src/card/builder.ts): `src/card/builder.ts`
- [Webhook support](https://github.com/ioniccompound/kasumi/blob/main/src/webhook/index.ts): `src/webhook/index.ts`

### Configuration

- [Bot configuration](https://github.com/ioniccompound/kasumi/blob/main/src/config/config.ts): `src/config/config.ts`
- [MongoDB storage](https://github.com/ioniccompound/kasumi/blob/main/src/config/database/mongodb/index.ts): `src/config/database/mongodb/index.ts`

### Other components

- **Bot developer**
- **KOOK platform**

## Connections

- API facade → REST requestor: constructs (evidence: `src/api/index.ts`)
- API facade → Channels: creates (evidence: `src/api/index.ts`)
- API facade → Guilds: creates (evidence: `src/api/index.ts`)
- API facade → Messages: creates (evidence: `src/api/index.ts`)
- API facade → Threads: creates (evidence: `src/api/index.ts`)
- API facade → Other API domains: creates (evidence: `src/api/index.ts`)
- Channels → REST requestor: requests (evidence: `src/api/channel/index.ts`)
- Messages → REST requestor: requests (evidence: `src/api/message/index.ts`)
- Threads → REST requestor: requests (evidence: `src/api/thread/index.ts`)
- Threads → Card messages: formats with (evidence: `src/api/thread/index.ts`)
- Messages → Card messages: accepts (evidence: `src/api/message/index.ts`)
- Card messages → Card builder: creates (evidence: `src/card/card.ts`)
- BotRoot WebSocket → BotRoot messages: imports (evidence: `src/websocket-botroot/index.ts`)
- KookTS WebSocket → WebSocket helpers: uses (evidence: `src/websocket-kookts/event-receiver/websocket.ts`)
- KookTS client base → KookTS WebSocket: imports (evidence: `src/websocket-kookts/base.ts`)
- Bot developer → API facade: uses
- Bot developer → Plugins and commands: configures
- REST requestor → KOOK platform: sends requests
- BotRoot WebSocket → KOOK platform: connects
- KookTS WebSocket → KOOK platform: connects
- Bot configuration → MongoDB storage: configures
