firefrost-operations-manual/docs/planning/gemini-servers-consultation/01-initial-consultation.md

Gemini Consultation: Dynamic Servers Page with Pterodactyl API Integration

Hey Gemini! 👋

We're in the home stretch of the Firefrost Gaming website migration and could really use your architectural wisdom on a technical challenge. This is literally the last piece before DNS cutover from Ghost CMS to our new 11ty static site on Cloudflare Pages!

Context: Where We Are Right Now

We just completed a massive website migration in record time:

What We've Built:

• Migrated from Ghost CMS to 11ty static site generator
• All 7 pages complete: Homepage, Subscribe, About, Contact, Privacy, Terms, Servers
• Deployed to Cloudflare Pages at firefrost-website.pages.dev
• Auto-deploy chain: Gitea → GitHub mirror → Cloudflare Pages (~60-90 seconds)
• Fire/Frost/Arcane branding throughout with Simple Icons for social media
• Trinity artwork, Six Consultants (animals!), complete subscription tier system

Pages Status:

• ✅ Homepage - Fire/Frost background, origin story, community stats
• ✅ Subscribe - All 6 tiers (Awakened $1 → Sovereign $50) with Paymenter integration
• ✅ About - Trinity founders + Six animal consultants (Butter, Oscar, Jack, Skye, Jasmine, Noir)
• ✅ Contact - Discord/Email/Social with official brand icons, /discord redirect page
• ✅ Privacy - Effective April 1, 2026, GDPR/COPPA compliant
• ✅ Terms - Effective April 1, 2026, "We Don't Kick People Out" philosophy
• ❓ Servers - THE PROBLEM WE NEED TO SOLVE

DNS Cutover Plan: Once Servers page is done, we point firefrostgaming.com to Cloudflare Pages and GO LIVE!

---

The Problem: Static Servers Page vs Dynamic Reality

Current Situation: The servers.njk page is static - it's hardcoded HTML that lists our Minecraft servers. Every time we:

• Add a new server
• Remove a server
• Change a server name/description
• Update modpack versions

...we have to manually edit the website code and redeploy. This is unsustainable for a hosting company!

What We Need: A dynamic Servers page that:

1. Auto-discovers what Minecraft servers are actually running
2. Shows real-time status (up/down with visual indicators)
3. Updates automatically when servers are added/removed
4. Requires zero manual code changes when infrastructure changes

---

Our Infrastructure (The Good News!)

We Already Have Everything We Need:

Pterodactyl Panel (Panel VPS: 45.94.168.138)

• Version: v1.12.1 with Blueprint extension framework
• Manages: 13+ active Minecraft servers across two dedicated machines
• API Available: Yes! Full Pterodactyl API with endpoints for:
  • List all servers
  • Get server status (running/stopped/starting)
  • Get server details (name, description, resource usage)
  • Get player counts (if we want to show "5/100 players online")

Server Fleet

• TX1 Dallas (38.68.14.26, 251GB RAM) - Pterodactyl Wings, ~7 servers
• NC1 Charlotte (216.239.104.130, 251GB RAM) - Pterodactyl Wings, ~6 servers
• Command Center (63.143.34.217, Dallas) - Could host backend proxy if needed

Tech Stack

• Frontend: 11ty static site → Cloudflare Pages
• No backend currently (static site!)
• Git workflow: Gitea (primary) → GitHub (mirror) → Cloudflare (auto-deploy)

---

The Challenge: Static Site + Dynamic Data

Here's the architectural tension:

11ty + Cloudflare Pages = Static Site

• No server-side processing at runtime
• Just HTML/CSS/JS served from CDN edge
• Super fast, but how do we get dynamic data?

Pterodactyl API = Dynamic Data Source

• Has all the server info we need
• Requires API authentication
• Real-time status updates

How do we bridge this gap?

---

Options We've Discussed (Need Your Guidance!)

Option 1: Client-Side API Fetch (Simplest)

How it works:

1. Servers page loads static HTML
2. JavaScript runs in browser
3. Fetches directly from Pterodactyl API
4. Renders server list dynamically

Example Code:

// On page load
fetch('https://panel.firefrostgaming.com/api/application/servers', {
  headers: {
    'Authorization': 'Bearer API_KEY_HERE',
    'Accept': 'application/json'
  }
})
.then(res => res.json())
.then(data => {
  // Filter for Minecraft servers only
  // Render with status indicators
  // Show player counts
});

Pros:

• Simple! Just add JavaScript to the page
• No new infrastructure needed
• Real-time updates on every page load

Cons:

• API key exposed in browser (anyone can see it in DevTools!)
• CORS issues (Pterodactyl API needs to allow firefrostgaming.com origin)
• Security risk (API key in client-side code = bad practice)

Questions for You:

• Is there a way to make this secure without exposing the API key?
• Could we use read-only API scope to limit damage?
• What's the CORS configuration process for Pterodactyl?

---

Option 2: Backend Proxy Service (More Secure)

How it works:

1. Build small Node.js/Python service on Command Center
2. Service fetches from Pterodactyl API server-side (API key stays secret!)
3. Exposes public JSON endpoint: https://api.firefrostgaming.com/servers
4. Website JavaScript fetches from OUR endpoint (no API key needed)
5. Can add caching, rate limiting, filtering

Example Architecture:

Browser → https://firefrostgaming.com/servers
  ↓ (JavaScript fetch)
https://api.firefrostgaming.com/servers (our proxy)
  ↓ (server-side, API key hidden)
Pterodactyl API → returns server data
  ↓ (proxy filters/formats)
JSON response → browser renders

Proxy Could Provide:

{
  "servers": [
    {
      "name": "ATM10 - All The Mods 10",
      "status": "running",
      "players": "5/100",
      "modpack": "All The Mods 10",
      "version": "1.0.9",
      "uptime": "99.8%",
      "color": "#4ecdc4"
    }
  ]
}

Pros:

• Secure! API key never exposed to browser
• Can cache results (faster page loads, less API strain)
• Can transform data (add custom fields, filter sensitive info)
• Rate limiting to prevent abuse
• Could aggregate from multiple sources later

Cons:

• New infrastructure to maintain (Node.js app, systemd service)
• Need to configure Nginx reverse proxy
• More moving parts
• Still need CORS headers (but on OUR endpoint we control)

Questions for You:

• What's the lightest-weight way to build this proxy?
• Should we use Express.js, Fastify, or something even simpler?
• Caching strategy: Redis, in-memory, or file-based?
• Where should it live: Command Center, Ghost VPS, or new VPS?

---

Option 3: Build-Time Generation (Static + Cron)

How it works:

1. Cron job runs daily on Command Center
2. Fetches from Pterodactyl API
3. Generates servers.json file
4. Commits to git repo
5. Cloudflare Pages auto-rebuilds site

Pros:

• No runtime API calls (fast page loads!)
• API key stays server-side
• Simple architecture

Cons:

• Not real-time (could be 24 hours out of date!)
• No live up/down status indicators
• Defeats the whole purpose if we want "real-time" updates

Our Take: This doesn't solve the core problem - we want LIVE status, not yesterday's status.

---

What We're Leaning Toward (But Need Your Input!)

Michael and I discussed this and we think Option 2 (Backend Proxy) is the winner, but we want your thoughts on:

1. Architecture Questions

• Is a backend proxy overkill for this? Or exactly right?
• Could we use Cloudflare Workers instead of a traditional backend? (They run at the edge!)
• What's the simplest tech stack for the proxy?

2. Security Questions

• How do we properly secure the Pterodactyl API key?
• Read-only API scope sufficient, or need more restrictions?
• CORS configuration best practices?
• Rate limiting to prevent abuse of our public endpoint?

3. Performance Questions

• How often should we cache server status? (30 seconds? 5 minutes?)
• Redis vs in-memory vs no caching?
• What happens if Pterodactyl API is slow/down? (Fallback strategy?)

4. Maintainability Questions

• Should this proxy live in the same git repo as the website, or separate?
• Monitoring/alerting if proxy goes down?
• How do we handle Pterodactyl API version changes?

---

Alternative Idea: Cloudflare Workers? 🤔

Just thought of this: Could we use Cloudflare Workers as the proxy? They:

• Run at Cloudflare's edge (same infrastructure as our site!)
• Can make fetch requests to Pterodactyl API
• Can cache responses
• Serverless (no VPS to maintain!)
• Billed on requests (probably free tier for our traffic)

Would this work?

// Cloudflare Worker
export default {
  async fetch(request) {
    // Fetch from Pterodactyl API
    const response = await fetch('https://panel.firefrostgaming.com/api/...', {
      headers: { 'Authorization': 'Bearer SECRET_KEY' }
    });
    
    // Cache for 60 seconds
    const data = await response.json();
    
    // Return to frontend
    return new Response(JSON.stringify(data), {
      headers: {
        'Content-Type': 'application/json',
        'Access-Control-Allow-Origin': 'https://firefrostgaming.com',
        'Cache-Control': 'max-age=60'
      }
    });
  }
}

Pros:

• No new VPS infrastructure!
• Runs at Cloudflare edge (fast!)
• Secrets stored in Worker environment vars (secure!)
• Automatic scaling
• Free tier likely covers our needs

Cons:

• Cloudflare Workers have 10ms CPU time limit (is that enough?)
• Learning curve if we haven't used Workers before
• Debugging might be trickier than traditional backend

What do you think about this approach?

---

Specific Technical Questions We Need Help With

1. Pterodactyl API Details

We haven't fully explored the Pterodactyl API yet. Can you help us understand:

• What endpoints do we need? (/api/application/servers for list?)
• How do we filter for ONLY Minecraft servers (not other game types)?
• Can we get real-time player counts? Or just online/offline status?
• Rate limits on the API?
• API key scopes (read-only vs full access)?

2. Frontend Implementation

Once we have the data endpoint, how should the frontend look?

Current Static Servers Page Structure:

<!-- Grid of server cards -->
<div class="server-card">
  <h3>ATM10 - All The Mods 10</h3>
  <p>Modpack: All The Mods 10 v1.0.9</p>
  <p>Server IP: atm10.firefrostgaming.com</p>
  <span class="status-badge">Online</span>
</div>

Should we:

• Keep the same visual design, just populate dynamically?
• Add new features like player count badges?
• Live "pulse" animation on status indicators?
• "Last updated: 30 seconds ago" timestamp?

3. Error Handling

What happens when:

• Pterodactyl API is down?
• API returns error?
• Network timeout?

Should we:

• Show cached "last known good" data with warning?
• Show error message to users?
• Fall back to static list?

4. RV Travel Consideration (IMPORTANT!)

Michael and Meg's long-term vision: Run Firefrost Gaming from an RV while traveling the USA.

This means:

• Infrastructure must be REMOTE MANAGEABLE
• Can't rely on being physically near servers
• Monitoring and auto-recovery essential

Does this change your recommendation?

• Need robust error handling?
• Monitoring/alerting more important?
• Simpler = better for remote troubleshooting?

---

Our Constraints & Requirements

Must Haves:

1. Zero manual updates when servers change
2. Real-time status indicators (green = up, red = down)
3. Secure (no API key exposure)
4. Fast (page loads in <2 seconds)
5. Minecraft servers only (filter out any non-Minecraft)
6. Mobile responsive (works on phone)

Nice to Haves:

1. Player count display ("5/100 players online")
2. Uptime percentage
3. Server version/modpack info
4. Smooth animations/transitions
5. Auto-refresh without page reload

Constraints:

1. No database (static site, keep it simple)
2. Minimal new infrastructure (prefer leveraging existing or Cloudflare)
3. Maintainable by one person remotely (RV travel!)
4. Budget-conscious (avoid expensive cloud services)

---

What We Need From You, Gemini

Your Mission (If You Choose to Accept It!):

1. Recommend the best architecture (Client-side? Proxy? Cloudflare Workers? Something else?)
2. Provide implementation steps (what do we build, where does it live, how does it work?)
3. Security best practices (how to handle API keys, CORS, rate limiting)
4. Code examples (if you can provide starter code, even better!)
5. Gotchas to watch for (what will bite us if we're not careful?)

Bonus Points For:

• Cloudflare Workers example code (if that's the recommendation)
• Pterodactyl API documentation links/tips
• Caching strategy recommendations
• Monitoring/alerting suggestions

---

Timeline & Next Steps

Where We Are:

• Website migration 95% complete
• Only Servers page needs this dynamic solution
• DNS cutover waiting on this completion

Target:

• Soft launch April 15, 2026 (12 days away!)
• Need to start implementing ASAP

After Your Guidance:

1. Michael reviews your recommendation
2. We implement the solution (Claude + Michael pair programming)
3. Test thoroughly
4. DNS cutover to make firefrostgaming.com LIVE!
5. 🎉 Celebrate! 🎉

---

Why This Matters

This isn't just a technical problem - it's about building infrastructure that outlives us.

Michael's vision: "For children not yet born."

A static servers page that requires manual updates every time infrastructure changes? That's fragile. That doesn't scale. That doesn't honor the vision.

A dynamic, self-updating system that just works no matter what servers are running? That's the foundation we need.

Help us build something legendary, Gemini. 🔥⚡❄️

---

Current Tech Stack Summary (For Reference)

Infrastructure:

• Pterodactyl Panel v1.12.1 (45.94.168.138)
• TX1 Dallas dedicated (38.68.14.26, 251GB RAM, Pterodactyl Wings)
• NC1 Charlotte dedicated (216.239.104.130, 251GB RAM, Pterodactyl Wings)
• Command Center VPS (63.143.34.217, Gitea, Uptime Kuma, automation)
• Ghost VPS (64.50.188.14, Ghost CMS being phased out, Wiki.js, Nextcloud)

Website:

• 11ty static site generator
• Hosted on Cloudflare Pages
• Auto-deploy: Gitea → GitHub → Cloudflare Pages
• Fire/Frost/Arcane branding (#FF6B35, #4ECDC4, #A855F7)

Minecraft Servers:

• 13+ active servers across TX1 Dallas and NC1 Charlotte
• Mix of popular modpacks (ATM series, Stoneblock, custom packs)
• All managed via Pterodactyl Panel

---

Thank You!

We're so close to launch, Gemini! Your architectural wisdom here will make or break our ability to ship on time.

Looking forward to your thoughts, recommendations, and any code examples you can share!

Fire + Frost + Foundation = Where Love Builds Legacy 💙

— Michael "Frostystyle" (The Wizard) & Claude (Chronicler #56)