# ayushsharma297/discord_bot architecture

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

- Interactive diagram: https://gitdiagram.com/ayushsharma297/discord_bot
- Repository: https://github.com/ayushsharma297/discord_bot

## Overview

##### Project type and purpose
- This is a modular, full-stack Discord bot (“Rajjo Gujjar 💕”) built in Python.
- It integrates with Discord via discord.py, uses FastAPI for LLM inference, connects to a RAG server (LightRAG), and uses Lavalink for music playback. It logs to SQLite.

##### File structure
- Top-level:
- main.py – bot startup, cog loading, Lavalink setup
- methods.py – shared helpers (conversation history, token counting)
- requirements.txt / pyproject.toml – dependencies
- env.example – environment variables
- assets/ – media files and example screenshots
- cogs/ – Discord command modules (ai_chat, music, moderation, fun, info, events, roast)
- LLM_server/ – FastAPI app (ollama_call.py, rag_call.py, web_search.py)
- lavalink/ – Java Lavalink server + plugins + config
- token_counter/ – standalone token-counting utility
- utils/ – YAML system prompts and general utilities
- Key patterns:
- Cog-based architecture for commands and events
- Separate microservice for LLM (FastAPI)
- External music service (Lavalink)
- SQLite for logging and analytics

##### README for additional insights
- Features: AI chat, music playback, moderation, games, TTS, logging
- Tech stack: Python 3.10+, discord.py, aiohttp, FastAPI, LightRAG, pandas, dotenv, Lavalink, Google TTS
- Startup steps: Launch LLM_server (uvicorn), LightRAG, Lavalink; then run main.py

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    User["Discord User"]:::external

    %% Discord Gateway
    Gateway["Discord Gateway\n(WebSocket API)"]:::external

    %% Bot Core
    subgraph "Bot Core" 
        direction TB
        Core["main.py\n(Bot Core)"]:::module
        click Core "https://github.com/ayushsharma297/discord_bot/blob/main/main.py"

        subgraph "Discord Command Cogs"
            direction TB
            AICog["AI Chat Cog"]:::module
            click AICog "https://github.com/ayushsharma297/discord_bot/blob/main/cogs/ai_chat.py"
            MusicCog["Music Cog"]:::module
            click MusicCog "https://github.com/ayushsharma297/discord_bot/blob/main/cogs/music.py"
            ModCog["Moderation Cog"]:::module
            click ModCog "https://github.com/ayushsharma297/discord_bot/blob/main/cogs/moderation.py"
            FunCog["Fun Cog"]:::module
            click FunCog "https://github.com/ayushsharma297/discord_bot/blob/main/cogs/fun.py"
            InfoCog["Info Cog"]:::module
            click InfoCog "https://github.com/ayushsharma297/discord_bot/blob/main/cogs/info.py"
            EventsCog["Events Cog"]:::module
            click EventsCog "https://github.com/ayushsharma297/discord_bot/blob/main/cogs/events.py"
            RoastCog["Roast Cog"]:::module
            click RoastCog "https://github.com/ayushsharma297/discord_bot/blob/main/cogs/roast.py"
        end

        subgraph "Method Layer"
            direction TB
            Methods["methods.py\n(Shared Helpers)"]:::module
            click Methods "https://github.com/ayushsharma297/discord_bot/blob/main/methods.py"
            Utils["utility.py\n(General Utils)"]:::utility
            click Utils "https://github.com/ayushsharma297/discord_bot/blob/main/utils/utility.py"
            Prompts["sys_prompts.yaml\n(System Prompts)"]:::utility
            click Prompts "https://github.com/ayushsharma297/discord_bot/blob/main/utils/sys_prompts.yaml"
        end
    end

    %% LLM Microservice
    subgraph "LLM Server\n(FastAPI)" 
        direction TB
        LLMLaunch["llm_handler.py"]:::module
        click LLMLaunch "https://github.com/ayushsharma297/discord_bot/blob/main/LLM_server/llm_handler.py"
        RAGCall["rag_call.py"]:::module
        click RAGCall "https://github.com/ayushsharma297/discord_bot/blob/main/LLM_server/rag_call.py"
        WebSearch["web_search.py"]:::module
        click WebSearch "https://github.com/ayushsharma297/discord_bot/blob/main/LLM_server/web_search.py"
        LLMDocs["README.md"]:::utility
        click LLMDocs "https://github.com/ayushsharma297/discord_bot/blob/main/LLM_server/README.md"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LightRAG["LightRAG RAG Service"]:::external
        Lavalink["Lavalink Audio Server"]:::external
        click Lavalink "https://github.com/ayushsharma297/discord_bot/blob/main/lavalink/application.yml"
        WebSearchAPI["Web Search API"]:::external
    end

    %% Storage & Assets
    subgraph "Storage & Assets"
        direction TB
        SQLiteDB["SQLite Database\n(chat_log.db)"]:::storage
        Assets["assets/ (Media Files)"]:::storage
        click Assets "https://github.com/ayushsharma297/discord_bot/tree/main/assets/"
    end

    %% Utils & Analytics
    subgraph "Utilities & Analytics"
        direction TB
        TokenCounter["Token Counter Utility"]:::utility
        click TokenCounter "https://github.com/ayushsharma297/discord_bot/blob/main/token_counter/universal_token_counter.py"
        TCSetup["requirements_setup.md\n& requirements.txt"]:::utility
        click TCSetup "https://github.com/ayushsharma297/discord_bot/blob/main/token_counter/requirements_setup.md"
        click TCSetup "https://github.com/ayushsharma297/discord_bot/blob/main/token_counter/requirements.txt"
    end

    %% Environment & Docs
    subgraph "Env & Docs"
        direction TB
        Env["env.example"]:::utility
        click Env "https://github.com/ayushsharma297/discord_bot/blob/main/env.example"
        Dependencies["requirements.txt\npyproject.toml"]:::utility
        click Dependencies "https://github.com/ayushsharma297/discord_bot/blob/main/requirements.txt"
        click Dependencies "https://github.com/ayushsharma297/discord_bot/blob/main/pyproject.toml"
        RootDocs["README.md\nLICENSE\n.gitignore"]:::utility
        click RootDocs "https://github.com/ayushsharma297/discord_bot/blob/main/README.md"
    end

    %% Connections
    User -->|"WS Connect"| Gateway
    Gateway -->|"discord.py WebSocket"| Core

    Core -->|"loads"| AICog & MusicCog & ModCog & FunCog & InfoCog & EventsCog & RoastCog
    AICog -->|"calls methods"| Methods
    AICog -->|"loads prompts"| Prompts
    AICog -->|"HTTP Request"| LLMLaunch
    LLMLaunch -->|"uses RAG API"| RAGCall
    RAGCall -->|"gRPC/HTTP"| LightRAG
    LLMLaunch -->|"HTTP Request"| WebSearch
    MusicCog -->|"WS to Audio"| Lavalink
    MusicCog -->|"streams audio to"| User

    Core -->|"SQL Read/Write"| SQLiteDB
    Core -->|"file I/O"| Assets
    Core -->|"on-demand"| TokenCounter

    %% Command Sequence Annotations
    User -->|"!play"| MusicCog
    MusicCog -->|"!play flow"| Lavalink
    User -->|"!chat"| AICog
    AICog -->|"!chat flow"| LLMLaunch

    %% Legend
    subgraph "Legend"
        direction LR
        L_module["Blue: In-Process Modules"]:::module
        L_storage["Green: Storage"]:::storage
        L_external["Yellow: External Services"]:::external
        L_utility["Gray: Utilities/Docs"]:::utility
    end

    classDef module fill:#D0E8FF,stroke:#005CAF,color:#000;
    classDef storage fill:#DFF2BF,stroke:#4F8A10,color:#000;
    classDef external fill:#FFF2CC,stroke:#D6B656,color:#000;
    classDef utility fill:#E0E0E0,stroke:#818181,color:#000;
```
