GiveawayBot project structure reference

GiveawayBot is organized as a standard Discord.js TypeScript project: source files live in src/, get compiled into build/ by the TypeScript toolchain, and are loaded at runtime by two auto-discovery handlers. The sections below walk through every directory and file so you know exactly where to look when reading or modifying the bot.

Directory tree

giveawaybot/
├── .env                        # Environment variables (not committed)
├── .env.example                # Template for required env vars
├── build.js                    # Custom build script (tsc wrapper)
├── package.json                # Dependencies and npm scripts
├── tsconfig.json               # TypeScript compiler options
└── src/
    ├── index.ts                # Bot entry point
    ├── types.d.ts              # Global TypeScript interfaces
    ├── functions.ts            # Shared utility functions
    ├── commands/
    │   ├── config.ts           # /gconfig command
    │   ├── gCreate.ts          # /gcreate command
    │   ├── gEnd.ts             # /gend command
    │   ├── gReRoll.ts          # /greroll command
    │   └── ping.ts             # /ping command
    ├── events/
    │   ├── guildCreate.ts      # Fires when bot joins a guild
    │   ├── interactionCreate.ts# Routes all Discord interactions
    │   └── ready.ts            # Fires once on bot login
    ├── database/
    │   ├── dbManager.ts        # Base DatabaseManager class
    │   ├── guildManager.ts     # GuildManager (guilds table)
    │   ├── gwManager.ts        # GiveawayManager (giveaways table)
    │   └── data/
    │       └── database.db     # SQLite database file (runtime artifact)
    └── handlers/
        ├── Command.ts          # Auto-loads slash commands
        └── Event.ts            # Auto-loads event listeners

The build/ directory is generated automatically when you run npm run build. It contains compiled JavaScript and should never be edited by hand — any changes will be overwritten on the next build.

Root files

File	Purpose
`index.ts`	Creates the Discord.js `Client`, loads the command and event handlers, then calls `client.login()`. This is the single entry point for the bot process.
`types.d.ts`	Declares the `SlashCommand` and `BotEvent` interfaces used across all command and event files, and extends `ProcessEnv` to type-check environment variables.
`functions.ts`	Exports shared helpers: `parseDuration` (converts duration strings like `5m` to a number of seconds), `processGiveaways` (the interval function that ends expired giveaways and picks winners), `color` (chalk color helpers for console output), `checkPermissions` (validates bot permissions in a channel), and `sendTimedMessage` (sends a message that auto-deletes after a delay).
`build.js`	A lightweight Node.js script invoked by `npm run build`. It calls the TypeScript compiler (`tsc`) and copies any non-TS assets to `build/`.
`package.json`	Defines two scripts: `npm run build` compiles the source, and `npm start` runs `node build/index.js`.
`.env` / `.env.example`	`.env.example` documents the two required environment variables. Copy it to `.env` and fill in your values before starting the bot.

src/commands/

Each file exports a SlashCommand object that conforms to the interface in types.d.ts. The Command.ts handler discovers and registers these automatically — no manual imports required.

File	Command	Description
`config.ts`	`/gconfig`	Guild-level configuration command. Allows server admins to view and update the embed color, entry emoji, and @everyone ping setting stored in the guilds table.
`gCreate.ts`	`/gcreate`	Creates a new giveaway. Accepts duration, prize, and winner count, writes a row to the giveaways table, and posts the giveaway embed with a reaction button.
`gEnd.ts`	`/gend`	Manually ends an active giveaway before its scheduled time, triggering winner selection immediately.
`gReRoll.ts`	`/greroll`	Re-rolls winners for a completed giveaway, picking a new set of participants from the original entry pool.
`ping.ts`	`/ping`	Utility command that replies with the bot’s current WebSocket ping (`client.ws.ping`) and uptime in minutes. Useful for verifying the bot is responsive.

src/events/

Each file exports a BotEvent object. The Event.ts handler registers these as Discord.js event listeners at startup.

File	Event	Description
`guildCreate.ts`	`guildCreate`	Fires when the bot is added to a new server. Creates the corresponding row in the `guilds` table so guild-specific settings can be stored.
`interactionCreate.ts`	`interactionCreate`	The central interaction router. Handles slash command dispatching, button interactions (giveaway entries), autocomplete responses, and modal submissions by inspecting the incoming `Interaction` object and delegating to the correct handler.
`ready.ts`	`ready`	Fires once after the bot successfully logs in. Sets the bot’s Discord status/activity, then starts the `processGiveaways` interval that checks for and ends expired giveaways every 1000 ms.

src/database/

GiveawayBot uses SQLite via better-sqlite3 for zero-dependency persistent storage. All database access goes through typed manager classes.

File	Description
`dbManager.ts`	`DatabaseManager` — abstract base class that opens the SQLite connection and exposes low-level query helpers. All manager classes extend this.
`guildManager.ts`	`GuildManager` — manages the `guilds` table. Handles creating a guild record on join, reading guild config, and updating settings via `/gconfig`.
`gwManager.ts`	`GiveawayManager` — manages the `giveaways` table. Handles inserting new giveaways, querying active giveaways for the interval check, marking giveaways as ended, and storing winner data.
`data/database.db`	The SQLite database file. Created automatically at runtime if it does not exist. This file should be excluded from version control (it is listed in `.gitignore`).

src/handlers/

The two handler files implement auto-discovery, keeping index.ts free of explicit imports for every command and event.

File	Description
`Command.ts`	Reads every `.js` file from `build/commands/` at startup, imports the default export, validates it against the `SlashCommand` interface, and registers it on the `Client`. It also calls the Discord REST API to push application commands to Discord so they appear in the slash command menu.
`Event.ts`	Reads every `.js` file from `build/events/` at startup, imports the default export, and attaches it to the `Client` using `client.on()` or `client.once()` depending on the `BotEvent.once` flag.

Adding a new command or event is as simple as creating a new file in the appropriate src/ directory, running npm run build, and restarting the bot — no edits to index.ts are needed.

Get Started

Commands

Customization

Database

Reference

GiveawayBot project structure reference

Directory tree

Root files

src/commands/

src/events/

src/database/

src/handlers/

Build docs developers (and LLMs) love

Get Started

Commands

Customization

Database

Reference

Documentation Index

​Directory tree

​Root files

​src/commands/

​src/events/

​src/database/

​src/handlers/

Build docs developers (and LLMs) love

Directory tree

Root files

src/commands/

src/events/

src/database/

src/handlers/