refactor: initial moves

bot/lib/BotClient.ts

@@ -0,0 +1,121 @@
+import { Client as DiscordClient, Collection, GatewayIntentBits, REST, Routes } from "discord.js";
+import { join } from "node:path";
+import type { Command } from "@shared/lib/types";
+import { env } from "@shared/lib/env";
+import { CommandLoader } from "@lib/loaders/CommandLoader";
+import { EventLoader } from "@lib/loaders/EventLoader";
+
+export class Client extends DiscordClient {
+
+    commands: Collection<string, Command>;
+    lastCommandTimestamp: number | null = null;
+    private commandLoader: CommandLoader;
+    private eventLoader: EventLoader;
+
+    constructor({ intents }: { intents: number[] }) {
+        super({ intents });
+        this.commands = new Collection<string, Command>();
+        this.commandLoader = new CommandLoader(this);
+        this.eventLoader = new EventLoader(this);
+    }
+
+    async loadCommands(reload: boolean = false) {
+        if (reload) {
+            this.commands.clear();
+            console.log("♻️  Reloading commands...");
+        }
+
+        const commandsPath = join(import.meta.dir, '../commands');
+        const result = await this.commandLoader.loadFromDirectory(commandsPath, reload);
+
+        console.log(`📦 Command loading complete: ${result.loaded} loaded, ${result.skipped} skipped, ${result.errors.length} errors`);
+    }
+
+    async loadEvents(reload: boolean = false) {
+        if (reload) {
+            this.removeAllListeners();
+            console.log("♻️  Reloading events...");
+        }
+
+        const eventsPath = join(import.meta.dir, '../events');
+        const result = await this.eventLoader.loadFromDirectory(eventsPath, reload);
+
+        console.log(`📦 Event loading complete: ${result.loaded} loaded, ${result.skipped} skipped, ${result.errors.length} errors`);
+    }
+
+
+
+    async deployCommands() {
+        // We use env.DISCORD_BOT_TOKEN directly so this can run without client.login()
+        const token = env.DISCORD_BOT_TOKEN;
+        if (!token) {
+            console.error("DISCORD_BOT_TOKEN is not set.");
+            return;
+        }
+
+        const rest = new REST().setToken(token);
+        const commandsData = this.commands.map(c => c.data.toJSON());
+        const guildId = env.DISCORD_GUILD_ID;
+        const clientId = env.DISCORD_CLIENT_ID;
+
+        if (!clientId) {
+            console.error("DISCORD_CLIENT_ID is not set.");
+            return;
+        }
+
+        try {
+            console.log(`Started refreshing ${commandsData.length} application (/) commands.`);
+
+            let data;
+            if (guildId) {
+                console.log(`Registering commands to guild: ${guildId}`);
+                data = await rest.put(
+                    Routes.applicationGuildCommands(clientId, guildId),
+                    { body: commandsData },
+                );
+                // Clear global commands to avoid duplicates
+                await rest.put(Routes.applicationCommands(clientId), { body: [] });
+            } else {
+                console.log('Registering commands globally');
+                data = await rest.put(
+                    Routes.applicationCommands(clientId),
+                    { body: commandsData },
+                );
+            }
+
+            console.log(`Successfully reloaded ${(data as any).length} application (/) commands.`);
+        } catch (error: any) {
+            if (error.code === 50001) {
+                console.warn("Missing Access: The bot is not in the guild or lacks 'applications.commands' scope.");
+                console.warn("   If you are testing locally, make sure you invited the bot with scope 'bot applications.commands'.");
+            } else {
+                console.error(error);
+            }
+        }
+    }
+
+    async shutdown() {
+        const { setShuttingDown, waitForTransactions } = await import("./shutdown");
+        const { closeDatabase } = await import("@shared/db/DrizzleClient");
+
+        console.log("🛑 Shutdown signal received. Starting graceful shutdown...");
+        setShuttingDown(true);
+
+        // Wait for transactions to complete
+        console.log("⏳ Waiting for active transactions to complete...");
+        await waitForTransactions(10000);
+
+        // Destroy Discord client
+        console.log("🔌 Disconnecting from Discord...");
+        this.destroy();
+
+        // Close database
+        console.log("🗄️ Closing database connection...");
+        await closeDatabase();
+
+        console.log("👋 Graceful shutdown complete. Exiting.");
+        process.exit(0);
+    }
+}
+
+export const AuroraClient = new Client({ intents: [GatewayIntentBits.Guilds, GatewayIntentBits.MessageContent, GatewayIntentBits.GuildMessages, GatewayIntentBits.GuildMembers] });

bot/lib/config.ts

@@ -0,0 +1,204 @@
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+const configPath = join(import.meta.dir, '..', '..', 'config', 'config.json');
+
+export interface GameConfigType {
+    leveling: {
+        base: number;
+        exponent: number;
+        chat: {
+            cooldownMs: number;
+            minXp: number;
+            maxXp: number;
+        }
+    },
+    economy: {
+        daily: {
+            amount: bigint;
+            streakBonus: bigint;
+            weeklyBonus: bigint;
+            cooldownMs: number;
+        },
+        transfers: {
+            allowSelfTransfer: boolean;
+            minAmount: bigint;
+        },
+        exam: {
+            multMin: number;
+            multMax: number;
+        }
+    },
+    inventory: {
+        maxStackSize: bigint;
+        maxSlots: number;
+    },
+    commands: Record<string, boolean>;
+    lootdrop: {
+        activityWindowMs: number;
+        minMessages: number;
+        spawnChance: number;
+        cooldownMs: number;
+        reward: {
+            min: number;
+            max: number;
+            currency: string;
+        }
+    };
+    studentRole: string;
+    visitorRole: string;
+    colorRoles: string[];
+    welcomeChannelId?: string;
+    welcomeMessage?: string;
+    feedbackChannelId?: string;
+    terminal?: {
+        channelId: string;
+        messageId: string;
+    };
+    moderation: {
+        prune: {
+            maxAmount: number;
+            confirmThreshold: number;
+            batchSize: number;
+            batchDelayMs: number;
+        };
+        cases: {
+            dmOnWarn: boolean;
+            logChannelId?: string;
+            autoTimeoutThreshold?: number;
+        };
+    };
+    system: Record<string, any>;
+}
+
+// Initial default config state
+export const config: GameConfigType = {} as GameConfigType;
+
+const bigIntSchema = z.union([z.string(), z.number(), z.bigint()])
+    .refine((val) => {
+        try {
+            BigInt(val);
+            return true;
+        } catch {
+            return false;
+        }
+    }, { message: "Must be a valid integer" })
+    .transform((val) => BigInt(val));
+
+const configSchema = z.object({
+    leveling: z.object({
+        base: z.number(),
+        exponent: z.number(),
+        chat: z.object({
+            cooldownMs: z.number(),
+            minXp: z.number(),
+            maxXp: z.number(),
+        })
+    }),
+    economy: z.object({
+        daily: z.object({
+            amount: bigIntSchema,
+            streakBonus: bigIntSchema,
+            weeklyBonus: bigIntSchema.default(50n),
+            cooldownMs: z.number(),
+        }),
+        transfers: z.object({
+            allowSelfTransfer: z.boolean(),
+            minAmount: bigIntSchema,
+        }),
+        exam: z.object({
+            multMin: z.number(),
+            multMax: z.number(),
+        })
+    }),
+    inventory: z.object({
+        maxStackSize: bigIntSchema,
+        maxSlots: z.number(),
+    }),
+    commands: z.record(z.string(), z.boolean()),
+    lootdrop: z.object({
+        activityWindowMs: z.number(),
+        minMessages: z.number(),
+        spawnChance: z.number(),
+        cooldownMs: z.number(),
+        reward: z.object({
+            min: z.number(),
+            max: z.number(),
+            currency: z.string(),
+        })
+
+    }),
+    studentRole: z.string(),
+    visitorRole: z.string(),
+    colorRoles: z.array(z.string()).default([]),
+    welcomeChannelId: z.string().optional(),
+    welcomeMessage: z.string().optional(),
+    feedbackChannelId: z.string().optional(),
+    terminal: z.object({
+        channelId: z.string(),
+        messageId: z.string()
+    }).optional(),
+    moderation: z.object({
+        prune: z.object({
+            maxAmount: z.number().default(100),
+            confirmThreshold: z.number().default(50),
+            batchSize: z.number().default(100),
+            batchDelayMs: z.number().default(1000)
+        }),
+        cases: z.object({
+            dmOnWarn: z.boolean().default(true),
+            logChannelId: z.string().optional(),
+            autoTimeoutThreshold: z.number().optional()
+        })
+    }).default({
+        prune: {
+            maxAmount: 100,
+            confirmThreshold: 50,
+            batchSize: 100,
+            batchDelayMs: 1000
+        },
+        cases: {
+            dmOnWarn: true
+        }
+    }),
+    system: z.record(z.string(), z.any()).default({}),
+});
+
+export function reloadConfig() {
+    if (!existsSync(configPath)) {
+        throw new Error(`Config file not found at ${configPath}`);
+    }
+
+    const raw = readFileSync(configPath, 'utf-8');
+    const rawConfig = JSON.parse(raw);
+
+    // Update config object in place
+    // We use Object.assign to keep the reference to the exported 'config' object same
+    const validatedConfig = configSchema.parse(rawConfig);
+    Object.assign(config, validatedConfig);
+
+    console.log("🔄 Config reloaded from disk.");
+}
+
+// Initial load
+reloadConfig();
+
+// Backwards compatibility alias
+export const GameConfig = config;
+
+export function saveConfig(newConfig: unknown) {
+    // Validate and transform input
+    const validatedConfig = configSchema.parse(newConfig);
+
+    const replacer = (key: string, value: any) => {
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        return value;
+    };
+
+    const jsonString = JSON.stringify(validatedConfig, replacer, 4);
+    writeFileSync(configPath, jsonString, 'utf-8');
+    reloadConfig();
+}

bot/lib/configManager.ts

@@ -0,0 +1,19 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const configPath = join(process.cwd(), 'config', 'config.json');
+
+export const configManager = {
+    toggleCommand: (commandName: string, enabled: boolean) => {
+        const raw = readFileSync(configPath, 'utf-8');
+        const data = JSON.parse(raw);
+
+        if (!data.commands) {
+            data.commands = {};
+        }
+
+        data.commands[commandName] = enabled;
+
+        writeFileSync(configPath, JSON.stringify(data, null, 4));
+    }
+};

bot/lib/db.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+
+// Mock DrizzleClient
+mock.module("./DrizzleClient", () => ({
+    DrizzleClient: {
+        transaction: async (cb: any) => cb("MOCK_TX")
+    }
+}));
+
+import { withTransaction } from "./db";
+import { setShuttingDown, getActiveTransactions, decrementTransactions } from "./shutdown";
+
+describe("db withTransaction", () => {
+    beforeEach(() => {
+        setShuttingDown(false);
+        // Reset transaction count
+        while (getActiveTransactions() > 0) {
+            decrementTransactions();
+        }
+    });
+
+    it("should allow transactions when not shutting down", async () => {
+        const result = await withTransaction(async (tx) => {
+            return "success";
+        });
+        expect(result).toBe("success");
+        expect(getActiveTransactions()).toBe(0);
+    });
+
+    it("should throw error when shutting down", async () => {
+        setShuttingDown(true);
+        expect(withTransaction(async (tx) => {
+            return "success";
+        })).rejects.toThrow("System is shutting down, no new transactions allowed.");
+        expect(getActiveTransactions()).toBe(0);
+    });
+
+    it("should increment and decrement transaction count", async () => {
+        let countDuring = 0;
+        await withTransaction(async (tx) => {
+            countDuring = getActiveTransactions();
+            return "ok";
+        });
+        expect(countDuring).toBe(1);
+        expect(getActiveTransactions()).toBe(0);
+    });
+});

bot/lib/db.ts

@@ -0,0 +1,25 @@
+import { DrizzleClient } from "@shared/db/DrizzleClient";
+import type { Transaction } from "@shared/lib/types";
+import { isShuttingDown, incrementTransactions, decrementTransactions } from "./shutdown";
+
+export const withTransaction = async <T>(
+    callback: (tx: Transaction) => Promise<T>,
+    tx?: Transaction
+): Promise<T> => {
+    if (tx) {
+        return await callback(tx);
+    } else {
+        if (isShuttingDown()) {
+            throw new Error("System is shutting down, no new transactions allowed.");
+        }
+
+        incrementTransactions();
+        try {
+            return await DrizzleClient.transaction(async (newTx) => {
+                return await callback(newTx);
+            });
+        } finally {
+            decrementTransactions();
+        }
+    }
+};

bot/lib/embeds.ts

@@ -0,0 +1,75 @@
+import { Colors, type ColorResolvable, EmbedBuilder } from "discord.js";
+
+/**
+ * Creates a standardized error embed.
+ * @param message The error message to display.
+ * @param title Optional title for the embed. Defaults to "Error".
+ * @returns An EmbedBuilder instance configured as an error.
+ */
+export function createErrorEmbed(message: string, title: string = "Error"): EmbedBuilder {
+    return new EmbedBuilder()
+        .setTitle(`❌ ${title}`)
+        .setDescription(message)
+        .setColor(Colors.Red)
+        .setTimestamp();
+}
+
+/**
+ * Creates a standardized warning embed.
+ * @param message The warning message to display.
+ * @param title Optional title for the embed. Defaults to "Warning".
+ * @returns An EmbedBuilder instance configured as a warning.
+ */
+export function createWarningEmbed(message: string, title: string = "Warning"): EmbedBuilder {
+    return new EmbedBuilder()
+        .setTitle(`⚠️ ${title}`)
+        .setDescription(message)
+        .setColor(Colors.Yellow)
+        .setTimestamp();
+}
+
+/**
+ * Creates a standardized success embed.
+ * @param message The success message to display.
+ * @param title Optional title for the embed. Defaults to "Success".
+ * @returns An EmbedBuilder instance configured as a success.
+ */
+export function createSuccessEmbed(message: string, title: string = "Success"): EmbedBuilder {
+    return new EmbedBuilder()
+        .setTitle(`✅ ${title}`)
+        .setDescription(message)
+        .setColor(Colors.Green)
+        .setTimestamp();
+}
+
+/**
+ * Creates a standardized info embed.
+ * @param message The info message to display.
+ * @param title Optional title for the embed. Defaults to "Info".
+ * @returns An EmbedBuilder instance configured as info.
+ */
+export function createInfoEmbed(message: string, title: string = "Info"): EmbedBuilder {
+    return new EmbedBuilder()
+        .setTitle(`ℹ️ ${title}`)
+        .setDescription(message)
+        .setColor(Colors.Blue)
+        .setTimestamp();
+}
+
+/**
+ * Creates a standardized base embed with common configuration.
+ * @param title Optional title for the embed.
+ * @param description Optional description for the embed.
+ * @param color Optional color for the embed.
+ * @returns An EmbedBuilder instance with base configuration.
+ */
+export function createBaseEmbed(title?: string, description?: string, color?: ColorResolvable): EmbedBuilder {
+    const embed = new EmbedBuilder()
+        .setTimestamp();
+
+    if (title) embed.setTitle(title);
+    if (description) embed.setDescription(description);
+    if (color) embed.setColor(color);
+
+    return embed;
+}

bot/lib/errors.ts

@@ -0,0 +1,18 @@
+export class ApplicationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+
+export class UserError extends ApplicationError {
+    constructor(message: string) {
+        super(message);
+    }
+}
+
+export class SystemError extends ApplicationError {
+    constructor(message: string) {
+        super(message);
+    }
+}

bot/lib/handlers/AutocompleteHandler.ts

@@ -0,0 +1,22 @@
+import { AutocompleteInteraction } from "discord.js";
+import { AuroraClient } from "@/lib/BotClient";
+ 
+
+/**
+ * Handles autocomplete interactions for slash commands
+ */
+export class AutocompleteHandler {
+    static async handle(interaction: AutocompleteInteraction): Promise<void> {
+        const command = AuroraClient.commands.get(interaction.commandName);
+
+        if (!command || !command.autocomplete) {
+            return;
+        }
+
+        try {
+            await command.autocomplete(interaction);
+        } catch (error) {
+            console.error(`Error handling autocomplete for ${interaction.commandName}:`, error);
+        }
+    }
+}

bot/lib/handlers/CommandHandler.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect, mock, beforeEach } from "bun:test";
+import { CommandHandler } from "./CommandHandler";
+import { AuroraClient } from "@/lib/BotClient";
+import { ChatInputCommandInteraction } from "discord.js";
+
+// Mock UserService
+mock.module("@/modules/user/user.service", () => ({
+    userService: {
+        getOrCreateUser: mock(() => Promise.resolve())
+    }
+}));
+
+describe("CommandHandler", () => {
+    beforeEach(() => {
+        AuroraClient.commands.clear();
+        AuroraClient.lastCommandTimestamp = null;
+    });
+
+    test("should update lastCommandTimestamp on successful execution", async () => {
+        const executeSuccess = mock(() => Promise.resolve());
+        AuroraClient.commands.set("test", {
+            data: { name: "test" } as any,
+            execute: executeSuccess
+        } as any);
+
+        const interaction = {
+            commandName: "test",
+            user: { id: "123", username: "testuser" }
+        } as unknown as ChatInputCommandInteraction;
+
+        await CommandHandler.handle(interaction);
+
+        expect(executeSuccess).toHaveBeenCalled();
+        expect(AuroraClient.lastCommandTimestamp).not.toBeNull();
+        expect(AuroraClient.lastCommandTimestamp).toBeGreaterThan(0);
+    });
+
+    test("should not update lastCommandTimestamp on failed execution", async () => {
+        const executeError = mock(() => Promise.reject(new Error("Command Failed")));
+        AuroraClient.commands.set("fail", {
+            data: { name: "fail" } as any,
+            execute: executeError
+        } as any);
+
+        const interaction = {
+            commandName: "fail",
+            user: { id: "123", username: "testuser" },
+            replied: false,
+            deferred: false,
+            reply: mock(() => Promise.resolve()),
+            followUp: mock(() => Promise.resolve())
+        } as unknown as ChatInputCommandInteraction;
+
+        await CommandHandler.handle(interaction);
+
+        expect(executeError).toHaveBeenCalled();
+        expect(AuroraClient.lastCommandTimestamp).toBeNull();
+    });
+});

bot/lib/handlers/CommandHandler.ts

@@ -0,0 +1,41 @@
+import { ChatInputCommandInteraction, MessageFlags } from "discord.js";
+import { AuroraClient } from "@/lib/BotClient";
+import { userService } from "@shared/modules/user/user.service";
+import { createErrorEmbed } from "@lib/embeds";
+ 
+
+/**
+ * Handles slash command execution
+ * Includes user validation and comprehensive error handling
+ */
+export class CommandHandler {
+    static async handle(interaction: ChatInputCommandInteraction): Promise<void> {
+        const command = AuroraClient.commands.get(interaction.commandName);
+
+        if (!command) {
+            console.error(`No command matching ${interaction.commandName} was found.`);
+            return;
+        }
+
+        // Ensure user exists in database
+        try {
+            await userService.getOrCreateUser(interaction.user.id, interaction.user.username);
+        } catch (error) {
+            console.error("Failed to ensure user exists:", error);
+        }
+
+        try {
+            await command.execute(interaction);
+            AuroraClient.lastCommandTimestamp = Date.now();
+        } catch (error) {
+            console.error(String(error));
+            const errorEmbed = createErrorEmbed('There was an error while executing this command!');
+
+            if (interaction.replied || interaction.deferred) {
+                await interaction.followUp({ embeds: [errorEmbed], flags: MessageFlags.Ephemeral });
+            } else {
+                await interaction.reply({ embeds: [errorEmbed], flags: MessageFlags.Ephemeral });
+            }
+        }
+    }
+}

bot/lib/handlers/ComponentInteractionHandler.ts

@@ -0,0 +1,78 @@
+import { ButtonInteraction, StringSelectMenuInteraction, ModalSubmitInteraction, MessageFlags } from "discord.js";
+ 
+import { UserError } from "@lib/errors";
+import { createErrorEmbed } from "@lib/embeds";
+
+type ComponentInteraction = ButtonInteraction | StringSelectMenuInteraction | ModalSubmitInteraction;
+
+/**
+ * Handles component interactions (buttons, select menus, modals)
+ * Routes to appropriate handlers based on customId patterns
+ * Provides centralized error handling with UserError differentiation
+ */
+export class ComponentInteractionHandler {
+    static async handle(interaction: ComponentInteraction): Promise<void> {
+        const { interactionRoutes } = await import("@lib/interaction.routes");
+
+        for (const route of interactionRoutes) {
+            if (route.predicate(interaction)) {
+                const module = await route.handler();
+                const handlerMethod = module[route.method];
+
+                if (typeof handlerMethod === 'function') {
+                    try {
+                        await handlerMethod(interaction);
+                        return;
+                    } catch (error) {
+                        await this.handleError(interaction, error, route.method);
+                        return;
+                    }
+                } else {
+                    console.error(`Handler method ${route.method} not found in module`);
+                }
+            }
+        }
+    }
+
+    /**
+     * Handles errors from interaction handlers
+     * Differentiates between UserError (user-facing) and system errors
+     */
+    private static async handleError(
+        interaction: ComponentInteraction,
+        error: unknown,
+        handlerName: string
+    ): Promise<void> {
+        const isUserError = error instanceof UserError;
+
+        // Determine error message
+        const errorMessage = isUserError
+            ? (error as Error).message
+            : 'An unexpected error occurred. Please try again later.';
+
+        // Log system errors (non-user errors) for debugging
+        if (!isUserError) {
+            console.error(`Error in ${handlerName}:`, error);
+        }
+
+        const errorEmbed = createErrorEmbed(errorMessage);
+
+        try {
+            // Handle different interaction states
+            if (interaction.replied || interaction.deferred) {
+                await interaction.followUp({
+                    embeds: [errorEmbed],
+                    flags: MessageFlags.Ephemeral
+                });
+            } else {
+                await interaction.reply({
+                    embeds: [errorEmbed],
+                    flags: MessageFlags.Ephemeral
+                });
+            }
+        } catch (replyError) {
+            // If we can't send a reply, log it
+            console.error(`Failed to send error response in ${handlerName}:`, replyError);
+        }
+    }
+}

bot/lib/handlers/index.ts

@@ -0,0 +1,3 @@
+export { ComponentInteractionHandler } from "./ComponentInteractionHandler";
+export { AutocompleteHandler } from "./AutocompleteHandler";
+export { CommandHandler } from "./CommandHandler";

bot/lib/interaction.routes.ts

@@ -0,0 +1,61 @@
+import { ButtonInteraction, ModalSubmitInteraction, StringSelectMenuInteraction } from "discord.js";
+
+// Union type for all component interactions
+type ComponentInteraction = ButtonInteraction | StringSelectMenuInteraction | ModalSubmitInteraction;
+
+// Type for the handler function that modules export
+type InteractionHandler = (interaction: ComponentInteraction) => Promise<void>;
+
+// Type for the dynamically imported module containing the handler
+interface InteractionModule {
+    [key: string]: (...args: any[]) => Promise<void> | any;
+}
+
+// Route definition
+interface InteractionRoute {
+    predicate: (interaction: ComponentInteraction) => boolean;
+    handler: () => Promise<InteractionModule>;
+    method: string;
+}
+
+export const interactionRoutes: InteractionRoute[] = [
+    // --- TRADE MODULE ---
+    {
+        predicate: (i) => i.customId.startsWith("trade_") || i.customId === "amount",
+        handler: () => import("@/modules/trade/trade.interaction"),
+        method: 'handleTradeInteraction'
+    },
+
+    // --- ECONOMY MODULE ---
+    {
+        predicate: (i) => i.isButton() && i.customId.startsWith("shop_buy_"),
+        handler: () => import("@/modules/economy/shop.interaction"),
+        method: 'handleShopInteraction'
+    },
+    {
+        predicate: (i) => i.isButton() && i.customId.startsWith("lootdrop_"),
+        handler: () => import("@/modules/economy/lootdrop.interaction"),
+        method: 'handleLootdropInteraction'
+    },
+
+    // --- ADMIN MODULE ---
+    {
+        predicate: (i) => i.customId.startsWith("createitem_"),
+        handler: () => import("@/modules/admin/item_wizard"),
+        method: 'handleItemWizardInteraction'
+    },
+
+    // --- USER MODULE ---
+    {
+        predicate: (i) => i.isButton() && i.customId === "enrollment",
+        handler: () => import("@/modules/user/enrollment.interaction"),
+        method: 'handleEnrollmentInteraction'
+    },
+
+    // --- FEEDBACK MODULE ---
+    {
+        predicate: (i) => i.customId.startsWith("feedback_"),
+        handler: () => import("@/modules/feedback/feedback.interaction"),
+        method: 'handleFeedbackInteraction'
+    }
+];

bot/lib/loaders/CommandLoader.ts

@@ -0,0 +1,111 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { Command } from "@shared/lib/types";
+import { config } from "@lib/config";
+import type { LoadResult, LoadError } from "./types";
+import type { Client } from "../BotClient";
+ 
+
+/**
+ * Handles loading commands from the file system
+ */
+export class CommandLoader {
+    private client: Client;
+
+    constructor(client: Client) {
+        this.client = client;
+    }
+
+    /**
+     * Load commands from a directory recursively
+     */
+    async loadFromDirectory(dir: string, reload: boolean = false): Promise<LoadResult> {
+        const result: LoadResult = { loaded: 0, skipped: 0, errors: [] };
+        await this.scanDirectory(dir, reload, result);
+        return result;
+    }
+
+    /**
+     * Recursively scan directory for command files
+     */
+    private async scanDirectory(dir: string, reload: boolean, result: LoadResult): Promise<void> {
+        try {
+            const files = await readdir(dir, { withFileTypes: true });
+
+            for (const file of files) {
+                const filePath = join(dir, file.name);
+
+                if (file.isDirectory()) {
+                    await this.scanDirectory(filePath, reload, result);
+                    continue;
+                }
+
+                if ((!file.name.endsWith('.ts') && !file.name.endsWith('.js')) || file.name.endsWith('.test.ts') || file.name.endsWith('.spec.ts')) continue;
+
+                await this.loadCommandFile(filePath, reload, result);
+            }
+        } catch (error) {
+            console.error(`Error reading directory ${dir}:`, error);
+            result.errors.push({ file: dir, error });
+        }
+    }
+
+    /**
+     * Load a single command file
+     */
+    private async loadCommandFile(filePath: string, reload: boolean, result: LoadResult): Promise<void> {
+        try {
+            const importPath = reload ? `${filePath}?t=${Date.now()}` : filePath;
+            const commandModule = await import(importPath);
+            const commands = Object.values(commandModule);
+
+            if (commands.length === 0) {
+                console.warn(`No commands found in ${filePath}`);
+                result.skipped++;
+                return;
+            }
+
+            const category = this.extractCategory(filePath);
+
+            for (const command of commands) {
+                if (this.isValidCommand(command)) {
+                    command.category = category;
+
+                    const isEnabled = config.commands[command.data.name] !== false;
+
+                    if (!isEnabled) {
+                        console.log(`🚫 Skipping disabled command: ${command.data.name}`);
+                        result.skipped++;
+                        continue;
+                    }
+
+                    this.client.commands.set(command.data.name, command);
+                    console.log(`Loaded command: ${command.data.name}`);
+                    result.loaded++;
+                } else {
+                    console.warn(`Skipping invalid command in ${filePath}`);
+                    result.skipped++;
+                }
+            }
+        } catch (error) {
+            console.error(`Failed to load command from ${filePath}:`, error);
+            result.errors.push({ file: filePath, error });
+        }
+    }
+
+    /**
+     * Extract category from file path
+     * e.g., /path/to/commands/admin/features.ts -> "admin"
+     */
+    private extractCategory(filePath: string): string {
+        const pathParts = filePath.split('/');
+        return pathParts[pathParts.length - 2] ?? "uncategorized";
+    }
+
+    /**
+     * Type guard to validate command structure
+     */
+    private isValidCommand(command: any): command is Command {
+        return command && typeof command === 'object' && 'data' in command && 'execute' in command;
+    }
+}

bot/lib/loaders/EventLoader.ts

@@ -0,0 +1,85 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { Event } from "@shared/lib/types";
+import type { LoadResult } from "./types";
+import type { Client } from "../BotClient";
+ 
+
+/**
+ * Handles loading events from the file system
+ */
+export class EventLoader {
+    private client: Client;
+
+    constructor(client: Client) {
+        this.client = client;
+    }
+
+    /**
+     * Load events from a directory recursively
+     */
+    async loadFromDirectory(dir: string, reload: boolean = false): Promise<LoadResult> {
+        const result: LoadResult = { loaded: 0, skipped: 0, errors: [] };
+        await this.scanDirectory(dir, reload, result);
+        return result;
+    }
+
+    /**
+     * Recursively scan directory for event files
+     */
+    private async scanDirectory(dir: string, reload: boolean, result: LoadResult): Promise<void> {
+        try {
+            const files = await readdir(dir, { withFileTypes: true });
+
+            for (const file of files) {
+                const filePath = join(dir, file.name);
+
+                if (file.isDirectory()) {
+                    await this.scanDirectory(filePath, reload, result);
+                    continue;
+                }
+
+                if (!file.name.endsWith('.ts') && !file.name.endsWith('.js')) continue;
+
+                await this.loadEventFile(filePath, reload, result);
+            }
+        } catch (error) {
+            console.error(`Error reading directory ${dir}:`, error);
+            result.errors.push({ file: dir, error });
+        }
+    }
+
+    /**
+     * Load a single event file
+     */
+    private async loadEventFile(filePath: string, reload: boolean, result: LoadResult): Promise<void> {
+        try {
+            const importPath = reload ? `${filePath}?t=${Date.now()}` : filePath;
+            const eventModule = await import(importPath);
+            const event = eventModule.default;
+
+            if (this.isValidEvent(event)) {
+                if (event.once) {
+                    this.client.once(event.name, (...args) => event.execute(...args));
+                } else {
+                    this.client.on(event.name, (...args) => event.execute(...args));
+                }
+                console.log(`Loaded event: ${event.name}`);
+                result.loaded++;
+            } else {
+                console.warn(`Skipping invalid event in ${filePath}`);
+                result.skipped++;
+            }
+        } catch (error) {
+            console.error(`Failed to load event from ${filePath}:`, error);
+            result.errors.push({ file: filePath, error });
+        }
+    }
+
+    /**
+     * Type guard to validate event structure
+     */
+    private isValidEvent(event: any): event is Event<any> {
+        return event && typeof event === 'object' && 'name' in event && 'execute' in event;
+    }
+}

bot/lib/loaders/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Result of loading commands or events
+ */
+export interface LoadResult {
+    loaded: number;
+    skipped: number;
+    errors: LoadError[];
+}
+
+/**
+ * Error that occurred during loading
+ */
+export interface LoadError {
+    file: string;
+    error: unknown;
+}

bot/lib/shutdown.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { isShuttingDown, setShuttingDown, incrementTransactions, decrementTransactions, getActiveTransactions, waitForTransactions } from "./shutdown";
+
+describe("shutdown logic", () => {
+    beforeEach(() => {
+        setShuttingDown(false);
+        while (getActiveTransactions() > 0) {
+            decrementTransactions();
+        }
+    });
+
+    it("should initialize with shuttingDown as false", () => {
+        expect(isShuttingDown()).toBe(false);
+    });
+
+    it("should update shuttingDown state", () => {
+        setShuttingDown(true);
+        expect(isShuttingDown()).toBe(true);
+    });
+
+    it("should track active transactions", () => {
+        expect(getActiveTransactions()).toBe(0);
+        incrementTransactions();
+        expect(getActiveTransactions()).toBe(1);
+        decrementTransactions();
+        expect(getActiveTransactions()).toBe(0);
+    });
+
+    it("should wait for transactions to complete", async () => {
+        incrementTransactions();
+
+        const start = Date.now();
+        const waitPromise = waitForTransactions(1000);
+
+        // Simulate completion after 200ms
+        setTimeout(() => {
+            decrementTransactions();
+        }, 200);
+
+        await waitPromise;
+        const duration = Date.now() - start;
+
+        expect(duration).toBeGreaterThanOrEqual(200);
+        expect(getActiveTransactions()).toBe(0);
+    });
+
+    it("should timeout if transactions never complete", async () => {
+        incrementTransactions();
+        const start = Date.now();
+        await waitForTransactions(500);
+        const duration = Date.now() - start;
+
+        expect(duration).toBeGreaterThanOrEqual(500);
+        expect(getActiveTransactions()).toBe(1); // Still 1 because we didn't decrement
+    });
+});

bot/lib/shutdown.ts

@@ -0,0 +1,30 @@
+ 
+
+let shuttingDown = false;
+let activeTransactions = 0;
+
+export const isShuttingDown = () => shuttingDown;
+export const setShuttingDown = (value: boolean) => {
+    shuttingDown = value;
+};
+
+export const incrementTransactions = () => {
+    activeTransactions++;
+};
+
+export const decrementTransactions = () => {
+    activeTransactions--;
+};
+
+export const getActiveTransactions = () => activeTransactions;
+
+export const waitForTransactions = async (timeoutMs: number = 10000) => {
+    const start = Date.now();
+    while (activeTransactions > 0) {
+        if (Date.now() - start > timeoutMs) {
+            console.warn(`Shutdown timed out waiting for ${activeTransactions} transactions after ${timeoutMs}ms`);
+            break;
+        }
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+};

bot/lib/webhookUtils.ts

@@ -0,0 +1,56 @@
+import { type TextBasedChannel, User } from 'discord.js';
+
+/**
+ * Sends a message to a channel using a temporary webhook (imitating the bot or custom persona).
+ * 
+ * @param channel The channel to send the message to (must support webhooks).
+ * @param payload The message payload (string content or JSON object for embeds/options).
+ * @param clientUser The client user (bot) to fallback for avatar/name if not specified in payload.
+ * @param reason The reason for creating the webhook (for audit logs).
+ */
+export async function sendWebhookMessage(
+    channel: TextBasedChannel,
+    payload: any,
+    clientUser: User,
+    reason: string
+): Promise<void> {
+
+    if (!('createWebhook' in channel)) {
+        throw new Error("Channel does not support webhooks.");
+    }
+
+    // Normalize payload if it's just a string, wrap it in content
+    if (typeof payload === 'string') {
+        payload = { content: payload };
+    }
+
+    let webhook;
+    try {
+        webhook = await channel.createWebhook({
+            name: payload.username || `${clientUser.username}`, // Use payload name or bot name
+            avatar: payload.avatar_url || payload.avatarURL || clientUser.displayAvatarURL(),
+            reason: reason
+        });
+
+        // Support snake_case keys for raw API compatibility if passed from config
+        if (payload.avatar_url && !payload.avatarURL) {
+            payload.avatarURL = payload.avatar_url;
+            delete payload.avatar_url;
+        }
+
+        await webhook.send(payload);
+
+        await webhook.delete(reason);
+
+    } catch (error) {
+        // Attempt cleanup if webhook was created but sending failed
+        if (webhook) {
+            try {
+                await webhook.delete("Cleanup after failure");
+            } catch (cleanupError) {
+                console.error("Failed to delete webhook during cleanup:", cleanupError);
+            }
+        }
+        throw error;
+    }
+}