# Gemini Architectural Consultation: Arbiter + Whitelist Manager Integration

Hi Gemini! 👋

Michael (The Wizard) and Claude (The Golden Chronicler #50) here. We need your architectural expertise on a critical integration between two services that's more complex than we initially realized.

---

## Context: What We're Building

**Firefrost Gaming** - Subscription-based modded Minecraft server hosting platform
- 6 subscription tiers: Awakened ($1), Elemental ($5), Knight ($10), Master ($15), Legend ($20), Sovereign ($499 lifetime)
- ~13 game servers across 2 physical nodes (TX1 Dallas, NC1 Charlotte)
- Goal: September 2027 remote RV operations (fully automated, low-maintenance)

**The Core Flow:**
1. User subscribes via Paymenter (Stripe payments)
2. **Arbiter** assigns Discord roles based on tier
3. User links Minecraft account (somehow - TBD)
4. **Whitelist Manager** grants server access based on subscription
5. User joins whitelisted Minecraft servers

---

## Current State: Two Broken/Incomplete Services

### Service 1: The Arbiter (Discord OAuth Bot)

**What it currently does:**
- Receives Paymenter subscription webhooks
- Assigns Discord roles based on subscription tier
- Manages role mapping via admin panel
- Ghost CMS integration (purpose unclear)
- Email notifications

**Current architecture:**
- Node.js + Express
- SQLite database (schema unknown - need to check)
- Discord.js bot
- Admin OAuth panel (Trinity-only access)

**What it does NOT do:**
- Store Minecraft usernames
- Communicate with Whitelist Manager
- Handle subscription cancellations (Arbiter 2.1 feature, not yet deployed)

**Code location:** `firefrost-services/services/arbiter/`

---

### Service 2: Whitelist Manager (Server Access Control)

**What it currently does (poorly):**
- Lists servers from Pterodactyl Panel API
- Groups servers by hardcoded name keywords (BROKEN - servers constantly change)
- Checks whitelist status via WebSocket console commands (unreliable)
- Allows manual add/remove players per-server or bulk

**Current architecture:**
- Python + Flask
- No database (in-memory activity log only)
- HTTP Basic Auth
- WebSocket connections to game servers

**What's BROKEN:**
- Server grouping uses name keywords instead of Panel node allocation
- Status detection fails (shows "UNKNOWN" for all servers)
- No concept of "master whitelist"
- No integration with subscriptions
- Purely manual operation

**Code location:** `firefrost-services/services/whitelist-manager/`

---

## What Michael Actually Needs

### The Real Requirements (Just Discovered):

1. **Subscription-Driven Access**
   - ANY paid subscriber (even $1 Awakened tier) gets whitelisted
   - Happens automatically once Minecraft account is linked
   - Cancellation removes whitelist access (with grace period - Arbiter 2.1)

2. **Master Whitelist Concept**
   - Single source of truth for approved players
   - All Minecraft servers sync from this master list
   - When whitelist enabled on server → master list auto-syncs

3. **Auto-Discovery**
   - Query Pterodactyl Panel for current servers
   - Group by actual node allocation (not name patterns)
   - Adapt as servers added/removed

4. **Panel API Integration**
   - Detect whitelist enabled/disabled from server properties
   - Toggle whitelist via Panel API (not console commands)
   - Reliable status detection

5. **Minecraft Account Linking**
   - Users link Minecraft username to Discord account
   - Stored permanently (survives subscription changes)
   - Validated against Mojang API?

---

## The Big Architectural Questions

We need your expertise on:

### Question 1: Data Storage Architecture

**Where should the Minecraft username → Discord ID mapping live?**

**Option A - Arbiter Owns It:**
- Arbiter SQLite database stores: `discord_id`, `minecraft_username`, `subscription_tier`
- Whitelist Manager queries Arbiter's API: `GET /api/subscribers` → returns list of active whitelisted players
- Pro: Single source of truth
- Con: Tight coupling, Whitelist Manager can't work independently

**Option B - Whitelist Manager Owns It:**
- Whitelist Manager has its own database
- Arbiter sends webhooks on subscribe/cancel/link: `POST /api/player-update`
- Pro: Loose coupling, independent services
- Con: Data duplication, sync issues

**Option C - Shared Database:**
- PostgreSQL database both services connect to
- Shared schema: `users`, `subscriptions`, `minecraft_accounts`
- Pro: No API overhead, consistent data
- Con: Tight coupling at DB layer, harder to deploy separately

**Option D - Something else we haven't thought of?**

**What do you recommend for remote RV operations reliability?**

---

### Question 2: Minecraft Account Linking Flow

**How should users link their Minecraft account?**

**Current unknowns:**
- Where does linking happen? (Discord bot command? Web form? Ghost CMS?)
- How do we validate Minecraft usernames? (Mojang API? Just accept any string?)
- Can users link multiple Minecraft accounts? (family subscriptions?)
- What if they change their Minecraft name?

**What's the industry-standard approach for Discord → Minecraft linking?**

---

### Question 3: Arbiter 2.x vs Arbiter 2.1

**Current plan:**
- Arbiter 2.1 adds subscription cancellation + grace period handling
- Whitelist Manager is separate service

**Should we instead build Arbiter 2.x?**
- Arbiter 2.x = combined service (Discord roles + Whitelist management)
- Single service handles entire subscription → server access flow
- Simpler deployment, fewer moving parts

**Or keep them separate?**
- Pro: Single responsibility, easier to test/debug
- Con: More services to manage, integration complexity

**What makes sense for a two-person team running this from an RV?**

---

### Question 4: Real-Time Sync Strategy

**When a user subscribes, how quickly should they get whitelisted?**

**Scenario:**
1. User subscribes via Paymenter ($5/month Elemental tier)
2. Paymenter webhook → Arbiter
3. Arbiter assigns Discord role
4. User links Minecraft account (username: "Steve")
5. **← THIS STEP:** How does "Steve" get added to all 13 game servers?

**Option A - Immediate Push:**
- Arbiter/Whitelist Manager immediately runs `whitelist add Steve` on all 13 servers
- Fast, but what if servers are offline?

**Option B - Periodic Sync:**
- Cron job every 5 minutes syncs master whitelist to all servers
- Slower (up to 5min delay), but more reliable

**Option C - On-Demand:**
- Servers pull whitelist on startup
- Manual "Force Sync" button in admin panel
- Slowest, but most resilient

**What's the right balance for production?**

---

### Question 5: Pterodactyl Panel v1.12.1 Integration

**Current Whitelist Manager uses:**
- WebSocket console commands: `whitelist on`, `whitelist list`
- Unreliable, times out, returns "unknown"

**Should we instead use Panel API?**
- Does Panel v1.12.1 API expose server whitelist status?
- Can we toggle whitelist via API instead of console?
- What about bulk operations (sync to 13 servers)?

**What's the proper way to integrate with Pterodactyl Panel for whitelist management?**

---

## Current Code We Have

**Arbiter:**
- Full source in `firefrost-services/services/arbiter/`
- SQLite database (schema in `src/database.js`)
- Discord bot + OAuth admin panel
- Paymenter webhook handler
- Email service (SMTP)

**Whitelist Manager:**
- Full source in `firefrost-services/services/whitelist-manager/`
- Flask app, no database
- Panel API client
- WebSocket console integration
- Basic auth admin panel

**We can share specific code if needed!**

---

## What We Need From You

### Primary Deliverable:

**Recommended Architecture** for the integrated system:

1. **Data storage strategy** (Option A/B/C/D from Question 1)
2. **Service structure** (Keep separate? Merge into Arbiter 2.x? Microservices?)
3. **Minecraft linking flow** (Discord bot command? Web form? API?)
4. **Whitelist sync strategy** (Real-time push? Periodic sync? On-demand?)
5. **Panel API integration** (Replace WebSocket with API calls? Hybrid?)

### Bonus If You Have Time:

- Database schema for the recommended approach
- API contract between Arbiter ↔ Whitelist Manager (if separate)
- Failure modes and recovery strategies (server offline, Panel API down, etc.)
- Migration path from current broken system to new architecture

---

## Constraints & Context

**Technical:**
- Pterodactyl Panel v1.12.1 (latest)
- Discord.js v14
- Python 3.11 (Whitelist Manager)
- Node.js 20 (Arbiter)
- Infrastructure: Debian 12, systemd services

**Team:**
- Two-person team (Michael + Meg)
- Will be operating remotely from RV (September 2027)
- Need reliable, low-maintenance automation
- Can't SSH to servers to fix things manually while traveling

**Scale:**
- Current: ~13 game servers, 2 physical nodes
- Target: 500 subscribers by September 2027
- 6 subscription tiers
- Unknown number of concurrent Minecraft players

**Philosophy:**
- "We Don't Kick People Out" - payment failures = downgrade, not removal
- Subscribers expect instant access after payment
- Whitelist is per-server (some servers whitelisted, some public)

---

## Questions For Us

If you need clarification on:
- Current Arbiter database schema
- Paymenter webhook payload format
- Panel API response structure
- Discord bot command preferences
- Any technical details

Just ask! We're here and ready to provide more context.

---

Thanks for being our architectural partner, Gemini! Your monorepo guidance earlier today was invaluable. Looking forward to your thoughts on this integration challenge.

— Michael & Claude (The Golden Chronicler) 💙🔥❄️

---

**P.S.** We're also wondering if this should be:
- **Arbiter 2.1** (just add cancellation handling, keep Whitelist Manager separate)
- **Arbiter 2.x** (major rewrite, absorb Whitelist Manager functionality)
- **Completely new service** (Arbiter stays Discord-only, new "Access Manager" handles whitelisting)

Your architectural instincts on service boundaries would be hugely helpful!
