# penguinmod/penguinbot-public architecture

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

## Overview

PenguinBot is a Discord bot whose main workflow is receiving Discord events, applying configured command and access checks, then invoking commands that reply, moderate, or provide interactive features. Its broader capabilities include games, image/video and text transformations, character actions backed by Lua, PenguinMod project analysis, and a web panel. The graph also includes the Scratchblocks renderer and core runtime utilities. Some command and event wiring is not shown in the excerpts, so those connections are omitted rather than inferred.

Main entry points: [`src/util/lua.js`](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/lua.js) (Lua runtime), [`src/util/utility.js`](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/utility.js) (Command utilities), [`src/util/scratchblocks.js`](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/scratchblocks.js) (Scratchblocks utility), [`src/events/client/messageCreate.js`](https://github.com/penguinmod/penguinbot-public/blob/main/src/events/client/messageCreate.js) (Message events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_client["Discord client<br/>[index.js]"]
  node_events["Event handling<br/>[handleEvents.js]"]
  node_message_event["Message events<br/>[messageCreate.js]"]
  node_utility["Command utilities<br/>[utility.js]"]
  node_config["Server configuration<br/>[config.js]"]
  node_env["Environment settings<br/>[env-util.js]"]
  node_optiontype["Command option types<br/>[optiontype.js]"]
  node_multithread["Worker launcher<br/>[multi-thread.js]"]
  node_disabled_db[("Disabled interactions<br/>[utility.js]")]
end

subgraph group_commands["Discord features"]
  node_interactions["Commands and moderation"]
  node_games["Games and puzzles"]
  node_project_analysis["PenguinMod analysis"]
  node_web_panel["Web panel<br/>[webclient.js]"]
  node_panel_actions["Panel actions<br/>[server.js]"]
end

subgraph group_media["Media processing"]
  node_media_commands["Media commands"]
  node_media_base["Media processors<br/>[gifmodifier.js]"]
  node_gif_worker["GIF worker"]
end

subgraph group_characters["Character scripting"]
  node_characters["Character commands"]
  node_character_manager[("Character data")]
  node_lua["Lua runtime<br/>[lua.js]"]
  node_lua_worker["Lua worker<br/>[lua.worker.js]"]
  node_json_circular["Circular JSON<br/>[json-circular.js]"]
  node_lua_libs["Lua safe libraries"]
end

subgraph group_scratch["Scratchblocks rendering"]
  node_scratch_util["Scratchblocks utility<br/>[scratchblocks.js]"]
  node_scratch_syntax["Scratch syntax<br/>[syntax.js]"]
  node_scratch_syntax_blocks["Syntax blocks<br/>[blocks.js]"]
  node_scratch2_blocks["Scratch 2 blocks<br/>[blocks.js]"]
  node_scratch2_draw["Scratch 2 drawing<br/>[draw.js]"]
  node_scratch2_style["Scratch 2 styling<br/>[style.js]"]
  node_scratch3_blocks["Scratch 3 blocks<br/>[blocks.js]"]
  node_scratch3_draw["Scratch 3 drawing<br/>[draw.js]"]
  node_scratch3_style["Scratch 3 styling<br/>[style.js]"]
end

node_discord(("Discord users"))

node_discord -->|"sends events"| node_client
node_client -->|"registers handlers"| node_events
node_message_event -->|"checks commands"| node_utility
node_message_event -->|"reads settings"| node_config
node_message_event -.->|"sends responses"| node_discord
node_utility -->|"checks permissions"| node_config
node_utility -->|"reads settings"| node_env
node_utility -->|"checks disabled state"| node_disabled_db
node_discord -.->|"invokes commands"| node_interactions
node_discord -.->|"invokes games"| node_games
node_discord -.->|"invokes commands"| node_media_commands
node_discord -.->|"invokes actions"| node_characters
node_discord -.->|"requests analysis"| node_project_analysis
node_web_panel -->|"checks enabled state"| node_env
node_web_panel -->|"routes actions"| node_panel_actions
node_panel_actions -->|"reads channel settings"| node_config
node_panel_actions -->|"checks credentials"| node_env
node_media_commands -->|"uses processor"| node_media_base
node_media_base -->|"runs worker"| node_multithread
node_gif_worker -->|"loads command implementation"| node_media_commands
node_gif_worker -.->|"not connected"| node_scratch_util
node_characters -->|"uses character data"| node_character_manager
node_characters -->|"runs character scripts"| node_lua
node_character_manager -->|"builds Lua context"| node_lua
node_lua -->|"runs isolated code"| node_multithread
node_lua -->|"dispatches evaluation"| node_lua_worker
node_lua_worker -->|"evaluates code"| node_lua
node_lua_worker -->|"serializes results"| node_json_circular
node_lua -->|"configures libraries"| node_lua_libs
node_scratch_util -->|"parses syntax"| node_scratch_syntax
node_scratch_syntax -->|"uses block definitions"| node_scratch_syntax_blocks
node_scratch_util -.->|"loads renderer"| node_scratch2_blocks
node_scratch_util -.->|"loads renderer"| node_scratch3_blocks
node_scratch2_blocks -->|"uses drawing"| node_scratch2_draw
node_scratch2_blocks -->|"uses styling"| node_scratch2_style
node_scratch3_blocks -->|"uses drawing"| node_scratch3_draw
node_scratch3_blocks -->|"uses styling"| node_scratch3_style
node_optiontype -.->|"supports command options"| node_interactions

click node_client "https://github.com/penguinmod/penguinbot-public/blob/main/src/index.js"
click node_events "https://github.com/penguinmod/penguinbot-public/blob/main/src/handleEvents.js"
click node_message_event "https://github.com/penguinmod/penguinbot-public/blob/main/src/events/client/messageCreate.js"
click node_utility "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/utility.js"
click node_config "https://github.com/penguinmod/penguinbot-public/blob/main/src/config.js"
click node_env "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/env-util.js"
click node_interactions "https://github.com/penguinmod/penguinbot-public/tree/main/src/commands"
click node_games "https://github.com/penguinmod/penguinbot-public/tree/main/src/commands"
click node_project_analysis "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/penguinmod-analyze.js"
click node_web_panel "https://github.com/penguinmod/penguinbot-public/blob/main/src/events/client/webclient.js"
click node_panel_actions "https://github.com/penguinmod/penguinbot-public/blob/main/src/admin/server.js"
click node_media_commands "https://github.com/penguinmod/penguinbot-public/tree/main/src/commands"
click node_media_base "https://github.com/penguinmod/penguinbot-public/blob/main/src/basecommands/gifmodifier.js"
click node_gif_worker "https://github.com/penguinmod/penguinbot-public/blob/main/src/basecommands/gifmodifier.worker.js"
click node_characters "https://github.com/penguinmod/penguinbot-public/tree/main/src/commands/character"
click node_character_manager "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/character-manager.js"
click node_lua "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/lua.js"
click node_lua_worker "https://github.com/penguinmod/penguinbot-public/blob/main/src/resources/worker/lua.worker.js"
click node_json_circular "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/json-circular.js"
click node_lua_libs "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/lua-fengari-baselib.js"
click node_scratch_util "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/scratchblocks.js"
click node_scratch_syntax "https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/syntax/syntax.js"
click node_scratch_syntax_blocks "https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/syntax/blocks.js"
click node_scratch2_blocks "https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch2/blocks.js"
click node_scratch2_draw "https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch2/draw.js"
click node_scratch2_style "https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch2/style.js"
click node_scratch3_blocks "https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch3/blocks.js"
click node_scratch3_draw "https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch3/draw.js"
click node_scratch3_style "https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch3/style.js"
click node_optiontype "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/optiontype.js"
click node_multithread "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/multi-thread.js"
click node_disabled_db "https://github.com/penguinmod/penguinbot-public/blob/main/src/util/utility.js"

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_client,node_events,node_message_event,node_utility,node_config,node_env,node_optiontype,node_multithread,node_disabled_db,node_discord toneBlue
class node_interactions,node_games,node_project_analysis,node_web_panel,node_panel_actions toneAmber
class node_media_commands,node_media_base,node_gif_worker toneMint
class node_characters,node_character_manager,node_lua,node_lua_worker,node_json_circular,node_lua_libs toneRose
class node_scratch_util,node_scratch_syntax,node_scratch_syntax_blocks,node_scratch2_blocks,node_scratch2_draw,node_scratch2_style,node_scratch3_blocks,node_scratch3_draw,node_scratch3_style toneIndigo
```

## Components

### Bot runtime

- [Discord client](https://github.com/penguinmod/penguinbot-public/blob/main/src/index.js): `src/index.js`
- [Event handling](https://github.com/penguinmod/penguinbot-public/blob/main/src/handleEvents.js): `src/handleEvents.js`
- [Message events](https://github.com/penguinmod/penguinbot-public/blob/main/src/events/client/messageCreate.js): `src/events/client/messageCreate.js`
- [Command utilities](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/utility.js): `src/util/utility.js`
- [Server configuration](https://github.com/penguinmod/penguinbot-public/blob/main/src/config.js): `src/config.js`
- [Environment settings](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/env-util.js): `src/util/env-util.js`
- [Command option types](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/optiontype.js): `src/util/optiontype.js`
- [Worker launcher](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/multi-thread.js): `src/util/multi-thread.js`
- [Disabled interactions](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/utility.js): `src/util/utility.js`

### Discord features

- [Commands and moderation](https://github.com/penguinmod/penguinbot-public/tree/main/src/commands): `src/commands`
- [Games and puzzles](https://github.com/penguinmod/penguinbot-public/tree/main/src/commands): `src/commands`
- [PenguinMod analysis](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/penguinmod-analyze.js): `src/util/penguinmod-analyze.js`
- [Web panel](https://github.com/penguinmod/penguinbot-public/blob/main/src/events/client/webclient.js): `src/events/client/webclient.js`
- [Panel actions](https://github.com/penguinmod/penguinbot-public/blob/main/src/admin/server.js): `src/admin/server.js`

### Media processing

- [Media commands](https://github.com/penguinmod/penguinbot-public/tree/main/src/commands): `src/commands`
- [Media processors](https://github.com/penguinmod/penguinbot-public/blob/main/src/basecommands/gifmodifier.js): `src/basecommands/gifmodifier.js`
- [GIF worker](https://github.com/penguinmod/penguinbot-public/blob/main/src/basecommands/gifmodifier.worker.js): `src/basecommands/gifmodifier.worker.js`

### Character scripting

- [Character commands](https://github.com/penguinmod/penguinbot-public/tree/main/src/commands/character): `src/commands/character`
- [Character data](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/character-manager.js): `src/util/character-manager.js`
- [Lua runtime](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/lua.js): `src/util/lua.js`
- [Lua worker](https://github.com/penguinmod/penguinbot-public/blob/main/src/resources/worker/lua.worker.js): `src/resources/worker/lua.worker.js`
- [Circular JSON](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/json-circular.js): `src/util/json-circular.js`
- [Lua safe libraries](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/lua-fengari-baselib.js): `src/util/lua-fengari-baselib.js`

### Scratchblocks rendering

- [Scratchblocks utility](https://github.com/penguinmod/penguinbot-public/blob/main/src/util/scratchblocks.js): `src/util/scratchblocks.js`
- [Scratch syntax](https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/syntax/syntax.js): `src/modules/scratchblocks/syntax/syntax.js`
- [Syntax blocks](https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/syntax/blocks.js): `src/modules/scratchblocks/syntax/blocks.js`
- [Scratch 2 blocks](https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch2/blocks.js): `src/modules/scratchblocks/scratch2/blocks.js`
- [Scratch 2 drawing](https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch2/draw.js): `src/modules/scratchblocks/scratch2/draw.js`
- [Scratch 2 styling](https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch2/style.js): `src/modules/scratchblocks/scratch2/style.js`
- [Scratch 3 blocks](https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch3/blocks.js): `src/modules/scratchblocks/scratch3/blocks.js`
- [Scratch 3 drawing](https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch3/draw.js): `src/modules/scratchblocks/scratch3/draw.js`
- [Scratch 3 styling](https://github.com/penguinmod/penguinbot-public/blob/main/src/modules/scratchblocks/scratch3/style.js): `src/modules/scratchblocks/scratch3/style.js`

### Other components

- **Discord users**

## Connections

- Discord users → Discord client: sends events
- Discord client → Event handling: registers handlers (evidence: `src/index.js`)
- Message events → Command utilities: checks commands (evidence: `src/events/client/messageCreate.js`)
- Message events → Server configuration: reads settings (evidence: `src/events/client/messageCreate.js`)
- Message events → Discord users: sends responses
- Command utilities → Server configuration: checks permissions (evidence: `src/util/utility.js`)
- Command utilities → Environment settings: reads settings (evidence: `src/util/utility.js`)
- Command utilities → Disabled interactions: checks disabled state (evidence: `src/util/utility.js`)
- Discord users → Commands and moderation: invokes commands
- Discord users → Games and puzzles: invokes games
- Discord users → Media commands: invokes commands
- Discord users → Character commands: invokes actions
- Discord users → PenguinMod analysis: requests analysis
- Web panel → Environment settings: checks enabled state (evidence: `src/events/client/webclient.js`)
- Web panel → Panel actions: routes actions (evidence: `src/events/client/webclient.js`)
- Panel actions → Server configuration: reads channel settings (evidence: `src/admin/server.js`)
- Panel actions → Environment settings: checks credentials (evidence: `src/admin/server.js`)
- Media commands → Media processors: uses processor (evidence: `src/commands/gifmodifier/winner.js`)
- Media processors → Worker launcher: runs worker (evidence: `src/basecommands/gifmodifier.js`)
- GIF worker → Media commands: loads command implementation (evidence: `src/basecommands/gifmodifier.worker.js`)
- GIF worker → Scratchblocks utility: not connected
- Character commands → Character data: uses character data (evidence: `src/commands/character/characteredit.js`)
- Character commands → Lua runtime: runs character scripts (evidence: `src/commands/character/characteredit.js`)
- Character data → Lua runtime: builds Lua context (evidence: `src/util/character-manager.js`)
- Lua runtime → Worker launcher: runs isolated code (evidence: `src/util/lua.js`)
- Lua runtime → Lua worker: dispatches evaluation (evidence: `src/util/lua.js`)
- Lua worker → Lua runtime: evaluates code (evidence: `src/resources/worker/lua.worker.js`)
- Lua worker → Circular JSON: serializes results (evidence: `src/resources/worker/lua.worker.js`)
- Lua runtime → Lua safe libraries: configures libraries (evidence: `src/util/lua.js`)
- Scratchblocks utility → Scratch syntax: parses syntax
- Scratch syntax → Syntax blocks: uses block definitions (evidence: `src/modules/scratchblocks/syntax/index.js`)
- Scratchblocks utility → Scratch 2 blocks: loads renderer
- Scratchblocks utility → Scratch 3 blocks: loads renderer
- Scratch 2 blocks → Scratch 2 drawing: uses drawing (evidence: `src/modules/scratchblocks/scratch2/blocks.js`)
- Scratch 2 blocks → Scratch 2 styling: uses styling (evidence: `src/modules/scratchblocks/scratch2/blocks.js`)
- Scratch 3 blocks → Scratch 3 drawing: uses drawing (evidence: `src/modules/scratchblocks/scratch3/index.js`)
- Scratch 3 blocks → Scratch 3 styling: uses styling (evidence: `src/modules/scratchblocks/scratch3/index.js`)
- Command option types → Commands and moderation: supports command options (evidence: `src/commands/ship.js`)
