From 00613b3a4fb3746da99bcc8a8f8836330eb4345f Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 11 Apr 2026 08:10:24 +0000 Subject: [PATCH] Update skills: Arbiter and Discord automation Arbiter skill (NEW): - Architecture overview - Deployment procedure with rsync excludes - Common mistakes (including temp/ directory warning) - Route patterns for Trinity Console - Database access commands - Debugging commands Discord skill (UPDATED): - Added social-metrics channel/webhook - Replaced TBD placeholders with real IDs - Guild ID: 1260574715546701936 - Social Metrics webhook documented Chronicler #76 --- docs/skills/arbiter/SKILL.md | 268 +++++++++++++++++++++++ docs/skills/discord-automation/README.md | 16 +- docs/skills/discord-automation/SKILL.md | 7 + 3 files changed, 285 insertions(+), 6 deletions(-) create mode 100644 docs/skills/arbiter/SKILL.md diff --git a/docs/skills/arbiter/SKILL.md b/docs/skills/arbiter/SKILL.md new file mode 100644 index 0000000..9ea40d8 --- /dev/null +++ b/docs/skills/arbiter/SKILL.md @@ -0,0 +1,268 @@ +--- +name: arbiter +description: | + Understand and work with Arbiter, the core backend for Firefrost Gaming. Use this skill whenever: + - Making changes to Arbiter code + - Adding API endpoints + - Working with Trinity Console + - Deploying updates to Command Center + - Debugging webhook or Discord issues + - Working with the PostgreSQL database + This skill prevents common mistakes and ensures proper deployment procedures. +--- + +# Arbiter Skill + +Arbiter is the Node.js/Express backend that powers Firefrost Gaming. It handles Stripe webhooks, Discord role management, the Trinity Console admin dashboard, social analytics, and internal APIs. + +--- + +## CRITICAL: Where Is The Code? + +**Active code:** `firefrost-services` repo → `services/arbiter-3.0/` + +**NOT here:** +- ❌ `services/arbiter/` — This is v2.0, ARCHIVED, do not use +- ❌ `services/_archived/` — Old stuff, historical reference only + +**Production location:** Command Center (63.143.34.217) → `/opt/arbiter-3.0/` + +--- + +## Architecture Overview + +``` +Arbiter 3.x +├── src/ +│ ├── index.js # Entry point +│ ├── routes/ +│ │ ├── admin/ # Trinity Console routes +│ │ │ ├── index.js # Dashboard, main admin routes +│ │ │ ├── subscribers.js +│ │ │ ├── social.js +│ │ │ └── ... +│ │ ├── api.js # Internal API (/api/internal/*) +│ │ ├── webhook.js # Stripe webhooks +│ │ └── oauth.js # Discord OAuth +│ ├── views/ +│ │ ├── admin/ # EJS templates for Trinity Console +│ │ └── partials/ +│ ├── public/ # Static assets (CSS, JS) +│ └── middleware/ +├── package.json +└── .env # NOT in git - on server only +``` + +--- + +## Key Endpoints + +| Route | Purpose | +|-------|---------| +| `/admin` | Trinity Console dashboard | +| `/admin/subscribers` | Subscriber management | +| `/admin/social` | Social analytics | +| `/admin/mcp-logs` | MCP command logs (Task #109) | +| `/api/internal/*` | Internal API (requires INTERNAL_API_TOKEN) | +| `/webhooks/stripe` | Stripe payment webhooks | +| `/oauth/discord/*` | Discord OAuth flow | + +--- + +## Database + +**PostgreSQL** on Command Center: +```bash +PGPASSWORD='FireFrost2026!Arbiter' psql -U arbiter -h 127.0.0.1 -d arbiter_db +``` + +**Key tables:** +- `subscribers` — Subscription records +- `social_posts` — Social media post tracking +- `social_snapshots` — Daily follower/engagement metrics +- `auth_requests` — Trinity Core approval queue (Task #111) + +--- + +## Environment Variables + +Located at `/opt/arbiter-3.0/.env` on Command Center (NOT in git): + +``` +# Core +PORT=3000 +NODE_ENV=production + +# Database +DATABASE_URL=postgresql://arbiter:xxx@localhost/arbiter_db + +# Discord +DISCORD_BOT_TOKEN=xxx +DISCORD_CLIENT_ID=xxx +DISCORD_CLIENT_SECRET=xxx +DISCORD_GUILD_ID=xxx + +# Stripe +STRIPE_SECRET_KEY=xxx +STRIPE_WEBHOOK_SECRET=xxx + +# Internal API +INTERNAL_API_TOKEN=6fYF1akCRW6pM2F8n3S3RxeIod4YgRniUJNEQurvBP4= + +# Session +SESSION_SECRET=xxx +``` + +--- + +## Deployment Procedure + +**IMPORTANT:** Arbiter is NOT a git repo on the server. Do not `git pull` in `/opt/arbiter-3.0/`. + +### Standard Deploy + +1. Clone `firefrost-services` to temp location: +```bash +cd /tmp +git clone https://TOKEN@git.firefrostgaming.com/firefrost-gaming/firefrost-services.git +``` + +2. Copy arbiter-3.0 files (preserve .env and temp): +```bash +rsync -av --exclude='.env' --exclude='node_modules' --exclude='temp' \ + /tmp/firefrost-services/services/arbiter-3.0/ /opt/arbiter-3.0/ +``` + +3. Install dependencies if package.json changed: +```bash +cd /opt/arbiter-3.0 +npm install +``` + +4. Restart service: +```bash +sudo systemctl restart arbiter-3 +``` + +5. Verify: +```bash +sudo systemctl status arbiter-3 +curl http://localhost:3000/health +``` + +6. Cleanup: +```bash +rm -rf /tmp/firefrost-services +``` + +### Deploy Script + +There's a helper script at `/opt/scripts/deploy-arbiter.sh` on Command Center. + +--- + +## Adding New Routes + +### Admin Route (Trinity Console page) + +1. Create route file: `src/routes/admin/newfeature.js` +2. Register in `src/routes/admin/index.js`: +```javascript +const newfeatureRoutes = require('./newfeature'); +router.use('/newfeature', newfeatureRoutes); +``` +3. Create view: `src/views/admin/newfeature.ejs` +4. Add nav link in `src/views/partials/header.ejs` + +### Internal API Endpoint + +Add to `src/routes/api.js`: +```javascript +router.post('/internal/newfeature', authenticateInternal, async (req, res) => { + // Your logic here +}); +``` + +Call with: +```bash +curl -X POST https://discord-bot.firefrostgaming.com/api/internal/newfeature \ + -H "X-Internal-Token: 6fYF1akCRW6pM2F8n3S3RxeIod4YgRniUJNEQurvBP4=" \ + -H "Content-Type: application/json" \ + -d '{"key": "value"}' +``` + +--- + +## Common Mistakes + +### ❌ Editing /opt/arbiter-3.0 directly +Changes will be lost on next deploy. Always edit in `firefrost-services` repo. + +### ❌ Looking at services/arbiter/ (no -3.0) +That's the archived v2.0 code. It's obsolete. + +### ❌ Forgetting to exclude temp/ in rsync +The `temp/` directory on production holds runtime files (exports, uploads, etc.). Always exclude it: +```bash +rsync -av --exclude='.env' --exclude='node_modules' --exclude='temp' ... +``` + +### ❌ Forgetting to restart after deploy +```bash +sudo systemctl restart arbiter-3 +``` + +### ❌ Committing .env to git +Never. It contains secrets. + +### ❌ Using wrong route file +- Dashboard/main pages: `src/routes/admin/index.js` +- NOT `src/routes/admin.js` (that file may not exist or is legacy) + +--- + +## Debugging + +### Check logs +```bash +sudo journalctl -u arbiter-3 -f +``` + +### Check if running +```bash +sudo systemctl status arbiter-3 +``` + +### Test health endpoint +```bash +curl http://localhost:3000/health +``` + +### Database query +```bash +PGPASSWORD='FireFrost2026!Arbiter' psql -U arbiter -h 127.0.0.1 -d arbiter_db -c "SELECT * FROM subscribers LIMIT 5;" +``` + +--- + +## Related Tasks + +- Task #87: Lifecycle handlers (cancellation, grace period) +- Task #109: MCP Logging in Trinity Console +- Task #111: Trinity Core approval flow integration + +--- + +## Service Details + +| Property | Value | +|----------|-------| +| Service name | `arbiter-3` | +| User | `root` (runs as) | +| Port | 3000 | +| Proxy | nginx → discord-bot.firefrostgaming.com | +| Node version | 20.x | + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️ diff --git a/docs/skills/discord-automation/README.md b/docs/skills/discord-automation/README.md index 6b3675a..f944d3b 100644 --- a/docs/skills/discord-automation/README.md +++ b/docs/skills/discord-automation/README.md @@ -64,14 +64,18 @@ Use **Discord Automation (Rube MCP)**: ## Firefrost Discord IDs -*(Add your IDs here once collected)* - | Entity | ID | Notes | |--------|-----|-------| -| Firefrost Guild | TBD | Main server | -| General Channel | TBD | — | -| Announcements | TBD | — | -| Staff Channel | TBD | — | +| Firefrost Guild | 1260574715546701936 | Main server | +| General Channel | 1260574716058664962 | #general-chat | +| Announcements | 1403980849686515832 | #announcements | +| Social Metrics | 1492272448941326507 | Webhook channel for bot posts | + +### Active Webhooks + +| Webhook | Channel | URL | +|---------|---------|-----| +| Social Metrics | #social-metrics | `https://discord.com/api/webhooks/1492272448941326507/a3ItVKmZ8B1MRMK7KNz7YPtNb7UYWnnYLBNMmGtS_jt7hklmzOdsg87zIGZHbkRnW3QH` | --- diff --git a/docs/skills/discord-automation/SKILL.md b/docs/skills/discord-automation/SKILL.md index a69c2b1..2fddab7 100644 --- a/docs/skills/discord-automation/SKILL.md +++ b/docs/skills/discord-automation/SKILL.md @@ -46,6 +46,13 @@ DISCORD_CLIENT_ID=1487080166969577502 | general-chat | 1260574716058664962 | | announcements | 1403980849686515832 | | 📚-guides (forum) | 1491804184356454430 | +| social-metrics | 1492272448941326507 | + +### Webhooks + +| Webhook | URL | +|---------|-----| +| social-metrics | `https://discord.com/api/webhooks/1492272448941326507/a3ItVKmZ8B1MRMK7KNz7YPtNb7UYWnnYLBNMmGtS_jt7hklmzOdsg87zIGZHbkRnW3QH` | ---