# dev-sahad/minnal-bot architecture

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

- Interactive diagram: https://gitdiagram.com/dev-sahad/minnal-bot
- Repository: https://github.com/dev-sahad/minnal-bot

## Overview

1. **System shape**
   - This repo is a **Discord bot monorepo** with a Python runtime at the center, plus a small **web control plane** and a set of **TypeScript packages/artifacts** that support APIs, generated clients, and UI tooling.
   - The main runtime is the Discord bot; the web and TS pieces are adjacent subsystems rather than the primary execution path.

2. **Bot entrypoint and runtime boundary**
   - `discord_bot.py` is the primary startup file for the bot.
   - `config.py`, `config_manager.py`, and `logger.py` provide configuration, persistence helpers, and logging around the bot process.
   - `start.py` and `webhook_server.py` appear to be supporting launch/hosting entrypoints or auxiliary servers.

3. **Feature decomposition via cogs**
   - The bot is organized into `cogs/*.py`, with each file owning a domain:
     - administration and moderation: `admin.py`, `bot_control.py`, `checks.py`, `sentinel.py`, `watchlist.py`
     - community automation: `welcome.py`, `autorole.py`, `verify.py`, `tickets.py`, `giveaways.py`, `ghostping.py`
     - engagement systems: `economy.py`, `levels.py`, `stats.py`, `fun.py`, `memes.py`, `rizz_engine.py`, `anime.py`
     - utility/info: `utilities.py`, `info.py`, `help.py`, `dashboard.py`
     - media/voice: `music.py`, `voice_features.py`, `voice_manager.py`
     - integrations: `web_bridge.py`, `ai_chat.py`, `codepilot.py`, `omni_status.py`
   - This is the main functional boundary: each cog encapsulates a command or event-driven subsystem.

4. **Data and state persistence**
   - Runtime state is file-backed in `data/*.json`, including `economy.json`, `reaction_roles.json`, `birthdays.json`, `web_config.json`, `bot_stats.json`, and `settings.json`.
   - The design is lightweight and local-first: the bot persists operational state to JSON rather than a separate database service in the main Python path.
   - This means architecture diagrams should show a **bot process reading/writing local files**, not a remote datastore, for core features.

5. **Assets and media**
   - `audio/` contains local media assets used by the bot, likely for music/voice or sound-trigger features.
   - `assets/` is a general static asset bucket.
   - These are part of the bot’s runtime environment and should be shown as local dependencies, not external services.

6. **Web bridge and remote control path**
   - The repo includes a dedicated **bot-to-web control bridge**: `cogs/web_bridge.py`, `webhook_server.py`, and documentation like `WEB_BRIDGE_GUIDE.md`.
   - The README indicates a token/link flow between Discord and a web panel: a Discord command produces a server token, which is then used by the browser panel to connect to the bot.
   - Architecturally, this is a separate control channel from Discord chat commands: **browser UI -> bridge/auth token -> bot state/actions**.

7. **Static admin panels**
   - `admin-panel.html`, `advanced-admin-panel.html`, `config-editor.html`, and related HTML docs are standalone web UIs.
   - These are meant to be deployed separately as static pages and used to manage bot settings, connection state, and administrative actions.
   - They are not the bot itself; they are the operator-facing front end for the web bridge.

8. **TypeScript API server artifact**
   - `artifacts/api-server/` is a small TypeScript server with `src/app.ts`, `src/index.ts`, and routes like `health.ts` and `railway.ts`.
   - It looks like a lightweight service boundary for deployment/health checks and platform integration, with built output under `dist/`.
   - In a diagram, treat it as a **companion HTTP service** rather than the bot’s core logic.

9. **Shared API contracts and generated clients**
   - `lib/api-spec/openapi.yaml` is the contract source for API generation.
   - `lib/api-client-react` and `lib/api-zod` contain generated clients/schemas, suggesting a contract-first workflow for browser-side/API integration and runtime validation.
   - These packages are the shared boundary between the TypeScript UI/server world and any API surface exposed by the bot ecosystem.

10. **Database/schema package**
   - `lib/db` contains a shared schema package built with Drizzle tooling (`drizzle.config.ts`, `src/schema`).
   - Even if the main bot uses JSON files, this package indicates a separate schema layer for structured data and likely supports the TS side of the repo.
   - For architecture, treat it as a **shared data model package** used by the API/UI tooling.

11. **Frontend tooling and sandboxes**
   - `artifacts/bot-logs` and `artifacts/mockup-sandbox` are Vite-based React apps with many shared UI components.
   - `mockup-sandbox` includes a custom preview plugin and generated mockup component definitions, which suggests a design/prototyping environment.
   - `bot-logs` likely provides a UI for viewing operational logs or bot telemetry.
   - These are separate frontend artifacts, not required for bot execution, but important for operator experience.

12. **Operational and deployment boundaries**
   - `Dockerfile`, `Procfile`, `requirements.txt`, `package.json`, `pnpm-workspace.yaml`, and `tsconfig*` show a repo that supports both Python and Node-based builds.
   - The README also emphasizes Replit/PythonAnywhere/Railway-style deployment, so the architecture is designed for hosted bot execution plus optional web hosting.
   - `tests/` is minimal, so the main reliability boundary is operational rather than deeply unit-tested code.

13. **External dependencies and integration points**
   - The bot’s main external system is **Discord**: slash commands, guild events, voice, moderation, and admin workflows all run through the Discord API.
   - Secondary external surfaces are a static web host for admin panels and any webhook/HTTP endpoints used for bridging or health checks.
   - The repo’s architecture is therefore a **Discord-centric event system with a sidecar web admin channel** and supporting generated API/tooling packages.

Main entry points: [`discord_bot.py`](https://github.com/dev-sahad/minnal-bot/blob/main/discord_bot.py) (Bot entry), [`data/settings.json`](https://github.com/dev-sahad/minnal-bot/blob/main/data/settings.json) (JSON state), [`cogs/web_bridge.py`](https://github.com/dev-sahad/minnal-bot/blob/main/cogs/web_bridge.py) (Integration cogs), [`artifacts/api-server/src/index.ts`](https://github.com/dev-sahad/minnal-bot/blob/main/artifacts/api-server/src/index.ts) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_bot["Python bot runtime"]
  node_discord_bot(("Bot entry<br/>python runtime<br/>[discord_bot.py]"))
  node_config_py["Config<br/>[config.py]"]
  node_config_manager_py["State mgr<br/>python persistence<br/>[config_manager.py]"]
  node_logger_py["Logger<br/>python logging<br/>[logger.py]"]
  node_cogs_core["Admin cogs<br/>discord cogs<br/>[admin.py]"]
  node_cogs_community["Community cogs<br/>discord cogs<br/>[welcome.py]"]
  node_cogs_engagement["Engagement cogs<br/>discord cogs<br/>[economy.py]"]
  node_cogs_voice["Media cogs<br/>discord cogs<br/>[music.py]"]
  node_cogs_integrations["Integration cogs<br/>discord cogs<br/>[web_bridge.py]"]
end

subgraph group_web_control["Web control plane"]
  node_webhook_server_py["Webhook server<br/>python http bridge<br/>[webhook_server.py]"]
  node_admin_panel_html["Admin panel<br/>static UI<br/>[admin-panel.html]"]
  node_config_editor_html["Config editor<br/>static UI<br/>[config-editor.html]"]
  node_webhook_panel_html["Webhook panel<br/>static UI"]
end

subgraph group_ts_tooling["TypeScript tooling"]
  node_api_spec["API spec<br/>openapi contract<br/>[openapi.yaml]"]
  node_api_client["API client<br/>generated TS client<br/>[index.ts]"]
  node_api_zod["Zod schemas<br/>generated TS schemas<br/>[index.ts]"]
  node_db_schema["DB schema<br/>shared schema<br/>[index.ts]"]
  node_api_server(("API server<br/>ts service<br/>[index.ts]"))
end

subgraph group_artifacts_frontend["Frontend artifacts"]
  node_bot_logs["Bot logs<br/>react app<br/>[App.tsx]"]
  node_mockup_sandbox["Mockup sandbox<br/>react app<br/>[App.tsx]"]
end

subgraph group_runtime_state["Local state and assets"]
  node_data_files[("JSON state<br/>file-backed state<br/>[settings.json]")]
  node_assets_bundle["Assets<br/>[shunsui.mp3]"]
end

node_discord_bot -->|"loads config"| node_config_py
node_discord_bot -->|"persists state"| node_config_manager_py
node_discord_bot -->|"emits logs"| node_logger_py
node_discord_bot -->|"loads"| node_cogs_core
node_discord_bot -->|"loads"| node_cogs_community
node_discord_bot -->|"loads"| node_cogs_engagement
node_discord_bot -->|"loads"| node_cogs_voice
node_discord_bot -->|"loads"| node_cogs_integrations
node_cogs_core -->|"reads/writes"| node_data_files
node_cogs_community -->|"reads/writes"| node_data_files
node_cogs_engagement -->|"reads/writes"| node_data_files
node_cogs_integrations -->|"reads/writes"| node_data_files
node_cogs_voice -->|"uses media"| node_assets_bundle
node_cogs_integrations -->|"bridges"| node_webhook_server_py
node_webhook_server_py -->|"serves/control"| node_webhook_panel_html
node_webhook_panel_html -->|"controls"| node_discord_bot
node_admin_panel_html -->|"administers"| node_discord_bot
node_config_editor_html -->|"edits config"| node_discord_bot
node_api_server -->|"implements"| node_api_spec
node_api_client -->|"generated from"| node_api_spec
node_api_zod -->|"generated from"| node_api_spec
node_db_schema -->|"supports"| node_api_server
node_bot_logs -->|"consumes"| node_api_server
node_mockup_sandbox -->|"uses"| node_api_client
node_mockup_sandbox -->|"validates"| node_api_zod

click node_discord_bot "https://github.com/dev-sahad/minnal-bot/blob/main/discord_bot.py"
click node_config_py "https://github.com/dev-sahad/minnal-bot/blob/main/config.py"
click node_config_manager_py "https://github.com/dev-sahad/minnal-bot/blob/main/config_manager.py"
click node_logger_py "https://github.com/dev-sahad/minnal-bot/blob/main/logger.py"
click node_cogs_core "https://github.com/dev-sahad/minnal-bot/blob/main/cogs/admin.py"
click node_cogs_community "https://github.com/dev-sahad/minnal-bot/blob/main/cogs/welcome.py"
click node_cogs_engagement "https://github.com/dev-sahad/minnal-bot/blob/main/cogs/economy.py"
click node_cogs_voice "https://github.com/dev-sahad/minnal-bot/blob/main/cogs/music.py"
click node_cogs_integrations "https://github.com/dev-sahad/minnal-bot/blob/main/cogs/web_bridge.py"
click node_data_files "https://github.com/dev-sahad/minnal-bot/blob/main/data/settings.json"
click node_assets_bundle "https://github.com/dev-sahad/minnal-bot/blob/main/audio/shunsui.mp3"
click node_webhook_server_py "https://github.com/dev-sahad/minnal-bot/blob/main/webhook_server.py"
click node_admin_panel_html "https://github.com/dev-sahad/minnal-bot/blob/main/admin-panel.html"
click node_config_editor_html "https://github.com/dev-sahad/minnal-bot/blob/main/config-editor.html"
click node_webhook_panel_html "https://github.com/dev-sahad/minnal-bot/blob/main/webhook_panel_integration.html"
click node_api_spec "https://github.com/dev-sahad/minnal-bot/blob/main/lib/api-spec/openapi.yaml"
click node_api_client "https://github.com/dev-sahad/minnal-bot/blob/main/lib/api-client-react/src/index.ts"
click node_api_zod "https://github.com/dev-sahad/minnal-bot/blob/main/lib/api-zod/src/index.ts"
click node_db_schema "https://github.com/dev-sahad/minnal-bot/blob/main/lib/db/src/index.ts"
click node_api_server "https://github.com/dev-sahad/minnal-bot/blob/main/artifacts/api-server/src/index.ts"
click node_bot_logs "https://github.com/dev-sahad/minnal-bot/blob/main/artifacts/bot-logs/src/App.tsx"
click node_mockup_sandbox "https://github.com/dev-sahad/minnal-bot/blob/main/artifacts/mockup-sandbox/src/App.tsx"

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_discord_bot,node_config_py,node_config_manager_py,node_logger_py,node_cogs_core,node_cogs_community,node_cogs_engagement,node_cogs_voice,node_cogs_integrations toneBlue
class node_webhook_server_py,node_admin_panel_html,node_config_editor_html,node_webhook_panel_html toneAmber
class node_api_spec,node_api_client,node_api_zod,node_db_schema,node_api_server toneMint
class node_bot_logs,node_mockup_sandbox toneRose
class node_data_files,node_assets_bundle toneIndigo
```

## Components

### Python bot runtime

Discord bot process and its cog-based feature modules.

- [Bot entry](https://github.com/dev-sahad/minnal-bot/blob/main/discord_bot.py): python runtime · Main Discord bot startup and runtime coordinator. · `discord_bot.py`
- [Config](https://github.com/dev-sahad/minnal-bot/blob/main/config.py): python config · Process configuration and environment wiring. · `config.py`
- [State mgr](https://github.com/dev-sahad/minnal-bot/blob/main/config_manager.py): python persistence · Helpers for loading and saving bot-local state. · `config_manager.py`
- [Logger](https://github.com/dev-sahad/minnal-bot/blob/main/logger.py): python logging · Shared logging setup for the bot process. · `logger.py`
- [Admin cogs](https://github.com/dev-sahad/minnal-bot/blob/main/cogs/admin.py): discord cogs · Administration, moderation, and control subsystems. · `cogs/admin.py`
- [Community cogs](https://github.com/dev-sahad/minnal-bot/blob/main/cogs/welcome.py): discord cogs · Welcome, roles, verification, tickets, and giveaways. · `cogs/welcome.py`
- [Engagement cogs](https://github.com/dev-sahad/minnal-bot/blob/main/cogs/economy.py): discord cogs · Economy, levels, stats, fun, memes, anime, and rizz. · `cogs/economy.py`
- [Media cogs](https://github.com/dev-sahad/minnal-bot/blob/main/cogs/music.py): discord cogs · Music, voice features, and voice session management. · `cogs/music.py`
- [Integration cogs](https://github.com/dev-sahad/minnal-bot/blob/main/cogs/web_bridge.py): discord cogs · AI, code, status, dashboard, and web bridge integrations. · `cogs/web_bridge.py`

### Web control plane

Static admin UIs and the bot/web bridge for remote operator actions.

- [Webhook server](https://github.com/dev-sahad/minnal-bot/blob/main/webhook_server.py): python http bridge · Auxiliary HTTP server for bridge or webhook handling. · `webhook_server.py`
- [Admin panel](https://github.com/dev-sahad/minnal-bot/blob/main/admin-panel.html): static UI · Standalone operator UI for bot administration. · `admin-panel.html`
- [Config editor](https://github.com/dev-sahad/minnal-bot/blob/main/config-editor.html): static UI · Standalone UI for editing bot configuration. · `config-editor.html`
- [Webhook panel](https://github.com/dev-sahad/minnal-bot/blob/main/webhook_panel_integration.html): static UI · Browser-side panel for bridge/token-based control. · `webhook_panel_integration.html`

### TypeScript tooling

Shared API contracts, generated clients, and companion services.

- [API spec](https://github.com/dev-sahad/minnal-bot/blob/main/lib/api-spec/openapi.yaml): openapi contract · Source contract for generated clients and schemas. · `lib/api-spec/openapi.yaml`
- [API client](https://github.com/dev-sahad/minnal-bot/blob/main/lib/api-client-react/src/index.ts): generated TS client · React-oriented generated client for the API surface. · `lib/api-client-react/src/index.ts`
- [Zod schemas](https://github.com/dev-sahad/minnal-bot/blob/main/lib/api-zod/src/index.ts): generated TS schemas · Generated runtime validation schemas from the API contract. · `lib/api-zod/src/index.ts`
- [DB schema](https://github.com/dev-sahad/minnal-bot/blob/main/lib/db/src/index.ts): shared schema · Drizzle-based shared data model package for the TS side. · `lib/db/src/index.ts`
- [API server](https://github.com/dev-sahad/minnal-bot/blob/main/artifacts/api-server/src/index.ts): ts service · Companion HTTP service for health and platform routes. · `artifacts/api-server/src/index.ts`

### Frontend artifacts

Standalone React/Vite experiences for logs and mockup preview.

- [Bot logs](https://github.com/dev-sahad/minnal-bot/blob/main/artifacts/bot-logs/src/App.tsx): react app · Frontend for viewing bot logs and telemetry. · `artifacts/bot-logs/src/App.tsx`
- [Mockup sandbox](https://github.com/dev-sahad/minnal-bot/blob/main/artifacts/mockup-sandbox/src/App.tsx): react app · UI sandbox and preview environment for generated mockups. · `artifacts/mockup-sandbox/src/App.tsx`

### Local state and assets

File-backed bot state and bundled media/assets.

- [JSON state](https://github.com/dev-sahad/minnal-bot/blob/main/data/settings.json): file-backed state · Local runtime state persisted as JSON files. · `data/settings.json`
- [Assets](https://github.com/dev-sahad/minnal-bot/blob/main/audio/shunsui.mp3): runtime assets · Bundled audio and static assets used by the bot. · `audio/shunsui.mp3`

## Connections

- Bot entry → Config: loads config · Startup configuration and environment values.
- Bot entry → State mgr: persists state · Reads and writes local bot state.
- Bot entry → Logger: emits logs · Central logging setup for runtime events.
- Bot entry → Admin cogs: loads · Registers administration and moderation cogs.
- Bot entry → Community cogs: loads · Registers community automation cogs.
- Bot entry → Engagement cogs: loads · Registers engagement and entertainment cogs.
- Bot entry → Media cogs: loads · Registers music and voice cogs.
- Bot entry → Integration cogs: loads · Registers integration and bridge cogs.
- Admin cogs → JSON state: reads/writes · Administration state and policy data.
- Community cogs → JSON state: reads/writes · Role, ticket, and verification state.
- Engagement cogs → JSON state: reads/writes · Economy and stats persistence.
- Integration cogs → JSON state: reads/writes · Bridge and web config state.
- Media cogs → Assets: uses media · Local audio and runtime assets.
- Integration cogs → Webhook server: bridges · HTTP/webhook path for remote control.
- Webhook server → Webhook panel: serves/control · Browser panel connection and token flow.
- Webhook panel → Bot entry: controls · Remote operator actions via the bridge.
- Admin panel → Bot entry: administers · Static admin UI for bot operations.
- Config editor → Bot entry: edits config · Operator-facing configuration workflow.
- API server → API spec: implements · HTTP surface derived from the shared contract.
- API client → API spec: generated from · Client code produced from the OpenAPI spec.
- Zod schemas → API spec: generated from · Validation schemas produced from the OpenAPI spec.
- DB schema → API server: supports · Shared structured data model for the TS service.
- Bot logs → API server: consumes · Log UI likely reads service/bot telemetry.
- Mockup sandbox → API client: uses · Prototype UI can consume the generated client.
- Mockup sandbox → Zod schemas: validates · Sandbox can use generated schemas for typed UI flows.