Project Structure

Understanding your BotBox project layout is key to building and maintaining scalable Discord bots.

Default Layout

When you create a new project with botbox create, you’ll get a structure like this:

plaintext

your-bot/
├── README.md
├── botbox.conf
├── requirements.txt
├── run.sh
├── .env (or doppler.yaml)
├── .gitignore
├── LICENSE
├── src/
│   ├── main.py
│   ├── cogs/
│   │   ├── __init__.py
│   │   ├── helloWorld.py
│   │   └── cogs.py
│   └── utils/
│       ├── __init__.py
│       └── logger.py

What’s in Each File?

File/Folder	Purpose
`README.md`	Project overview and usage instructions
`botbox.conf`	Main project configuration (bot info, cogs, etc.)
`requirements.txt`	Python dependencies (`discord.py`, `python-dotenv`)
`run.sh`	Script to run your bot (handles env setup)
`.env`/`doppler.yaml`	Environment variable configuration
`.gitignore`	Ignores `logs/`, `.env`, `__pycache__/`, `*.pyc`, and `venv/`
`LICENSE`	Your chosen license
`src/`	All source code for your bot
`src/main.py`	Main entry point for your Discord bot
`src/cogs/`	Folder for all your cogs (modular bot features)
`src/cogs/__init__.py`	Makes `cogs` a Python package
`src/cogs/helloWorld.py`	Example cog (safe to remove)
`src/cogs/cogs.py`	Cog management commands (reload, list, etc.)
`src/utils/`	Shared helpers used by your bot
`src/utils/__init__.py`	Makes `utils` a Python package
`src/utils/logger.py`	Logging setup, controlled by `LOG_LEVEL` and `LOG_DIR`

📝 NOTE

requirements.txt and .gitignore are generated as of 2.6.3, and src/utils/ with the logger as of 2.7.0. Older projects will not have them, and botbox project upgrade only rewrites botbox.conf, so add them by hand if you need them.

Note that .gitignore ignores .env, so your token never ends up in git as long as you keep your secrets there.

Example: `botbox.conf`

This file controls your bot’s metadata and which cogs are loaded.

json

{
  "botbox": {
    "version": "2.7.0"
  },
  "bot": {
    "name": "My Awesome Bot",
    "command_prefix": "!",
    "author": "Your Name",
    "description": "A really cool bot!"
  },
  "cogs": [
    {
      "name": "HelloWorld",
      "file": "helloWorld",
      "env": "development",
      "slash_commands": [
        {
          "Name": "hello",
          "Scope": "guild",
          "Type": "slash",
          "Description": "Bot responds with world",
          "Args": [],
          "ReturnType": "None"
        }
      ],
      "prefix_commands": []
    }
  ]
}

Example: .env File

env

DISCORD_TOKEN=your-bot-token-here
DISCORD_GUILD=your-guild-id-here
ENVIRONMENTS=production,development
LOG_LEVEL=INFO
LOG_DIR=logs

The ENVIRONMENTS variable controls which cogs are loaded based on their env field in botbox.conf.
For example, if ENVIRONMENTS=production, only cogs with "env": "production" will be loaded.

Adding and Removing Cogs

Add a cog:
Run botbox add and follow the prompts.
The new cog will appear in src/cogs/ and be registered in botbox.conf.
Remove a cog:
Run botbox remove to safely delete a cog and update your config.

Customizing Your Project

You can add more files, folders, or Python modules as needed.
Just keep your cogs in src/cogs/ and update botbox.conf if you add or remove them manually.