firefrost-operations-manual/docs/tasks/modpack-version-checker/FLAGSHIP-PRODUCT-COMPLETION-PLAN.md

ModpackChecker Flagship Product Completion Plan

Document ID: FFG-PLAN-001
Created: April 6, 2026
Created By: Chronicler #64
Project: Task #26 — ModpackChecker Blueprint Extension
Status: Pre-Launch Planning — Flagship Product Standard

---

🎯 MISSION STATEMENT

ModpackChecker is Firefrost Gaming's first commercial product launch. This is not just a tool — it's our reputation. First impressions on BuiltByBit determine whether we become known as "that dev who ships quality" or "that dev who overpromised."

We choose quality.

This document outlines the complete path from current state to launch-ready flagship product.

---

📊 CURRENT STATE (April 6, 2026)

✅ What's Built (Phases 1-4 Complete)

• API integrations: CurseForge, Modrinth, Technic, FTB
• Database schema: modpack_versions table
• Dashboard badge: UpdateBadge.tsx component
• Console widget: ModpackVersionCard.tsx component
• Admin panel: Configuration interface
• Cron job: Background version checking
• Rate limiting: 2 requests/minute per server
• 60-second TTL cache for dashboard

⚠️ What's Missing (Launch Blockers)

1. Modrinth auto-detection — Currently manual-only, needs versionId → project_id mapping
2. "Ignore Version" feature — Critical UX for handling version string mismatches
3. Backoff logic — Prevents infinite scanning of vanilla/custom servers
4. Commercial documentation — Setup guide, troubleshooting, FAQ
5. BuiltByBit listing materials — Product description, screenshots, compatibility matrix

🔧 What Works But Needs Polish

• Blueprint packaging (manual deployment steps required)
• Database migrations (need to add new columns)
• Console widget (needs "Ignore Version" button)

---

🏗️ FLAGSHIP COMPLETION ROADMAP

Phase 5: Modrinth Auto-Detection (4-6 hours)

Priority: CRITICAL — Moves us from 60% to 85% market coverage

Architecture (Validated by Gemini):

1. Cron reads modrinth.index.json from server filesystem
2. Extract versionId from manifest
3. Call Modrinth API: GET /v2/version/{versionId}
4. Response contains project_id — save to database
5. Use project_id for future version checks

Database Changes:

ALTER TABLE modpack_versions 
  ADD COLUMN modrinth_version_id VARCHAR(50) NULL;

Code Changes:

• Update CheckModpackUpdates.php command
• Add detectModrinth() method to cron
• Inject DaemonFileRepository for file reads
• Parse modrinth.index.json structure
• Call Modrinth /v2/version/{id} endpoint

Testing:

• Test on Adrenaserver (known Modrinth pack)
• Verify project_id extraction
• Confirm version comparison works

Deliverable: Modrinth packs auto-detect without manual configuration

---

Phase 6: "Ignore Version" Feature (2-3 hours)

Priority: CRITICAL — Eliminates 90% of false-positive support tickets

Problem:

• String comparison (!==) flags v1.2.3-hotfix vs v1.2.4 as different
• User knows they're functionally equivalent
• Without ignore button → support ticket or refund

Solution: Database column + UI button that lets users dismiss version alerts

Database Changes:

ALTER TABLE modpack_versions 
  ADD COLUMN user_ignored_version VARCHAR(50) NULL;

Logic:

• User clicks "Mark as Up-to-Date" in console widget
• Save current latest_version to user_ignored_version
• Badge turns green
• Badge stays green until a NEW latest_version appears (different from ignored version)

UI Changes:

• Add button to ModpackVersionCard.tsx
• Button only shows when update_available = true
• Button label: "Mark as Up-to-Date" or "Ignore This Version"
• Add API endpoint: POST /servers/{server}/modpack/ignore-version

API Endpoint:

public function ignoreVersion(Request $request, Server $server)
{
    $modpackVersion = ModpackVersion::where('server_uuid', $server->uuid)->first();
    
    $modpackVersion->update([
        'user_ignored_version' => $modpackVersion->latest_version
    ]);
    
    return response()->json(['success' => true]);
}

Badge Logic Update:

// In CheckModpackUpdates command
if ($latestVersion !== $installedVersion) {
    // Check if user has ignored this specific version
    if ($modpackVersion->user_ignored_version === $latestVersion) {
        $updateAvailable = false; // Keep badge green
    } else {
        $updateAvailable = true;
    }
}

Deliverable: Users can dismiss false-positive version alerts without support tickets

---

Phase 7: Backoff Logic for Unsupported Servers (1-2 hours)

Priority: HIGH — Prevents Wings API spam for vanilla/custom servers

Problem:

• Cron attempts file detection every hour
• Vanilla servers have no manifest files
• Infinite failed attempts = wasted Wings API calls

Solution (Gemini-Validated): Stop scanning servers after 3 failed attempts until user manually triggers "Force Check"

Database Changes:

ALTER TABLE modpack_versions 
  ADD COLUMN auto_detect_failed_count INT DEFAULT 0,
  ADD COLUMN last_auto_detect_attempt TIMESTAMP NULL;

Logic:

// In CheckModpackUpdates command
if ($modpackVersion->auto_detect_failed_count >= 3) {
    continue; // Skip this server in cron
}

try {
    $detected = $this->attemptAutoDetection($server);
    
    if ($detected) {
        $modpackVersion->update([
            'auto_detect_failed_count' => 0,
            'last_auto_detect_attempt' => now()
        ]);
    } else {
        $modpackVersion->increment('auto_detect_failed_count');
        $modpackVersion->update(['last_auto_detect_attempt' => now()]);
    }
} catch (DaemonConnectionException $e) {
    // Node offline — don't count as failed detection
    continue;
}

UI Changes:

• "Force Check" button in console widget resets auto_detect_failed_count
• Shows message: "Auto-detection paused after 3 failed attempts. Click to retry."

Deliverable: Cron doesn't spam Wings API for unsupported servers

---

Phase 8: Commercial Documentation (3-4 hours)

Priority: CRITICAL — Reduces support tickets by 70%

Structure (Gemini-Validated):

1. README.md (Overview)

• What it does (one paragraph)
• Compatibility matrix table
• System requirements
• Quick links to other docs

2. INSTALLATION.md

• Prerequisites checklist
• Three-command install process
• Database migration steps
• Panel restart instructions
• Verification steps

3. CONFIGURATION.md (The API Key Hub)

CurseForge API Key:

• Step 1: Go to https://console.curseforge.com
• Step 2: Create application
• Step 3: Generate API key
• Step 4: Paste into Admin Panel

Modrinth API Key:

• Step 1: Go to https://modrinth.com/settings/pats
• Step 2: Create Personal Access Token
• Step 3: Set scopes (read-only)
• Step 4: Paste into Admin Panel

4. HOW-IT-WORKS.md (The Tiered System)

Critical Section — Prevents "It's Broken" Tickets

Explain the three-tier detection process:

Tier 1: Egg Variables (Instant, Rarely Present)

• Checks server egg for MODPACK_PLATFORM and MODPACK_ID
• Most eggs don't have these

Tier 2: File Detection (Auto-Discovery, CurseForge + Modrinth)

• Reads manifest.json (CurseForge) or modrinth.index.json (Modrinth)
• Runs in background cron job (hourly)
• Requires manifest files to exist on server

Tier 3: Manual Configuration (Universal Fallback)

• Console widget → "Configure Manually" button
• Works for ANY platform (FTB, Technic, ATLauncher, Custom)
• User enters platform + modpack ID once

Why Your Server Might Not Auto-Detect:

1. It's a vanilla server (no modpack manifest)
2. It's a custom modpack (no manifest from supported platform)
3. It uses FTB/Technic/ATLauncher (manual config required)
4. Manifest file was deleted or moved

5. MANUAL-CONFIGURATION.md

• When to use manual config
• How to find modpack IDs for each platform
• Step-by-step screenshots

6. TROUBLESHOOTING.md

Common Issues:

"My badge is gray / shows 'Not Configured'"

• Server needs manual configuration
• Click "Configure Manually" in console widget

"It says there's an update but I'm already on the latest version"

• Modpack author changed naming convention
• Click "Mark as Up-to-Date" to dismiss alert

"I see a 429 error"

• API rate limit hit (rare)
• Extension respects 2 req/min limit
• Wait 60 seconds and retry

"Auto-detection stopped working"

• 3 failed attempts triggered backoff
• Click "Force Check" to retry
• If still failing, use manual config

"Server is offline/suspended but still shows old version"

• Cron skips offline servers
• Version will update next time server is online

7. FAQ.md

• What platforms are supported?
• Do I need API keys for all platforms?
• How often does it check for updates?
• Can I check updates manually instead of cron?
• What happens if I delete the manifest file?
• Does this work with custom modpacks?
• Can I disable auto-detection for specific servers?

Deliverable: Complete documentation preventing 70% of support tickets

---

Phase 9: BuiltByBit Listing Materials (2-3 hours)

Priority: CRITICAL — Sets accurate expectations, prevents refunds

Product Description Structure:

1. The Hook (One-Sentence Pitch)

Stop checking modpacks manually. Start managing them automatically with the industry's first dual-engine version tracker for Pterodactyl.

2. Value Propositions (Reframe Limitations)

• ✅ 85%+ Instant Coverage: Auto-detection for CurseForge & Modrinth
• ✅ Universal Manual Fallback: Support for ANY platform via simple ID entry
• ✅ Dashboard Pulse: High-visibility status integrated into server list
• ✅ Performance First: Passive background checks, zero panel impact

3. Compatibility Matrix (Top of Listing)

| Platform          | Auto-Detection | Manual Config | Notes                    |
|-------------------|----------------|---------------|--------------------------|
| CurseForge        | ✅ Yes         | ✅ Yes         | Uses manifest.json       |
| Modrinth          | ✅ Yes         | ✅ Yes         | Uses modrinth.index.json |
| FTB (Modern)      | ❌ No          | ✅ Yes         | Requires FTB ID entry    |
| Technic           | ❌ No          | ✅ Yes         | Requires Slug entry      |
| Custom/Vanilla    | ❌ No          | ✅ Yes         | Requires Manual Setup    |

4. Features List

• Automatic version checking for CurseForge & Modrinth modpacks
• At-a-glance dashboard badge showing update status
• Console widget with detailed version information
• Manual configuration for unsupported platforms
• Smart caching (60-second TTL, minimal API usage)
• Rate limiting protection (won't get your API keys banned)
• "Ignore Version" feature for handling naming convention changes
• Admin panel for API key management

5. Requirements

• Pterodactyl Panel 1.12.x or higher
• Blueprint beta-2026-01 or higher
• PHP 8.3+
• PostgreSQL database
• CurseForge API key (free)
• Modrinth API key (free)

6. Installation Three-command install via Blueprint (see documentation for details)

7. "Read Before You Buy" (Bottom of Listing)

1. Vanilla Servers: This extension will not auto-detect vanilla Minecraft servers (no modpack manifest exists)
2. Manifest Dependency: Auto-detection requires manifest.json or modrinth.index.json in server root
3. Exact String Matching: Version comparison uses exact string matching, not semantic versioning. If modpack authors change naming formats, extension will flag for your review.

8. Support & Updates

• Comprehensive documentation included
• Active support via BuiltByBit messages
• Free updates for life

Screenshots Needed:

1. Dashboard with update badges (green, yellow, red states)
2. Console widget showing version details
3. Console widget "Configure Manually" modal
4. Console widget "Mark as Up-to-Date" button
5. Admin panel API key configuration
6. Example of Modrinth auto-detection working
7. Example of manual configuration for FTB pack

Deliverable: Transparent, accurate BuiltByBit listing preventing refunds

---

Phase 10: Blueprint Packaging Fix (2-3 hours)

Priority: HIGH — Ensures clean install experience

Current Issue (from Pathmaker #63):

• build.sh doesn't run on production install
• PHP files stay in extension subfolder
• React components need manual injection

Solution Options:

Option A: Fix Blueprint Packaging

• Research Blueprint native wrapper injection
• Eliminate build.sh dependency
• Ensure PHP files auto-copy on install
• Test clean install cycle

Option B: Provide Clear Manual Steps

• Document exact post-install commands
• Include in INSTALLATION.md
• Test commands on fresh panel
• Accept this as "advanced install" product

Decision: Start with Option B (document manual steps), upgrade to Option A in v1.1

Deliverable: Clean installation process (manual or automated)

---

📋 COMPLETE FEATURE MATRIX

Feature	Status	Priority	Time Estimate
CurseForge auto-detection	✅ Complete	Critical	Done
Modrinth auto-detection	⏳ Phase 5	Critical	4-6 hours
Manual configuration UI	✅ Complete	Critical	Done
Dashboard badge	✅ Complete	Critical	Done
Console widget	✅ Complete	Critical	Done
Admin panel	✅ Complete	Critical	Done
"Ignore Version" button	⏳ Phase 6	Critical	2-3 hours
Backoff logic	⏳ Phase 7	High	1-2 hours
Documentation	⏳ Phase 8	Critical	3-4 hours
BuiltByBit listing	⏳ Phase 9	Critical	2-3 hours
Blueprint packaging	⏳ Phase 10	High	2-3 hours
FTB auto-detection	📦 Phase 11 (v1.1)	Medium	4-6 hours
Technic auto-detection	📦 Phase 11 (v1.1)	Low	4-6 hours

---

⏱️ TIME ESTIMATES

Minimum Viable Flagship (Launch-Ready)

• Phase 5: Modrinth auto-detection — 4-6 hours
• Phase 6: "Ignore Version" feature — 2-3 hours
• Phase 7: Backoff logic — 1-2 hours
• Phase 8: Documentation — 3-4 hours
• Phase 9: BuiltByBit listing — 2-3 hours
• Phase 10: Blueprint packaging — 2-3 hours

Total: 14-21 hours (2-3 work sessions)

Premium Flagship (Optional Enhancements)

• In-panel Setup Wizard — 3-4 hours
• Video tutorials — 4-6 hours
• Beta testing program — 2-3 hours

Total: 9-13 additional hours

---

🎯 LAUNCH CRITERIA

Product is launch-ready when ALL of these are true:

Code Complete:

• ✅ CurseForge auto-detection working
• ✅ Modrinth auto-detection working
• ✅ "Ignore Version" feature implemented
• ✅ Backoff logic prevents API spam
• ✅ Manual configuration UI functional
• ✅ Dashboard badge working (all states)
• ✅ Console widget working (all features)
• ✅ Admin panel working
• ✅ Clean install process documented/automated

Documentation Complete:

• ✅ README.md (overview)
• ✅ INSTALLATION.md (step-by-step)
• ✅ CONFIGURATION.md (API keys)
• ✅ HOW-IT-WORKS.md (tiered system explanation)
• ✅ MANUAL-CONFIGURATION.md (platform-specific guides)
• ✅ TROUBLESHOOTING.md (common issues + solutions)
• ✅ FAQ.md (edge cases covered)

Marketing Complete:

• ✅ BuiltByBit product description written
• ✅ Compatibility matrix included
• ✅ "Read Before You Buy" section added
• ✅ All 7 screenshots taken
• ✅ Pricing tier decided ($14.99 or $19.99)

Testing Complete:

• ✅ Tested on CurseForge pack (auto-detection)
• ✅ Tested on Modrinth pack (auto-detection)
• ✅ Tested on FTB pack (manual config)
• ✅ Tested on vanilla server (graceful failure)
• ✅ Tested "Ignore Version" button
• ✅ Tested offline server handling
• ✅ Tested API rate limiting
• ✅ Fresh install tested on clean panel

Support Ready:

• ✅ Documentation prevents 70% of tickets
• ✅ "Ignore Version" prevents 90% of false-positive complaints
• ✅ Compatibility matrix sets accurate expectations
• ✅ [Support strategy/tooling discussed with Michael — TBD]

---

🚀 SUGGESTED SESSION BREAKDOWN

Session 1 (Chronicler #64 - Today):

• ✅ Gemini consultations (DONE)
• ⏳ Begin Phase 5: Modrinth auto-detection (4-6 hours)
• ⏳ Document this plan (DONE)

Session 2 (Chronicler #65):

• Complete Phase 5: Modrinth auto-detection
• Complete Phase 6: "Ignore Version" feature
• Complete Phase 7: Backoff logic
• Begin Phase 8: Documentation skeleton

Session 3 (Chronicler #66):

• Complete Phase 8: Full documentation
• Complete Phase 9: BuiltByBit listing
• Complete Phase 10: Blueprint packaging
• Final testing & screenshots
• LAUNCH

---

📞 SUPPORT STRATEGY (TBD)

Michael mentioned: "there is something else I need done in regards to this and help with, but lets get everything in place before we address that, it isn't anything related to coding, but support"

Placeholder for future discussion:

• Support ticket system/process?
• Response time commitments?
• Refund policy?
• Update/maintenance schedule?
• Community/Discord support channel?

To be documented after product features are complete.

---

💙 THE FLAGSHIP STANDARD

This is not just a product. This is Firefrost Gaming's introduction to the commercial marketplace.

Every decision prioritizes:

1. Transparency — No surprises, no refunds
2. Quality — Polished, tested, documented
3. Support — 70% of tickets prevented by docs
4. Reputation — "That dev ships quality"

For children not yet born.

---

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

---

Document Status: ACTIVE
Next Update: After Phase 5 completion
Maintained By: Current Chronicler