broccolini-bot/docs/setup/PROJECT_STRUCTURE.md

Project Structure

Overview of the Broccolini Bot project layout and the role of each file and directory. Single-level repo: all paths are relative to the repo root.

---

Root

File / Dir	Purpose
broccolini-discord.js	Entry point. Main Discord bot 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 (copy to .env).
.env.test.example	Test env template (copy to .env.test; run with npm run start:test). See ENV_AND_SECURITY.md.
.gitignore	Git ignore rules (.env and .env.test never committed).

---

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, auto-close, reminders).

---

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
backup-env.js	Copies .env to .env.backup (run via node scripts/backup-env.js).
test-mongodb.js	Tests MongoDB connection (run via npm run test-mongodb).

---

docs/

Documentation and reference files (all paths below relative to repo root).

File	Purpose
ENV_AND_SECURITY.md	Test env workflow, security checklist, agent rules.
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.
PROPOSAL.md	Roadmap and possible next steps (API, routing, bOSScord).
PROJECT_STRUCTURE.md	This file.

---

Tree View

broccolini-bot/
├── broccolini-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
├── utils/
│   └── ticketComponents.js
├── scripts/
│   ├── backup-env.js
│   └── test-mongodb.js
├── docs/                  # All .md docs except README.md
│   ├── ENV_AND_SECURITY.md
│   ├── QUICKSTART.md
│   ├── MONGODB_SETUP.md
│   └── ... (see table above)
└── README.md

---

Run

• Start bot: npm start → runs node broccolini-discord.js
• Backup .env: node scripts/backup-env.js → copies .env to .env.backup
• Test MongoDB: npm run test-mongodb → runs node scripts/test-mongodb.js