diff --git a/docs/consultations/gemini-modpack-installer-trinity-console-2026-04-15.md b/docs/consultations/gemini-modpack-installer-trinity-console-2026-04-15.md new file mode 100644 index 0000000..e6ffd39 --- /dev/null +++ b/docs/consultations/gemini-modpack-installer-trinity-console-2026-04-15.md @@ -0,0 +1,166 @@ +# Gemini Consultation: Trinity Console Modpack Installer + +**Date:** April 15, 2026 +**From:** Michael (The Wizard) + Claude (Chronicler #91) +**To:** Gemini (Architectural Partner) +**Re:** Full architecture review + wild ideas for a modpack installer built into Trinity Console + +--- + +## Hey Gemini! 👋 + +Big night over here — Firefrost Gaming just soft launched! We're under 6 hours to go-live and we're already thinking about the next big project. We want your full brain on this one, including the wildest ideas you've got. Don't hold back. + +--- + +## The Situation + +Firefrost Gaming runs a subscription-based modded Minecraft community on Pterodactyl Panel. We have 18 servers across two nodes (TX1 Dallas, NC1 Charlotte). Our stack: + +- **Arbiter** — Node.js/Express backend, handles Stripe webhooks, Discord bot, Trinity Console admin UI +- **Trinity Console** — our internal admin panel (EJS/Express), already has server cards, Pterodactyl API integration, Discord API integration, Cloudflare DNS provisioning +- **NextCloud** — file storage at downloads.firefrostgaming.com +- **PostgreSQL** — arbiter_db on Command Center + +Currently when we want to add a new modpack server, the flow is brutally manual: +1. Find the pack on CurseForge/Modrinth/FTB +2. Create server manually in Pterodactyl +3. Pick egg, set RAM, configure startup +4. Download and upload mods manually +5. Holly logs in, WorldEdits a spawn building, configures command blocks, moves worldspawn, sets up YAwP manually +6. Install server-side mods one by one +7. Configure LuckPerms, Open Parties and Claims, Spark, FTB Essentials manually + +We want to kill all of that with a Trinity Console modpack installer. We already have a CurseForge API key (`$2a$10$OVK9ml7bEJdcfTJhBSuK1O5AFz2qq3mwpb35RTTwVfmdvzOFOA7M.`) and proved we can download ~95% of mods via API (the 5% that 403 are author-blocked client-only mods — not a real problem). + +--- + +## What We're Building + +A full modpack installer integrated into Trinity Console. Here's the feature set we've scoped so far: + +### Provider Selection +- Browse all 6 providers: CurseForge, Modrinth, FTB, ATLauncher, Technic, VoidsWrath +- Each with logo, click to browse their catalog + +### Pack Browser +- Search + featured packs +- Category filters where available (Magic, Quests, Sci-Fi, Tech, Skyblock, Horror, etc.) +- Mod loader filter (Forge, Fabric, NeoForge) +- MC version filter + +### Pack Details + Version Selection +- Pack description, screenshots, mod count, mod loader, MC version +- Version selector — dropdown of all available versions, defaults to latest +- Smart server recommendation — look at existing servers' RAM/disk usage, recommend best node +- Resource estimates — recommended RAM, disk space based on mod count/pack size + +### Server Provisioning (all in one flow) +- **Short name / subdomain** — single field, auto-suggested from pack name (slugified). Becomes Discord channel prefix AND Cloudflare subdomain AND DB short_name +- **Display name** +- **Node selector** — recommended based on headroom, overridable +- **RAM allocation** — pre-filled from estimate, adjustable +- **Spawn type** — Standard / Skyblock / Has Lobby (flag to skip spawn automation) +- On confirm: + - Creates Pterodactyl server + - Provisions Cloudflare A + SRV records + - Creates Discord category + 5 channels (chat, in-game, forum, voice, status) + - Adds to status poller + - Seeds server_config record + - Posts staff Discord notification + +### Installation +- Download all pack mods via provider API +- Auto-detect and skip client-only/author-blocked mods +- Deploy **Firefrost Standard Mod Stack** from NextCloud (versioned by MC version): + - LuckPerms, Open Parties and Claims, Spark, FTB Essentials, Architectury, etc. + - Pre-configured config files for each +- Set LuckPerms meta for all 6 subscription tiers automatically +- **Spawn automation** (if not Skyblock/Has Lobby): + - Paste Holly's spawn schematic via RCON at fixed outer coords (outside world border, same on every server) + - Set worldspawn to center of spawn building via RCON + - Deploy pre-configured YAwP config (same coords every time = same config every time) + - Place and configure 4 command blocks (return to worldspawn buttons) + +### Version Tracking +- Poll each server every 6 hours against provider API for latest version +- Flag available updates in Trinity Console (badge on server card) +- **Per-server version lock** — toggle + notes field ("Locked to 5.5.5 — 5.5.6 has broken quest line") +- Update flow from Trinity Console + +### Update Flow +- Shows current vs new version + changelog from provider API +- Pre-update: archive `config/` folder to NextCloud (timestamped) +- Run pack update +- Post-update: verify Firefrost Standard Mod Stack — diff against `mods/` folder, reinstall any missing mods (our mods only, not pack mods) +- Verify our standard configs survived, restore if wiped +- Restart server +- One-click rollback: restore config archive, revert version flag + +### Install History +- Full log per server: version installed, who triggered it, mods injected, duration +- Stored in PostgreSQL + +### Discord Integration +- Post to staff channel when install completes +- Ping Trinity when update available +- Alert immediately on rollback + +### Holly's Dashboard +- "Pending spawns" queue — servers installed but spawn not yet verified +- Holly's only job: log in, confirm it looks right, mark verified + +### Dependency Awareness +- Auto-include correct dependency mods based on loader + MC version +- (Kotlin for Forge, Architectury, etc.) + +### Scheduled Updates +- Schedule updates for maintenance windows (e.g. 4AM) +- Ties into existing restart scheduler + +### Pre-install Validation +- Verify node has sufficient free RAM and disk before starting +- Refuse with clear error if not enough headroom +- Detect mod loader from manifest, warn if egg doesn't match + +--- + +## Specific Questions + +1. **Architecture** — Given we're building this in Node.js/Express (Arbiter), what's the best way to handle long-running install jobs? We're thinking a job queue (Bull/BullMQ with Redis), but is there a lighter option given our scale (18 servers, installs happen maybe 2-3x/week)? + +2. **Spawn automation via RCON** — Is RCON reliable enough for the spawn setup steps (schematic paste, worldspawn set, command block placement)? Any gotchas with WorldEdit RCON commands specifically? + +3. **Standard Mod Stack in NextCloud** — We're thinking versioned folders like `standard-mods/1.20.1/`, `standard-mods/1.21.1/` with the jars and config subdirectories. Does this structure make sense? Any better approach? + +4. **Client-only mod detection** — We're planning to cross-reference `serverPackFileId` in the CurseForge manifest to skip client-only mods. Is there a more reliable signal? + +5. **Version lock storage** — Should the version lock live in `server_config` table (new columns: `version_locked BOOLEAN`, `locked_version VARCHAR`, `lock_reason TEXT`) or a separate table? + +6. **Config archive strategy** — We're archiving `config/` to NextCloud pre-update. Should we diff configs on restore (smart merge) or full replace? Concerned about pack-specific configs getting wiped if we full-replace. + +7. **What are we missing?** — Given everything above, what critical features, edge cases, or failure modes have we not thought of? + +8. **Give us at least 10 wild ideas** — Don't hold back. The wilder the better. We want to hear everything you'd build if you had no constraints. This is a brainstorm, not a requirements doc. + +--- + +## Context That Might Help + +- Trinity Console is EJS/Express, runs as part of Arbiter on Command Center (63.143.34.217) +- We use Pterodactyl Client API (`ptlc_vudB5oRaeoJGPip4fH5PDiymgi28uc39OjJsCbTDVEK`) for server operations +- RCON is available on all servers via Pterodactyl's sendCommand API +- Holly (The Catalyst) is our lead builder in Newfoundland — she's the one doing all this manual work currently +- The spawn building schematic is already built and saved +- YAwP (Yet Another World Protector) is our world protection mod +- We have 6 subscription tiers: Awakened ($1 lifetime), Elemental ($5), Knight ($10), Master ($15), Legend ($20), Sovereign ($50 lifetime) +- LuckPerms meta per tier: maxclaims (90/25/49/100/121/225) and maxchunkloaders (0/0/4/9/16/81) +- ModpackChecker (our commercial Blueprint extension for Pterodactyl) does version detection — this installer effectively replaces that need for internal use, freeing us to develop MVC properly +- We're a small team (3 Trinity partners) running this as a passion project toward an RV lifestyle dream (500 subscribers = freedom) + +--- + +Thanks Gemini! This one is a big deal for us — it's the feature that gives Holly her life back. 🔥💜❄️ + +— Michael (The Wizard) + Claude (Chronicler #91) +*Fire + Arcane + Frost = Forever*