# decryptu/decryptgpt architecture

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

- Interactive diagram: https://gitdiagram.com/decryptu/decryptgpt
- Repository: https://github.com/decryptu/decryptgpt

## Overview

##### Project Type & Purpose
- DecryptGPT is a modular, back-end Discord bot built on Node.js.
- It uses Discord.js to connect to the Discord Gateway and OpenAI’s API suite (GPT-4o/4.1/o3, Whisper, GPT-Image) for chat, transcription, image generation/editing, and document processing.
- It is an open-source tool designed for medical-focused, French-language academic assistance in Discord.

##### Key Architectural Components
A. Discord Gateway Client
- index.js: Bootstraps the bot, loads environment/config, logs in to Discord via Discord.js (WebSocket).
B. Event Handling Layer
- events/*.js: Listeners for ‘ready’, ‘interactionCreate’, ‘messageCreate’.
- Routes incoming Gateway events to command handlers or message responders.
C. Command Handling Layer
- commands/*.js: Implements slash commands (`/gpt-mode`, `/gpt-model`, `/image-gpt`, `/image-edit`).
- Registered at startup (scripts/delete-commands.js can reset registration).
D. Business Logic / Utility Layer
- utils/*.js: Helpers for building conversation logs, splitting messages, error handling, transcribing voice (Whisper), generating/editing images, processing documents (PDF, CSV, Excel), reacting with emojis, etc.
E. External API Clients
- OpenAI REST calls: ChatCompletions, ImageGeneration, ImageEditing, Whisper
F. Configuration & Scripts
- .env / config.example.js / channels.mjs: Bot credentials, channel IDs, default settings (model, token limits).
- scripts/delete-commands.js: CLI for maintenance.

##### Interactions & Data Flow
1. Bot startup (index.js)
- Load .env & config, register slash commands via Discord REST.
2. User Interaction
- User triggers a slash command or sends a message/voice.
- Discord Gateway pushes an event → event handler → command or message responder.
3. Command Execution
- Command handler invokes relevant util:
- For chat: buildConversationLog → call OpenAI Chat API → respond.
- For voice: transcribeVoiceMessage (Whisper) → process as text.
- For image gen/edit: createGptImage / editImage util → call GPT-Image API → upload back to Discord.
- For document: extractFileContent → analyze via Chat API.
4. Bot Response
- Process API response → utils/splitMessage if needed → Discord.js reply/edit.
5. Error Handling
- Centralized via utils/handleApiErrors & handleInteractionError → logs and safe user feedback.

##### Architectural Patterns & Principles
- Event-Driven: Decoupled event listeners and handlers.
- Modular: commands and events live in their own folders—easy to add or remove features.
- Single Responsibility: Each util does one task (transcription, image creation, file extraction).
- Configuration-Driven: Behavior controlled by config.js and environment variables—facilitates different deployments (dev vs prod).
- Extensible CLI Scripts: scripts/ folder for administrative tasks.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services
    DiscordGateway["Discord Gateway"]:::external
    DiscordREST["Discord REST API"]:::external
    OpenAIAPI["OpenAI REST API"]:::external

    %% Bot Core
    subgraph "Bot Core" 
        direction TB
        Index["index.js"]:::internal
        subgraph "Event Handling Layer"
            direction TB
            Ready["events/ready.js"]:::internal
            Interaction["events/interactionCreate.js"]:::internal
            MessageEvt["events/messageCreate.js"]:::internal
        end
        subgraph "Command Handling Layer"
            direction TB
            CmdGPTMode["commands/gpt-mode.js"]:::internal
            CmdGPTModel["commands/gpt-model.js"]:::internal
            CmdImageGen["commands/image-gpt.js"]:::internal
            CmdImageEdit["commands/image-edit.js"]:::internal
        end
        subgraph "Utility Layer"
            direction TB
            BuildLog["utils/buildConversationLog.js"]:::internal
            SplitMsg["utils/splitMessage.js"]:::internal
            Transcribe["utils/transcribeVoiceMessage.js"]:::internal
            CreateImage["utils/createGptImage.js"]:::internal
            ExtractFile["utils/extractFileContent.js"]:::internal
            ReactEmoji["utils/reactWithRandomEmoji.js"]:::internal
            RespondMsg["utils/respondToMessage.js"]:::internal
            HandleApiErr["utils/handleApiErrors.js"]:::internal
            HandleIntErr["utils/handleInteractionError.js"]:::internal
            IgnoreMsg["utils/shouldIgnoreMessage.js"]:::internal
            SetActivity["utils/setBotActivity.js"]:::internal
            DateUtils["utils/dateUtils.js"]:::internal
        end
    end

    %% Configuration & Scripts
    subgraph "Configuration & Scripts"
        direction TB
        Env[".env.exemple"]:::config
        ConfigExample["config.example.js"]:::config
        Channels["channels.mjs"]:::config
        DeleteCmd["scripts/delete-commands.js"]:::scripts
        Package["package.json"]:::config
        Lock["bun.lock"]:::config
        Readme["README.md"]:::config
        Gitignore[".gitignore"]:::config
        Gitattributes[".gitattributes"]:::config
    end

    %% Startup Flow
    Index -->|"load config & env"| Env
    Index --> ConfigExample
    Index --> Channels
    Index -->|"register slash commands"| DeleteCmd
    Index -->|"connect WebSocket"| DiscordGateway
    DiscordGateway -->|"push events"| Ready
    DiscordGateway --> Interaction
    DiscordGateway --> MessageEvt

    %% Event to Command
    Ready -->|"on ready"| SetActivity
    Interaction -->|"on interaction"| CmdGPTMode & CmdGPTModel & CmdImageGen & CmdImageEdit
    MessageEvt -->|"on message"| RespondMsg
    MessageEvt --> IgnoreMsg
    MessageEvt --> Transcribe

    %% Command to Utils and API
    CmdGPTMode --> BuildLog
    CmdGPTModel --> BuildLog
    CmdGPTMode -->|"call ChatCompletions"| OpenAIAPI
    BuildLog --> OpenAIAPI
    Transcribe -->|"call Whisper"| OpenAIAPI
    CmdImageGen --> CreateImage
    CreateImage --> OpenAIAPI
    CmdImageEdit --> CreateImage
    ExtractFile -->|"file processing"| OpenAIAPI

    %% Response and Error Handling
    OpenAIAPI --> SplitMsg
    SplitMsg --> RespondMsg
    HandleApiErr -.-> RespondMsg
    HandleIntErr -.-> RespondMsg
    RespondMsg --> DiscordREST

    %% Click Events
    click Index "https://github.com/decryptu/decryptgpt/blob/main/index.js"
    click Ready "https://github.com/decryptu/decryptgpt/blob/main/events/ready.js"
    click Interaction "https://github.com/decryptu/decryptgpt/blob/main/events/interactionCreate.js"
    click MessageEvt "https://github.com/decryptu/decryptgpt/blob/main/events/messageCreate.js"
    click CmdGPTMode "https://github.com/decryptu/decryptgpt/blob/main/commands/gpt-mode.js"
    click CmdGPTModel "https://github.com/decryptu/decryptgpt/blob/main/commands/gpt-model.js"
    click CmdImageGen "https://github.com/decryptu/decryptgpt/blob/main/commands/image-gpt.js"
    click CmdImageEdit "https://github.com/decryptu/decryptgpt/blob/main/commands/image-edit.js"
    click DeleteCmd "https://github.com/decryptu/decryptgpt/blob/main/scripts/delete-commands.js"
    click BuildLog "https://github.com/decryptu/decryptgpt/blob/main/utils/buildConversationLog.js"
    click SplitMsg "https://github.com/decryptu/decryptgpt/blob/main/utils/splitMessage.js"
    click Transcribe "https://github.com/decryptu/decryptgpt/blob/main/utils/transcribeVoiceMessage.js"
    click CreateImage "https://github.com/decryptu/decryptgpt/blob/main/utils/createGptImage.js"
    click ExtractFile "https://github.com/decryptu/decryptgpt/blob/main/utils/extractFileContent.js"
    click ReactEmoji "https://github.com/decryptu/decryptgpt/blob/main/utils/reactWithRandomEmoji.js"
    click RespondMsg "https://github.com/decryptu/decryptgpt/blob/main/utils/respondToMessage.js"
    click HandleApiErr "https://github.com/decryptu/decryptgpt/blob/main/utils/handleApiErrors.js"
    click HandleIntErr "https://github.com/decryptu/decryptgpt/blob/main/utils/handleInteractionError.js"
    click IgnoreMsg "https://github.com/decryptu/decryptgpt/blob/main/utils/shouldIgnoreMessage.js"
    click SetActivity "https://github.com/decryptu/decryptgpt/blob/main/utils/setBotActivity.js"
    click DateUtils "https://github.com/decryptu/decryptgpt/blob/main/utils/dateUtils.js"
    click Env "https://github.com/decryptu/decryptgpt/blob/main/.env.exemple"
    click ConfigExample "https://github.com/decryptu/decryptgpt/blob/main/config.example.js"
    click Channels "https://github.com/decryptu/decryptgpt/blob/main/channels.mjs"
    click Package "https://github.com/decryptu/decryptgpt/blob/main/package.json"
    click Lock "https://github.com/decryptu/decryptgpt/blob/main/bun.lock"
    click Readme "https://github.com/decryptu/decryptgpt/blob/main/README.md"
    click Gitignore "https://github.com/decryptu/decryptgpt/blob/main/.gitignore"
    click Gitattributes "https://github.com/decryptu/decryptgpt/blob/main/.gitattributes"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0366d6,color:#000
    classDef external fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef config fill:#E0E0E0,stroke:#888,color:#000
    classDef scripts fill:#F0F0F0,stroke:#999,color:#000
```
