broccolini-bot/PROJECT_STRUCTURE.md

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