# Project Structure

Overview of the **gmail-bridge** project layout and the role of each file and directory.

---

## Root

| File / Dir | Purpose |
|------------|--------|
| `zammad-discord.js` | **Entry point.** Main Discord bot + Gmail bridge process. |
| `config.js` | Configuration loading (env, defaults). |
| `db-connection.js` | MongoDB connection setup. |
| `models.js` | Mongoose models (e.g. guild settings, tickets). |
| `utils.js` | Shared utilities. |
| `gmail-poll.js` | Gmail polling / inbox sync logic. |
| `game-options.json` | Game-related options (e.g. for slash commands). |
| `package.json` | Dependencies and npm scripts. |
| `.env.example` | Example environment variables. |
| `.gitignore` | Git ignore rules. |

---

## Directories

### `commands/`

Slash-command registration and definitions.

| File | Purpose |
|------|--------|
| `register.js` | Registers Discord slash commands (e.g. `/ticket`, `/setup`). |

---

### `handlers/`

Event and interaction handlers for the Discord bot.

| File | Purpose |
|------|--------|
| `accountinfo.js` | Account / user info commands or logic. |
| `analytics.js` | Analytics or stats handling. |
| `buttons.js` | Discord button interaction handlers. |
| `commands.js` | Slash command execution routing. |
| `messages.js` | Message events (e.g. DMs, channel messages). |
| `setup.js` | Setup / configuration flow (e.g. guild setup). |

---

### `services/`

Core business logic and external integrations.

| File | Purpose |
|------|--------|
| `debugLog.js` | Debug / structured logging. |
| `gmail.js` | Gmail API integration (read/send, labels). |
| `guildSettings.js` | Guild-specific settings (DB + cache). |
| `tickets.js` | Ticket lifecycle (create, update, link to Zammad). |
| `zammad.js` | Zammad API client (tickets, users, articles). |
| `zammad-sync.js` | Sync logic between Discord and Zammad. |

---

### `utils/`

Helper modules used across the app.

| File | Purpose |
|------|--------|
| `ticketComponents.js` | Discord components (buttons, selects) for ticket flows. |

---

### `scripts/`

One-off or maintenance scripts.

| File | Purpose |
|------|--------|
| `create-zammad-objects.js` | Creates required objects in Zammad (run via `npm run create-zammad-objects`). |

---

### `docs/`

Documentation and reference files.

| File | Purpose |
|------|--------|
| `MONGODB_ZAMMAD_LINK.md` | How MongoDB and Zammad are linked. |
| `schema zammad.txt` | Zammad schema or object reference. |

---

## Documentation (root)

| File | Purpose |
|------|--------|
| `README.md` | Main project readme. |
| `QUICKSTART.md` | Quick start / setup guide. |
| `FEATURES_SUMMARY.md` | Feature overview. |
| `IMPLEMENTATION_SUMMARY.md` | Implementation notes. |
| `PHASE_FEATURES.md` | Phased feature list. |
| `MONGODB_SETUP.md` | MongoDB setup instructions. |
| `NEW_FEATURES.md` | New features changelog. |
| `UPGRADE_COMPLETE.md` | Upgrade completion notes. |
| `DISCORD_API_VALIDATION.md` | Discord API validation details. |
| `DISCORD_API_IMPROVEMENTS.md` | Discord API improvements. |
| `PROJECT_STRUCTURE.md` | This file. |

---

## Tree View

```
gmail-bridge/
├── zammad-discord.js      # Entry point
├── config.js
├── db-connection.js
├── models.js
├── utils.js
├── gmail-poll.js
├── game-options.json
├── package.json
├── .env.example
├── .gitignore
├── commands/
│   └── register.js
├── handlers/
│   ├── accountinfo.js
│   ├── analytics.js
│   ├── buttons.js
│   ├── commands.js
│   ├── messages.js
│   └── setup.js
├── services/
│   ├── debugLog.js
│   ├── gmail.js
│   ├── guildSettings.js
│   ├── tickets.js
│   ├── zammad.js
│   └── zammad-sync.js
├── utils/
│   └── ticketComponents.js
├── scripts/
│   └── create-zammad-objects.js
├── docs/
│   ├── MONGODB_ZAMMAD_LINK.md
│   └── schema zammad.txt
└── *.md                   # Root documentation files
```

---

## Run

- **Start bot:** `npm start` → runs `node zammad-discord.js`
- **Create Zammad objects:** `npm run create-zammad-objects` → runs `node scripts/create-zammad-objects.js`