# sudis/discord-email-verifier architecture

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

- Interactive diagram: https://gitdiagram.com/sudis/discord-email-verifier
- Repository: https://github.com/sudis/discord-email-verifier

## Overview

##### Project Type and Purpose
- This is a backend Node.js “Discord bot” service whose sole responsibility is to verify users’ email addresses via SMTP (e-mail) and store/track verification states in a MySQL database.
- It uses the Discord slash-command framework GCommands V9, Nodemailer for SMTP, and a MySQL backend.

##### File-Structure Analysis
- index.js – the entry point. Initializes the Discord client (with GCommands), loads configuration, connects to MySQL, registers slash commands and event listeners, and starts the bot.
- config/
– functions.js – common utility functions (e.g., database helpers, timeouts).
– mysql.js – establishes and exports a MySQL connection pool.
– settings.json – environment-specific settings (SMTP credentials, DB credentials, bot token).
– table.sql – DDL for creating the verification table.
- commands/verify.js – slash-command handler for `/verify send <email>` and any other verification subcommands.
- listeners/ready.js – event listener for the “ready” event (bot startup).
- examples/ – sample code showing how to programmatically issue commands or listen for events.

##### Key Architectural Patterns
- Event-Driven / Command Pattern – Discord events are fed into GCommands, which dispatches to command handlers or listeners.
- Layered Approach –
– Presentation layer: Discord API Gateway (slash commands and events).
– Application layer: command handlers (business logic), listener handlers.
– Infrastructure layer: MySQL database, external SMTP service.
- Asynchronous I/O – All I/O operations (Discord API, MySQL, SMTP) are handled asynchronously via Promises or callbacks.

##### Main Components
a. Discord API Gateway
– Emits raw websocket events (ready, interactionCreate).
– Receives outgoing messages & slash‐command registrations.
b. Bot Core (index.js + GCommands)
– Event Dispatcher: routes incoming interactions to the right command or listener.
– Configuration Loader: reads settings.json and initializes SMTP & DB modules.
c. Command Handler (commands/verify.js)
– Implements `/verify send <email>` logic:
- Insert or update verification record in MySQL with status=“PENDING” and a TTL.
- Generate and send verification code via Nodemailer to the provided email.
d. Listener Handler (listeners/ready.js)
– On “ready” event: logs startup info, registers slash commands with Discord.
e. MySQL Database (config/mysql.js + table.sql)
– Verification Table: fields like userId, email, status, timestamp.
– TTL cleanup logic (could be a scheduled job in functions.js or handled in command logic).
f. SMTP Service (Nodemailer + external Gmail SMTP)
– E-mail transport for sending verification messages.
g. Utilities (config/functions.js)
– Timeout/deletion logic for pending records.
– Other helper methods (email formatting, database wrappers).

##### Relationships and Data Flows
1. User issues `/verify send <email>` in Discord
↓
2. Discord Gateway → Bot Core (interactionCreate)
↓
3. Bot Core dispatch → Command Handler
↓
4. Command Handler
- Calls DB module → INSERT/UPDATE PENDING record
- Calls Email module → Nodemailer → Gmail SMTP
↓
5. Email is sent → User inbox
↓
6. (Optionally) User clicks link or issues another bot command → Bot Core → verify status updated to VERIFIED in DB
↓
7. Post-verification actions (e.g., assign Discord role) can be added here.

##### Essential Elements to Capture
- Bot Initialization (config load, DB connect, GCommands register)
- Runtime Event Loop (Discord events → command/listener dispatch)
- Data Store interactions (PENDING → VERIFIED → DELETE)
- External E-mail dispatch via Nodemailer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        DiscordAPI["Discord API Gateway"]:::discord
    end

    %% Application Layer
    subgraph "Application Layer"
        BotCore["Bot Core\n(index.js & GCommands)"]:::discord
        ConfigLoader["Configuration Loader"]:::util
        CommandHandler["Command Handler\n(commands/verify.js)"]:::app
        ListenerHandler["Listener Handler\n(listeners/ready.js)"]:::app
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        MySQLModule["MySQL Module\n(config/mysql.js)"]:::db
        VerificationTable["Verification Table DDL\n(config/table.sql)"]:::db
        SMTPService["SMTP Service\n(Nodemailer + Gmail)"]:::ext
        Utilities["Utilities\n(config/functions.js)"]:::util
    end

    %% Examples
    subgraph "Examples"
        ExampleCmd["Example Command\n(examples/command.js)"]:::util
        ExampleListener["Example Listener\n(examples/listener.js)"]:::util
    end

    %% User
    User["User"]:::ext

    %% Flows
    DiscordAPI -->|"interactionCreate event"| BotCore
    BotCore -->|"load config"| ConfigLoader
    ConfigLoader -->|"DB init"| MySQLModule
    ConfigLoader -->|"SMTP init"| SMTPService
    BotCore -->|"dispatch interaction"| CommandHandler
    BotCore -->|"ready event"| ListenerHandler
    ListenerHandler -->|"register slash commands"| DiscordAPI

    CommandHandler -->|"SQL INSERT/UPDATE PENDING"| MySQLModule
    CommandHandler -->|"send mail via SMTP"| SMTPService
    SMTPService -->|"email delivered"| User

    CommandHandler -->|"cleanup helpers"| Utilities
    Utilities -->|"cleanup TTL"| MySQLModule

    %% Examples relationships
    ExampleCmd -.->|uses| CommandHandler
    ExampleListener -.->|uses| ListenerHandler

    %% Click Events
    click DiscordAPI "https://github.com/sudis/discord-email-verifier/blob/main/index.js"
    click BotCore "https://github.com/sudis/discord-email-verifier/blob/main/index.js"
    click ConfigLoader "https://github.com/sudis/discord-email-verifier/blob/main/config/settings.json"
    click CommandHandler "https://github.com/sudis/discord-email-verifier/blob/main/commands/verify.js"
    click ListenerHandler "https://github.com/sudis/discord-email-verifier/blob/main/listeners/ready.js"
    click MySQLModule "https://github.com/sudis/discord-email-verifier/blob/main/config/mysql.js"
    click VerificationTable "https://github.com/sudis/discord-email-verifier/blob/main/config/table.sql"
    click SMTPService "https://github.com/sudis/discord-email-verifier/blob/main/config/settings.json"
    click Utilities "https://github.com/sudis/discord-email-verifier/blob/main/config/functions.js"
    click ExampleCmd "https://github.com/sudis/discord-email-verifier/blob/main/examples/command.js"
    click ExampleListener "https://github.com/sudis/discord-email-verifier/blob/main/examples/listener.js"

    %% Styles
    classDef discord fill:#cce5ff,stroke:#6495ed,color:#000
    classDef app fill:#e6f7ff,stroke:#4682b4,color:#000
    classDef db fill:#ccffcc,stroke:#32cd32,color:#000
    classDef ext fill:#ffe5cc,stroke:#ffa500,color:#000
    classDef util fill:#dddddd,stroke:#999,color:#000
```
