# mpursa/kiwibot architecture

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

- Interactive diagram: https://gitdiagram.com/mpursa/kiwibot
- Repository: https://github.com/mpursa/kiwibot

## Overview

KiwiBot is a Discord bot that lets authorized users inspect and control configured game servers. The main workflow is a slash command received by the bot, role-checked and dispatched to a handler, which reads server state or player data and may start, stop, or schedule a stop before replying in Discord. A separate poller auto-stops servers only after confirmed idleness. The graph reflects documented commands and capabilities; unsampled handler details are represented at the resolver level, without assuming additional internal call paths.

Main entry points: [`src/handler/resolve.ts`](https://github.com/mpursa/kiwibot/blob/main/src/handler/resolve.ts) (Command handlers), [`src/main.ts`](https://github.com/mpursa/kiwibot/blob/main/src/main.ts) (Bot entry point), [`src/server/autostop.ts`](https://github.com/mpursa/kiwibot/blob/main/src/server/autostop.ts) (Idle-stop poller), [`src/discord/messaging.ts`](https://github.com/mpursa/kiwibot/blob/main/src/discord/messaging.ts) (Replies and alerts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord["Discord interface"]
  node_main["Bot entry point<br/>[main.ts]"]
  node_commands["Slash commands<br/>[commands.ts]"]
  node_messaging["Replies and alerts<br/>[messaging.ts]"]
end

subgraph group_control["Command control"]
  node_resolve["Command handlers<br/>[resolve.ts]"]
  node_roles["Role checks<br/>[roles.ts]"]
end

subgraph group_server["Server operations"]
  node_autostop["Idle-stop poller<br/>[autostop.ts]"]
  node_state["Unit and socket state<br/>[state.ts]"]
  node_players["Player parsing<br/>[players.ts]"]
  node_rcon["RCON client<br/>[rcon.ts]"]
end

subgraph group_config["Configuration"]
  node_config["Server configuration<br/>[cfg.ts]"]
end

node_user(("Discord user"))
node_discord(("Discord API"))
node_host["Host services"]
node_game["Game servers"]

node_user -->|"submits commands"| node_discord
node_discord -->|"delivers interactions"| node_main
node_main -->|"registers commands"| node_discord
node_main -->|"loads definitions"| node_commands
node_main -->|"dispatches commands"| node_resolve
node_main -->|"starts poller"| node_autostop
node_main -->|"checks sudo access"| node_state
node_main -->|"sends startup alert"| node_messaging
node_commands -->|"builds server choices"| node_config
node_resolve -->|"looks up command"| node_commands
node_resolve -->|"selects server"| node_config
node_resolve -->|"checks access"| node_roles
node_resolve -->|"reads or controls unit"| node_state
node_resolve -->|"checks connected players"| node_players
node_resolve -->|"queries player answer"| node_rcon
node_resolve -->|"announces actions"| node_messaging
node_resolve -->|"replies to command"| node_discord
node_state -->|"runs systemctl and ss"| node_host
node_autostop -->|"reads idle settings"| node_config
node_autostop -->|"checks and stops units"| node_state
node_autostop -->|"checks occupancy"| node_players
node_autostop -->|"sends stop alerts"| node_messaging
node_players -->|"queries game"| node_rcon
node_rcon -->|"exchanges RCON data"| node_game
node_messaging -->|"posts messages"| node_discord

click node_main "https://github.com/mpursa/kiwibot/blob/main/src/main.ts"
click node_commands "https://github.com/mpursa/kiwibot/blob/main/src/discord/commands.ts"
click node_messaging "https://github.com/mpursa/kiwibot/blob/main/src/discord/messaging.ts"
click node_resolve "https://github.com/mpursa/kiwibot/blob/main/src/handler/resolve.ts"
click node_roles "https://github.com/mpursa/kiwibot/blob/main/src/discord/roles.ts"
click node_config "https://github.com/mpursa/kiwibot/blob/main/src/core/cfg.ts"
click node_autostop "https://github.com/mpursa/kiwibot/blob/main/src/server/autostop.ts"
click node_state "https://github.com/mpursa/kiwibot/blob/main/src/server/state.ts"
click node_players "https://github.com/mpursa/kiwibot/blob/main/src/server/players.ts"
click node_rcon "https://github.com/mpursa/kiwibot/blob/main/src/server/rcon.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_main,node_commands,node_messaging,node_user toneBlue
class node_resolve,node_roles toneAmber
class node_autostop,node_state,node_players,node_rcon,node_discord,node_game toneMint
class node_config toneRose
class node_host toneIndigo
```

## Components

### Discord interface

- [Bot entry point](https://github.com/mpursa/kiwibot/blob/main/src/main.ts): `src/main.ts`
- [Slash commands](https://github.com/mpursa/kiwibot/blob/main/src/discord/commands.ts): `src/discord/commands.ts`
- [Replies and alerts](https://github.com/mpursa/kiwibot/blob/main/src/discord/messaging.ts): `src/discord/messaging.ts`

### Command control

- [Command handlers](https://github.com/mpursa/kiwibot/blob/main/src/handler/resolve.ts): `src/handler/resolve.ts`
- [Role checks](https://github.com/mpursa/kiwibot/blob/main/src/discord/roles.ts): `src/discord/roles.ts`

### Server operations

- [Idle-stop poller](https://github.com/mpursa/kiwibot/blob/main/src/server/autostop.ts): `src/server/autostop.ts`
- [Unit and socket state](https://github.com/mpursa/kiwibot/blob/main/src/server/state.ts): `src/server/state.ts`
- [Player parsing](https://github.com/mpursa/kiwibot/blob/main/src/server/players.ts): `src/server/players.ts`
- [RCON client](https://github.com/mpursa/kiwibot/blob/main/src/server/rcon.ts): `src/server/rcon.ts`

### Configuration

- [Server configuration](https://github.com/mpursa/kiwibot/blob/main/src/core/cfg.ts): `src/core/cfg.ts`

### Other components

- **Discord user**
- **Discord API**
- **Host services**
- **Game servers**

## Connections

- Discord user → Discord API: submits commands
- Discord API → Bot entry point: delivers interactions
- Bot entry point → Discord API: registers commands
- Bot entry point → Slash commands: loads definitions
- Bot entry point → Command handlers: dispatches commands
- Bot entry point → Idle-stop poller: starts poller
- Bot entry point → Unit and socket state: checks sudo access
- Bot entry point → Replies and alerts: sends startup alert
- Slash commands → Server configuration: builds server choices
- Command handlers → Slash commands: looks up command
- Command handlers → Server configuration: selects server
- Command handlers → Role checks: checks access
- Command handlers → Unit and socket state: reads or controls unit
- Command handlers → Player parsing: checks connected players
- Command handlers → RCON client: queries player answer
- Command handlers → Replies and alerts: announces actions
- Command handlers → Discord API: replies to command
- Unit and socket state → Host services: runs systemctl and ss
- Idle-stop poller → Server configuration: reads idle settings
- Idle-stop poller → Unit and socket state: checks and stops units
- Idle-stop poller → Player parsing: checks occupancy
- Idle-stop poller → Replies and alerts: sends stop alerts
- Player parsing → RCON client: queries game
- RCON client → Game servers: exchanges RCON data
- Replies and alerts → Discord API: posts messages