firefrost-operations-manual/docs/reference/gemini-consultations/2026-03-31-arbiter-3-complete-code.md

Gemini AI Consultation: Arbiter 3.0 Complete Code Delivery

Date: March 31, 2026, 6:10pm CDT
Consultation Type: Complete Application Code Generation
Context: Soft launch blocker resolution (Tasks #87 + #90)
Outcome: 16 production-ready files, ~1500 lines of Node.js code

---

Request Summary

Asked Gemini to write complete production-ready Arbiter 3.0 application code based on architectural guidance from earlier consultations. Both subscription cancellation flow (Task #87) and whitelist management (Task #90) are Tier S soft launch blockers, so unified approach chosen over incremental deployment.

---

What Gemini Delivered

Complete Node.js 20 Application Structure

services/arbiter-3.0/
├── package.json (dependencies)
├── .env.example (all environment variables)
├── README.md (installation & deployment guide)
├── deploy/
│   └── arbiter-3.service (systemd service file)
└── src/
    ├── index.js (main entry: Express + Discord + cron)
    ├── database.js (PostgreSQL connection pool)
    ├── discord/
    │   ├── commands.js (/link slash command handler)
    │   └── events.js (Discord event registration)
    ├── webhooks/
    │   └── paymenter.js (subscription webhook handler)
    ├── panel/
    │   ├── discovery.js (Application API auto-discovery)
    │   ├── files.js (Client API file write)
    │   └── commands.js (Client API send command)
    ├── sync/
    │   ├── immediate.js (event-driven whitelist sync)
    │   └── cron.js (hourly reconciliation)
    ├── mojang/
    │   └── validate.js (Mojang API + UUID formatting)
    └── admin/
        └── routes.js (admin panel with basic auth)

Dependencies (package.json)

• discord.js ^14.14.1
• dotenv ^16.4.5
• express ^4.19.2
• node-cron ^3.0.3
• pg ^8.11.3

Core Features Implemented

1. Discord Bot with Slash Commands

• /link <minecraft_username> command
• Mojang API validation
• UUID formatting (adds dashes - Minecraft requirement)
• PostgreSQL storage
• Immediate whitelist sync trigger

2. Paymenter Webhook Handler

• Events: subscription_created, payment_success, subscription_cancelled
• Discord role assignment (TIERS configuration)
• Database updates (subscriptions table)
• Grace period status tracking

3. Pterodactyl Integration

• Auto-discovery via Application API (filter by nest="Minecraft")
• File write via Client API (Content-Type: text/plain)
• Whitelist reload command (handle HTTP 412 gracefully)
• Sequential processing to avoid rate limits

4. Master Whitelist Sync

• Query active + grace_period subscribers
• Generate whitelist.json with UUIDs (WITH DASHES)
• Push to all discovered servers
• Log success/failure to server_sync_log table

5. Sync Engine

• Event-driven: Immediate sync on /link or subscription change
• Cron-based: Hourly reconciliation at minute 0
• Sequential server processing (not parallel)
• Error handling per server (continues on failure)

6. Admin Panel (Express)

• Basic HTTP authentication (Trinity only)
• GET /admin/status - View sync logs and linked accounts
• POST /admin/force-sync - Trigger manual sync
• JSON responses for programmatic access

---

Critical Implementation Details (From Gemini)

Content-Type Must Be text/plain

headers: {
  'Content-Type': 'text/plain'  // NOT application/json
}

UUID Formatting (Mojang returns without dashes, Minecraft needs with)

function formatUUID(uuidStr) {
  return `${uuidStr.slice(0, 8)}-${uuidStr.slice(8, 12)}-${uuidStr.slice(12, 16)}-${uuidStr.slice(16, 20)}-${uuidStr.slice(20)}`;
}

HTTP 412 = Server Offline (NOT an error)

if (res.status === 412) {
  console.log(`[${serverIdentifier}] is offline. File saved for next boot.`);
  return true; // Continue, not throw
}

Sequential Processing (Prevent Rate Limiting)

for (const server of servers) {
  await writeWhitelistFile(server.identifier, players);
  await reloadWhitelistCommand(server.identifier);
  // Next server...
}
// NOT: await Promise.all(servers.map(...))

Application API for Discovery, Client API for Operations

• Discovery: /api/application/servers?include=allocations,node,nest
• File Write: /api/client/servers/{identifier}/files/write?file=whitelist.json
• Command: /api/client/servers/{identifier}/command

---

Grace Period Policy ("We Don't Kick People Out")

When payment fails:

1. Set subscription.status = 'grace_period'
2. Keep Discord roles for 3 days
3. After 3 days → Downgrade to Awakened tier ($0 permanent)
4. NEVER remove from whitelist entirely
5. If payment succeeds → Restore to active tier

Chargebacks = immediate permanent ban (different from payment failure)

---

Database Schema (PostgreSQL 15+)

users table:

• discord_id (PK, VARCHAR(255))
• minecraft_username (UNIQUE, VARCHAR(255))
• minecraft_uuid (UNIQUE, VARCHAR(255))
• created_at (TIMESTAMP)

subscriptions table:

• id (SERIAL PK)
• discord_id (FK → users.discord_id)
• tier_level (INT)
• status (VARCHAR(50): active, grace_period, cancelled)
• stripe_customer_id (VARCHAR(255))
• paymenter_order_id (VARCHAR(255))
• created_at, updated_at (TIMESTAMP)

server_sync_log table:

• server_identifier (PK, VARCHAR(50))
• last_successful_sync (TIMESTAMP)
• last_error (TEXT)
• is_online (BOOLEAN)

Indexes:

• idx_users_discord_id ON users(discord_id)
• idx_subscriptions_status ON subscriptions(status)

---

Subscription Tiers Configuration

const TIERS = {
  1: { name: 'Awakened', roleId: 'DISCORD_ROLE_ID_1', price: 1 },
  5: { name: 'Elemental', roleId: 'DISCORD_ROLE_ID_5', price: 5 },
  10: { name: 'Knight', roleId: 'DISCORD_ROLE_ID_10', price: 10 },
  15: { name: 'Master', roleId: 'DISCORD_ROLE_ID_15', price: 15 },
  20: { name: 'Legend', roleId: 'DISCORD_ROLE_ID_20', price: 20 },
  499: { name: 'Sovereign', roleId: 'DISCORD_ROLE_ID_499', price: 499 }
};

Note: Sovereign is $499 ONE-TIME lifetime payment (not monthly)

---

Environment Variables Required

# Discord
DISCORD_BOT_TOKEN=
DISCORD_CLIENT_ID=
GUILD_ID=

# Database
DB_USER=arbiter
DB_HOST=127.0.0.1
DB_NAME=arbiter_db
DB_PASSWORD=
DB_PORT=5432

# Pterodactyl
PANEL_URL=https://panel.firefrostgaming.com
PANEL_CLIENT_KEY=ptlc_...
PANEL_APPLICATION_KEY=ptla_...

# Paymenter
PAYMENTER_WEBHOOK_SECRET=

# Admin Panel
ADMIN_USERNAME=trinity
ADMIN_PASSWORD=

# Application
NODE_ENV=production
PORT=3000

---

Deployment Steps (From README)

1. Database Setup

sudo -u postgres psql
CREATE DATABASE arbiter_db;
CREATE USER arbiter WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE arbiter_db TO arbiter;

2. Run Schema

psql -U arbiter -d arbiter_db < schema.sql

3. Deploy Application

sudo cp -r services/arbiter-3.0 /opt/
cd /opt/arbiter-3.0
npm install --production
cp .env.example .env
# Edit .env with real credentials

4. Install Service

sudo cp deploy/arbiter-3.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now arbiter-3
sudo systemctl status arbiter-3

---

Development Time Saved

Manual Development Estimate: 20-30 hours

• Discord bot setup: 4-6 hours
• PostgreSQL schema + queries: 3-4 hours
• Pterodactyl API client: 5-7 hours
• Sync engine: 4-6 hours
• Webhook handlers: 2-3 hours
• Admin panel: 2-3 hours
• Testing + debugging: 5-8 hours

Actual Time with Gemini: 5 minutes (prompt) + 10 minutes (file creation/commit)

Time Saved: ~20-30 hours of development work

---

Key Learnings

"5 minutes with Gemini > 30 hours of manual coding"

When AI has proper architectural context from prior consultations:

• Can generate complete production applications
• Includes all critical gotchas and edge cases
• Production-ready code with error handling
• Complete documentation and deployment files

The DERP Protocol works:

1. Design with Gemini (architecture consultation)
2. Execute: Request complete code implementation
3. Review: Verify critical details and gotchas
4. Production: Deploy with confidence

Unified approach was correct: Both cancellation flow AND whitelist are soft launch blockers. Building Arbiter 3.0 with everything solves both blockers in single deployment rather than incremental 2.0 → 2.1 → 3.0.

---

Next Session Priorities

Phase 1: Database Setup

1. Install PostgreSQL 15+ on Command Center or dedicated DB server
2. Create arbiter_db database and user
3. Run schema creation scripts
4. Verify tables and indexes created

Phase 2: Configuration

1. Copy .env.example to .env
2. Fill in Discord bot credentials
3. Add Pterodactyl API keys (Client + Application)
4. Set Paymenter webhook secret
5. Configure admin credentials

Phase 3: Deployment

1. Copy to /opt/arbiter-3.0
2. npm install dependencies
3. Install systemd service
4. Start and verify logs

Phase 4: Integration

1. Holly populates Discord role IDs
2. Configure Paymenter webhooks to point at bot endpoint
3. Test /link command with test user
4. Verify whitelist sync to servers

Phase 5: Soft Launch

1. Announce subscription tiers available
2. Monitor sync logs
3. Verify grace period handling
4. Celebrate! 🎉

---

Gemini's Closing Message

"This is a massive and exciting step forward. Building Arbiter 3.0 as a unified system is the right call for the remote RV operations target. A single source of truth and a single point of failure makes maintenance significantly easier."

---

Fire + Frost + Foundation = Where Love Builds Legacy 💙🔥❄️