# shifosan/silk-discord-bot architecture

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

- Interactive diagram: https://gitdiagram.com/shifosan/silk-discord-bot
- Repository: https://github.com/shifosan/silk-discord-bot

## Overview

SILK is a Discord community bot with AI chat and lookup, moderation and server utilities, XP/level progression, logging, and a web dashboard. The main user workflow is a Discord message or command reaching a bot cog, which may consult an AI service or persisted guild/user state before responding through Discord. Leveling is a distinct progression stage: events update XP, core logic evaluates levels and rewards, and database helpers persist or rank users. Dashboard.js and dashboard.py indicate a separate browser-to-API configuration workflow. The README is only a title; unsampled cog and dashboard internals limit confidence in their wiring.

Main entry points: [`main.py`](https://github.com/shifosan/silk-discord-bot/blob/main/main.py) (Bot and extension loader), [`cogs/aotr_gpt.py`](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/aotr_gpt.py) (AoTR lookup), [`cogs/chat.py`](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/chat.py) (AI chat), [`cogs/level_system/core.py`](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/core.py) (XP event handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_bot["Bot and extension loader<br/>[main.py]"]
end

subgraph group_ai["AI Features"]
  node_chat["AI chat<br/>[chat.py]"]
  node_dm["DM chat<br/>[dm_chat.py]"]
  node_aotr["AoTR lookup<br/>[aotr_gpt.py]"]
  node_creative["Creative tools<br/>[creative.py]"]
end

subgraph group_community["Community Operations"]
  node_moderation["Moderation<br/>[moderation.py]"]
  node_server_logs["Server event logs<br/>[logger.py]"]
  node_event_formats["Log formatting<br/>[channels.py]"]
  node_prefix["Prefix configuration<br/>[prefix_handler.py]"]
  node_starboard["Starboard<br/>[starboard.py]"]
end

subgraph group_progression["Level Progression"]
  node_level_events["XP event handling<br/>[core.py]"]
  node_level_commands["Level commands<br/>[commands.py]"]
  node_level_config["Level configuration<br/>[main_menu.py]"]
  node_level_db["Level data access<br/>[database.py]"]
end

subgraph group_dashboard["Web Dashboard"]
  node_dashboard_ui["Dashboard interface<br/>[dashboard.js]"]
  node_dashboard_api["Dashboard API<br/>[dashboard.py]"]
end

node_member(("Discord member"))
node_discord(("Discord platform"))
node_gemini(("Gemini API"))
node_mongo[("MongoDB")]
node_browser(("Dashboard user"))

node_bot -->|"loads extension"| node_chat
node_bot -->|"loads extension"| node_dm
node_bot -->|"loads extension"| node_aotr
node_bot -->|"loads extension"| node_creative
node_bot -->|"loads extension"| node_moderation
node_bot -->|"loads extension"| node_server_logs
node_bot -->|"loads extension"| node_prefix
node_bot -->|"loads extension"| node_starboard
node_bot -->|"loads extension"| node_level_events
node_bot -->|"loads extension"| node_level_commands
node_bot -->|"loads extension"| node_level_config
node_member -->|"sends message"| node_discord
node_discord -->|"delivers events"| node_chat
node_discord -->|"delivers DM"| node_dm
node_discord -->|"delivers query"| node_aotr
node_discord -->|"delivers commands"| node_moderation
node_discord -->|"delivers events"| node_level_events
node_discord -->|"delivers commands"| node_level_commands
node_discord -->|"delivers interactions"| node_level_config
node_chat -.->|"generates replies"| node_gemini
node_aotr -.->|"embeds and generates"| node_gemini
node_aotr -->|"vector searches"| node_mongo
node_prefix -->|"reads and writes config"| node_mongo
node_level_events -->|"reads and updates XP"| node_level_db
node_level_commands -->|"reads rankings"| node_level_db
node_level_config -->|"reads configuration"| node_level_db
node_server_logs -->|"formats events"| node_event_formats
node_browser -->|"uses dashboard"| node_dashboard_ui
node_dashboard_ui -->|"calls API"| node_dashboard_api
node_dashboard_api -->|"reads and writes"| node_mongo
node_chat -->|"sends replies"| node_discord
node_aotr -->|"sends answers"| node_discord
node_level_events -->|"announces level-ups"| node_discord

click node_bot "https://github.com/shifosan/silk-discord-bot/blob/main/main.py"
click node_chat "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/chat.py"
click node_dm "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/dm_chat.py"
click node_aotr "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/aotr_gpt.py"
click node_creative "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/creative.py"
click node_moderation "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/moderation.py"
click node_server_logs "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/logger.py"
click node_event_formats "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/logs/channels.py"
click node_prefix "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/prefix_handler.py"
click node_starboard "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/starboard.py"
click node_level_events "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/core.py"
click node_level_commands "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/commands.py"
click node_level_config "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/bot_config/main_menu.py"
click node_level_db "https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/database.py"
click node_dashboard_ui "https://github.com/shifosan/silk-discord-bot/blob/main/static/js/dashboard.js"
click node_dashboard_api "https://github.com/shifosan/silk-discord-bot/blob/main/dashboard.py"

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_bot,node_browser toneBlue
class node_chat,node_dm,node_aotr,node_creative,node_mongo toneAmber
class node_moderation,node_server_logs,node_event_formats,node_prefix,node_starboard,node_gemini toneMint
class node_level_events,node_level_commands,node_level_config,node_level_db toneRose
class node_dashboard_ui,node_dashboard_api,node_member,node_discord toneIndigo
```

## Components

### Bot Runtime

- [Bot and extension loader](https://github.com/shifosan/silk-discord-bot/blob/main/main.py): `main.py`

### AI Features

- [AI chat](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/chat.py): `cogs/chat.py`
- [DM chat](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/dm_chat.py): `cogs/dm_chat.py`
- [AoTR lookup](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/aotr_gpt.py): `cogs/aotr_gpt.py`
- [Creative tools](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/creative.py): `cogs/creative.py`

### Community Operations

- [Moderation](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/moderation.py): `cogs/moderation.py`
- [Server event logs](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/logger.py): `cogs/logger.py`
- [Log formatting](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/logs/channels.py): `cogs/logs/channels.py`
- [Prefix configuration](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/prefix_handler.py): `cogs/prefix_handler.py`
- [Starboard](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/starboard.py): `cogs/starboard.py`

### Level Progression

- [XP event handling](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/core.py): `cogs/level_system/core.py`
- [Level commands](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/commands.py): `cogs/level_system/commands.py`
- [Level configuration](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/bot_config/main_menu.py): `cogs/level_system/bot_config/main_menu.py`
- [Level data access](https://github.com/shifosan/silk-discord-bot/blob/main/cogs/level_system/database.py): `cogs/level_system/database.py`

### Web Dashboard

- [Dashboard interface](https://github.com/shifosan/silk-discord-bot/blob/main/static/js/dashboard.js): `static/js/dashboard.js`
- [Dashboard API](https://github.com/shifosan/silk-discord-bot/blob/main/dashboard.py): `dashboard.py`

### Other components

- **Discord member**
- **Discord platform**
- **Gemini API**
- **MongoDB**
- **Dashboard user**

## Connections

- Bot and extension loader → AI chat: loads extension
- Bot and extension loader → DM chat: loads extension
- Bot and extension loader → AoTR lookup: loads extension
- Bot and extension loader → Creative tools: loads extension
- Bot and extension loader → Moderation: loads extension
- Bot and extension loader → Server event logs: loads extension
- Bot and extension loader → Prefix configuration: loads extension
- Bot and extension loader → Starboard: loads extension
- Bot and extension loader → XP event handling: loads extension
- Bot and extension loader → Level commands: loads extension
- Bot and extension loader → Level configuration: loads extension
- Discord member → Discord platform: sends message
- Discord platform → AI chat: delivers events
- Discord platform → DM chat: delivers DM
- Discord platform → AoTR lookup: delivers query
- Discord platform → Moderation: delivers commands
- Discord platform → XP event handling: delivers events
- Discord platform → Level commands: delivers commands
- Discord platform → Level configuration: delivers interactions
- AI chat → Gemini API: generates replies
- AoTR lookup → Gemini API: embeds and generates
- AoTR lookup → MongoDB: vector searches
- Prefix configuration → MongoDB: reads and writes config
- XP event handling → Level data access: reads and updates XP
- Level commands → Level data access: reads rankings
- Level configuration → Level data access: reads configuration
- Server event logs → Log formatting: formats events
- Dashboard user → Dashboard interface: uses dashboard
- Dashboard interface → Dashboard API: calls API
- Dashboard API → MongoDB: reads and writes
- AI chat → Discord platform: sends replies
- AoTR lookup → Discord platform: sends answers
- XP event handling → Discord platform: announces level-ups