First upload
This commit is contained in:
samkintop
154
docs/setup/PROJECT_STRUCTURE.md
Normal file
154
docs/setup/PROJECT_STRUCTURE.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# 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](./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`
|
||||
Reference in New Issue
Block a user