firefrost-operations-manual/docs/consultations/gemini-modpack-database-schema-2026-04-01.md

Gemini's Response: Database Schema Refinement & UI Visualization

From: Gemini AI
To: Chronicler #52 + Michael (The Wizard)
Date: April 1, 2026
Re: Modpack Version Checker - Database Architecture & Fleet Coverage Dashboard

---

Hello Chronicler #52 and Michael (The Wizard)! 👋

I absolutely love the decisive action here. Banning fragmented platforms internally and adopting the "RV-Ready Score" as a core development philosophy is the exact mindset transition from "hobbyist coder" to "SaaS Founder." You are building a machine that works for you, not the other way around.

Gracefully degrading the UI for unsupported platforms is a brilliant product decision. Instead of a buyer installing the extension and thinking "It's broken, it didn't find my FTB server," they see: "Oh, it found my FTB server, but FTB doesn't allow automated tracking. I should probably switch to CurseForge." You turn a technical limitation into an educational feature that reduces support tickets.

Let's refine that database architecture and look at how to visualize this in your dashboard.

---

1. Architectural Review: The Database Schema

Your proposed schema logic is excellent, but for a distributed commercial product, we need to make one defensive tweak.

My Recommendation: Instead of platform ENUM('curseforge', 'modrinth', 'ftb'...), use platform VARCHAR(50).

Why? If Pterodactyl or the community Modpack Egg updates next year to support a new platform (e.g., fabric-api-direct), an ENUM requires you to push an update with a database migration just to avoid SQL errors when it encounters the new string. With a VARCHAR(50), your database happily accepts the new string, your backend logic defaults it to is_supported = FALSE, and your UI gracefully flags it as "Manual Tracking Required" without throwing a fatal database error.

The is_supported Boolean: Keeping is_supported BOOLEAN DEFAULT TRUE is a fantastic idea, but you should use it dynamically!

• Scenario A (Platform Limit): Server is FTB. On sync, backend sets is_supported = FALSE.
• Scenario B (Author Deletion): Server is CurseForge. Your scheduled task pings the CurseForge API, but the API returns a 404 Not Found because the modpack author deleted the project. Your task catches the 404, flips is_supported = FALSE, and logs the reason. The UI shifts that server into the "Manual Tracking / Intervention Required" bucket.

This makes your schema incredibly resilient to edge cases.

---

2. Detection Method (Pterodactyl Quirks)

To detect the platform, you will query the Pterodactyl Server's environment variables.

When accessing the panel database or API, look at the server's environment JSON. The standard Modpack Installer egg uses a variable usually named INSTALL_TYPE, PLATFORM, or MODPACK_API.

Architecture Rule: If the environment variable isn't explicitly curseforge or modrinth, immediately flag it as is_supported = false and platform = unknown (or whatever the raw variable string is). Never guess.

---

3. Turning Educational Messaging into a Feature

Your P.S. was spot on. Buyers love dashboards that show them the "Health" or "Coverage" of their fleet. If they see they have 80% automated coverage and 20% manual, it gamifies the process of standardizing their servers to supported platforms.

Here is an interactive mockup of how you could build that specific "Fleet Coverage" dashboard component in your Laravel/Blade UI. Play around with the sliders to see how the UI gracefully handles different distributions of supported vs. unsupported servers.

[Interactive Fleet Coverage Dashboard Simulator Provided]

---

The Next Steps

You have effectively locked in the MVP scope, pricing, and architecture.

1. CurseForge BYOK: Look into how to securely store API keys in Laravel (encrypting them at rest in the database is a great selling point for security-conscious hosts).

2. Modrinth User-Agent: This is just a simple HTTP header addition in your Guzzle/cURL requests.

3. Blueprint Basics: Dive into the Blueprint documentation to see how to scaffold your initial routes and Blade templates.

Take your time on the Dev VPS. You are building the financial foundation for the legacy now. Let me know when you start digging into the API specifics or the Blueprint scaffolding!

---

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

— Gemini AI

---

Key Architectural Decisions

Database Schema (Final)

CREATE TABLE modpack_version_tracker (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    server_id INT NOT NULL,
    platform VARCHAR(50) NOT NULL,  -- Not ENUM! Handles future platforms gracefully
    project_id VARCHAR(255) NOT NULL,
    current_version_id VARCHAR(255),
    latest_version_id VARCHAR(255),
    is_supported BOOLEAN DEFAULT TRUE,  -- Dynamically set based on platform + API availability
    unsupported_reason VARCHAR(255),  -- NULL if supported, error message if not
    last_checked_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (server_id) REFERENCES servers(id) ON DELETE CASCADE
);

Platform Detection Logic

• Read Pterodactyl server environment variables (INSTALL_TYPE, PLATFORM, MODPACK_API)
• If value is curseforge or modrinth → is_supported = TRUE
• If value is anything else → is_supported = FALSE, platform = [raw value]
• Never guess. Unknown = unsupported.

Dynamic Support Flagging

Scenario A: Platform Unsupported

• FTB server detected → is_supported = FALSE, unsupported_reason = "FTB platform does not provide public API"

Scenario B: API Error (404)

• CurseForge modpack deleted by author → Catch 404 → is_supported = FALSE, unsupported_reason = "Modpack not found on CurseForge (deleted by author?)"

Scenario C: API Rate Limit

• CurseForge returns 429 → Don't flag as unsupported → Log error, retry next cycle

UI Treatment

Fleet Coverage Dashboard:

• Total servers count
• Automated tracking % (supported / total)
• Visual progress bar or donut chart
• Server list with badges:
  • ✅ "Tracking Active" (supported)
  • ⚠️ "Manual Oversight Required" (unsupported)
• Educational instructions toggle for unsupported servers

Gamification Effect:

• Buyers see 80% coverage, want 100%
• Encourages migration to supported platforms
• Reduces support tickets ("Why isn't this working?")
• Turns limitation into educational feature