> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breezehost.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# File Structure

> How to organize your bot files so they work correctly on Breeze Hosting.

# File Structure

One of the most common reasons a bot fails to start is an incorrect file structure. The Pterodactyl panel expects your **main entry file to be at the root level** of the file manager — not nested inside subfolders.

## The Golden Rule

<Warning>
  Your main file (`bot.py`, `index.js`, `main.py`, etc.) **must** be at the root of the file manager. If it's inside a subfolder, the server won't find it and your bot won't start.
</Warning>

## Correct vs. Incorrect Structure

### Correct

Your entry file and dependency files sit directly at the root:

```
/
├── bot.py              <-- entry file at root
├── requirements.txt
├── .env
├── cogs/
│   ├── moderation.py
│   └── fun.py
└── utils/
    └── helpers.py
```

```
/
├── index.js            <-- entry file at root
├── package.json
├── .env
├── commands/
│   ├── ping.js
│   └── help.js
└── events/
    └── ready.js
```

### Incorrect

The entry file is buried inside a subfolder — this **will not work**:

```
/
└── my-bot/              <-- extra folder wrapping everything
    ├── bot.py
    ├── requirements.txt
    └── cogs/
        └── moderation.py
```

```
/
└── src/                 <-- entry file nested in src/
    ├── index.js
    ├── commands/
    └── events/
```

In both cases, the startup command (`python bot.py` or `node index.js`) will fail because the file isn't where the server expects it.

## Why Does This Happen?

This usually happens when you upload a **zip archive** that was created from a parent folder. For example, if you zip a folder called `my-bot/`, the archive will contain:

```
my-bot/
├── bot.py
├── requirements.txt
└── ...
```

When you unarchive it on the server, everything ends up inside `my-bot/` instead of at the root.

## How to Fix It

### If your files are already in a subfolder on the server

<Steps>
  <Step title="Open the File Manager">
    Go to your server on [panel.breezehost.xyz](https://panel.breezehost.xyz) and click the **Files** tab.
  </Step>

  <Step title="Navigate into the subfolder">
    Click into the subfolder that contains your bot files (e.g., `my-bot/`).
  </Step>

  <Step title="Select all files">
    Select all the files and folders inside.
  </Step>

  <Step title="Move them to root">
    Use the **Move** option and set the destination to `/` (the root directory).
  </Step>

  <Step title="Delete the empty folder">
    Go back to root and delete the now-empty subfolder.
  </Step>
</Steps>

### When creating zip archives

To avoid this problem in the first place, zip the **contents** of your project folder, not the folder itself:

**On Windows**: Open your project folder, select all files inside, right-click > **Compress to ZIP file**.

**On macOS**: Open your project folder, select all files inside, right-click > **Compress**.

**On Linux / terminal**:

```bash theme={null}
# Correct — zip the contents, not the folder
cd my-bot
zip -r ../my-bot.zip .

# Incorrect — this creates a nested folder in the zip
zip -r my-bot.zip my-bot/
```

<Tip>
  The key difference: navigate **into** your project folder first, then zip everything from there. Don't zip the folder from outside it.
</Tip>

## What About Subfolders for Cogs, Commands, etc.?

Subfolders are perfectly fine for organizing your code — the rule only applies to your **main entry file** and **dependency files** (`requirements.txt`, `package.json`, `.env`). These must be at the root.

Your cogs, commands, events, utilities, and any other modules can be organized in whatever subfolder structure you prefer:

```
/
├── bot.py              <-- root
├── requirements.txt    <-- root
├── .env                <-- root
├── cogs/               <-- subfolder is fine
│   ├── moderation.py
│   ├── music.py
│   └── economy.py
├── utils/              <-- subfolder is fine
│   ├── database.py
│   └── helpers.py
└── data/               <-- subfolder is fine
    └── config.yaml
```

## Checklist

Before starting your server, verify:

* [ ] Your main file (`bot.py`, `index.js`, etc.) is at the root of the file manager
* [ ] `requirements.txt` (Python) or `package.json` (JavaScript) is at the root
* [ ] Your `.env` or config file is at the root
* [ ] The startup command in **Settings > Startup** matches the filename of your root-level entry file
* [ ] No unnecessary parent folder is wrapping your entire project