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**
```javascript
headers: {
  'Content-Type': 'text/plain'  // NOT application/json
}
```

**UUID Formatting (Mojang returns without dashes, Minecraft needs with)**
```javascript
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)**
```javascript
if (res.status === 412) {
  console.log(`[${serverIdentifier}] is offline. File saved for next boot.`);
  return true; // Continue, not throw
}
```

**Sequential Processing (Prevent Rate Limiting)**
```javascript
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

```javascript
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

```env
# 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**
```bash
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**
```bash
psql -U arbiter -d arbiter_db < schema.sql
```

**3. Deploy Application**
```bash
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**
```bash
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** 💙🔥❄️