# khpofdfdgf/guardbot architecture

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

- Interactive diagram: https://gitdiagram.com/khpofdfdgf/guardbot
- Repository: https://github.com/khpofdfdgf/guardbot

## Overview

GuardBot is a Discord server moderation bot with a companion staff dashboard. Members and staff interact through Discord commands and message events; moderation features apply rules and actions, while warning and case records support follow-up. A FastAPI web application adds OAuth login, dashboard/API routes, live connections, and an admin terminal. The README documents appeals, rules, automated moderation, and staff controls; some cog implementations were not excerpted, so their internal links are omitted. Edges cite excerpts, the source index, or README statements that support the relationship.

Main entry points: [`web/main.py`](https://github.com/khpofdfdgf/guardbot/blob/main/web/main.py) (Web App), [`config.py`](https://github.com/khpofdfdgf/guardbot/blob/main/config.py) (Runtime Config), [`bot.py`](https://github.com/khpofdfdgf/guardbot/blob/main/bot.py) (Bot Runtime), [`cogs/automod.py`](https://github.com/khpofdfdgf/guardbot/blob/main/cogs/automod.py) (Auto Moderation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord["Discord Bot"]
  node_bot["Bot Runtime<br/>[bot.py]"]
end

subgraph group_moderation["Moderation Features"]
  node_automod["Auto Moderation<br/>[automod.py]"]
  node_ai_check["AI Checks"]
  node_mod_commands["Staff Commands<br/>[moderation.py]"]
  node_appeals["Appeals<br/>[appeals.py]"]
  node_rules["Server Rules<br/>[rules.py]"]
  node_event_logs["Event Logging<br/>[logging_events.py]"]
  node_safe_mode["Safe Mode<br/>[safemode.py]"]
  node_config_commands["Config Commands<br/>[config_cmd.py]"]
end

subgraph group_web["Web Dashboard"]
  node_web_app["Web App<br/>[main.py]"]
  node_oauth["OAuth Login<br/>[auth.py]"]
  node_web_api["Dashboard API<br/>[api.py]"]
  node_web_views["Dashboard Pages"]
  node_live_socket["Live WebSocket<br/>[websockets.py]"]
  node_web_terminal["Admin Terminal<br/>[terminal.py]"]
end

subgraph group_state["Configuration And State"]
  node_config["Runtime Config<br/>[config.py]"]
  node_records[("Warnings And Cases<br/>[utils.py]")]
  node_backups[("Server Backups")]
end

node_members(("Members"))
node_staff(("Staff"))
node_discord_service(("Discord"))
node_shell["ShellInABox"]

node_bot -->|"connects to"| node_discord_service
node_bot -->|"starts alongside"| node_web_app
node_web_app -->|"includes router"| node_oauth
node_web_app -->|"includes router"| node_web_api
node_web_app -->|"includes router"| node_live_socket
node_web_app -->|"includes router"| node_web_terminal
node_web_app -->|"renders"| node_web_views
node_oauth -->|"requests profile"| node_discord_service
node_oauth -->|"stores profile"| node_web_app
node_web_terminal -->|"controls process"| node_shell
node_staff -->|"runs commands"| node_mod_commands
node_members -->|"submits appeal"| node_appeals
node_members -->|"requests rules"| node_rules
node_bot -.->|"loads cog"| node_automod
node_automod -->|"checks messages"| node_ai_check
node_mod_commands -->|"records actions"| node_records
node_config_commands -->|"updates settings"| node_config
node_automod -->|"reads rules"| node_config
node_mod_commands -->|"reads settings"| node_config
node_event_logs -->|"reads settings"| node_config
node_rules -->|"reads settings"| node_config
node_safe_mode -->|"reads settings"| node_config
node_safe_mode -->|"restores snapshots"| node_backups

click node_bot "https://github.com/khpofdfdgf/guardbot/blob/main/bot.py"
click node_automod "https://github.com/khpofdfdgf/guardbot/blob/main/cogs/automod.py"
click node_ai_check "https://github.com/khpofdfdgf/guardbot/blob/main/AI_Logic_moderation.py"
click node_mod_commands "https://github.com/khpofdfdgf/guardbot/blob/main/cogs/moderation.py"
click node_appeals "https://github.com/khpofdfdgf/guardbot/blob/main/cogs/appeals.py"
click node_rules "https://github.com/khpofdfdgf/guardbot/blob/main/cogs/rules.py"
click node_event_logs "https://github.com/khpofdfdgf/guardbot/blob/main/cogs/logging_events.py"
click node_safe_mode "https://github.com/khpofdfdgf/guardbot/blob/main/cogs/safemode.py"
click node_config_commands "https://github.com/khpofdfdgf/guardbot/blob/main/cogs/config_cmd.py"
click node_config "https://github.com/khpofdfdgf/guardbot/blob/main/config.py"
click node_records "https://github.com/khpofdfdgf/guardbot/blob/main/utils.py"
click node_backups "https://github.com/khpofdfdgf/guardbot/tree/main/backups"
click node_web_app "https://github.com/khpofdfdgf/guardbot/blob/main/web/main.py"
click node_oauth "https://github.com/khpofdfdgf/guardbot/blob/main/web/auth.py"
click node_web_api "https://github.com/khpofdfdgf/guardbot/blob/main/web/api.py"
click node_web_views "https://github.com/khpofdfdgf/guardbot/tree/main/web/templates"
click node_live_socket "https://github.com/khpofdfdgf/guardbot/blob/main/web/websockets.py"
click node_web_terminal "https://github.com/khpofdfdgf/guardbot/blob/main/web/terminal.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 toneBlue
class node_automod,node_ai_check,node_mod_commands,node_appeals,node_rules,node_event_logs,node_safe_mode,node_config_commands toneAmber
class node_web_app,node_oauth,node_web_api,node_web_views,node_live_socket,node_web_terminal toneMint
class node_config,node_records,node_backups toneRose
class node_members,node_staff,node_discord_service,node_shell toneIndigo
```

## Components

### Discord Bot

- [Bot Runtime](https://github.com/khpofdfdgf/guardbot/blob/main/bot.py): `bot.py`

### Moderation Features

- [Auto Moderation](https://github.com/khpofdfdgf/guardbot/blob/main/cogs/automod.py): `cogs/automod.py`
- [AI Checks](https://github.com/khpofdfdgf/guardbot/blob/main/AI_Logic_moderation.py): `AI_Logic_moderation.py`
- [Staff Commands](https://github.com/khpofdfdgf/guardbot/blob/main/cogs/moderation.py): `cogs/moderation.py`
- [Appeals](https://github.com/khpofdfdgf/guardbot/blob/main/cogs/appeals.py): `cogs/appeals.py`
- [Server Rules](https://github.com/khpofdfdgf/guardbot/blob/main/cogs/rules.py): `cogs/rules.py`
- [Event Logging](https://github.com/khpofdfdgf/guardbot/blob/main/cogs/logging_events.py): `cogs/logging_events.py`
- [Safe Mode](https://github.com/khpofdfdgf/guardbot/blob/main/cogs/safemode.py): `cogs/safemode.py`
- [Config Commands](https://github.com/khpofdfdgf/guardbot/blob/main/cogs/config_cmd.py): `cogs/config_cmd.py`

### Web Dashboard

- [Web App](https://github.com/khpofdfdgf/guardbot/blob/main/web/main.py): `web/main.py`
- [OAuth Login](https://github.com/khpofdfdgf/guardbot/blob/main/web/auth.py): `web/auth.py`
- [Dashboard API](https://github.com/khpofdfdgf/guardbot/blob/main/web/api.py): `web/api.py`
- [Dashboard Pages](https://github.com/khpofdfdgf/guardbot/tree/main/web/templates): `web/templates`
- [Live WebSocket](https://github.com/khpofdfdgf/guardbot/blob/main/web/websockets.py): `web/websockets.py`
- [Admin Terminal](https://github.com/khpofdfdgf/guardbot/blob/main/web/terminal.py): `web/terminal.py`

### Configuration And State

- [Runtime Config](https://github.com/khpofdfdgf/guardbot/blob/main/config.py): `config.py`
- [Warnings And Cases](https://github.com/khpofdfdgf/guardbot/blob/main/utils.py): `utils.py`
- [Server Backups](https://github.com/khpofdfdgf/guardbot/tree/main/backups): `backups`

### Other components

- **Members**
- **Staff**
- **Discord**
- **ShellInABox**

## Connections

- Bot Runtime → Discord: connects to (evidence: `README.md`)
- Bot Runtime → Web App: starts alongside (evidence: `bot.py`)
- Web App → OAuth Login: includes router (evidence: `web/main.py`)
- Web App → Dashboard API: includes router (evidence: `web/main.py`)
- Web App → Live WebSocket: includes router (evidence: `web/main.py`)
- Web App → Admin Terminal: includes router (evidence: `web/main.py`)
- Web App → Dashboard Pages: renders (evidence: `web/main.py`)
- OAuth Login → Discord: requests profile (evidence: `web/auth.py`)
- OAuth Login → Web App: stores profile (evidence: `web/auth.py`)
- Admin Terminal → ShellInABox: controls process (evidence: `web/terminal.py`)
- Staff → Staff Commands: runs commands (evidence: `README.md`)
- Members → Appeals: submits appeal (evidence: `README.md`)
- Members → Server Rules: requests rules (evidence: `README.md`)
- Bot Runtime → Auto Moderation: loads cog
- Auto Moderation → AI Checks: checks messages (evidence: `cogs/automod.py`)
- Staff Commands → Warnings And Cases: records actions (evidence: `cogs/moderation.py`)
- Config Commands → Runtime Config: updates settings (evidence: `cogs/config_cmd.py`)
- Auto Moderation → Runtime Config: reads rules (evidence: `cogs/automod.py`)
- Staff Commands → Runtime Config: reads settings (evidence: `cogs/moderation.py`)
- Event Logging → Runtime Config: reads settings (evidence: `cogs/logging_events.py`)
- Server Rules → Runtime Config: reads settings (evidence: `cogs/rules.py`)
- Safe Mode → Runtime Config: reads settings (evidence: `cogs/safemode.py`)
- Safe Mode → Server Backups: restores snapshots (evidence: `cogs/safemode.py`)
