firefrost-operations-manual/docs/tasks/modpack-version-checker/README.md

# Modpack Version Checker - Commercial Blueprint Extension

**Product ID:** FFG-PRODUCT-001  
**Status:** READY TO BUILD  
**Estimated Build Time:** 8-10 hours  
**Revenue Projection:** $1,000-6,750 Year 1  
**Created:** February 22, 2026  
**Created By:** The Chronicler #21 with Gemini Pro Research  

---

## 🎯 EXECUTIVE SUMMARY

**What:** Commercial Pterodactyl Blueprint extension that automatically monitors modpack versions across CurseForge, Modrinth, and FTB platforms.

**Why:** Server owners waste 20+ minutes daily manually checking if modpacks are outdated. This solves that permanently with automated monitoring.

**Market Validation:** Competitor ($23.99, ~400 sales = $9,600 revenue) proves strong demand for Pterodactyl automation tools at this price point.

**Unique Value:** Competitor only INSTALLS modpacks. We MONITOR them daily. Different product category, solving the "Day 2-365" problem.

**Revenue Model:** Two-tier pricing
- Standard: $14.99 (CurseForge + Modrinth)
- Professional: $24.99 (+ FTB + Cron automation + Discord webhooks)

---

## 💰 COMMERCIAL VIABILITY

**Market Evidence:**
- ✅ Proven market: $9,600 gross revenue (competitor)
- ✅ Price point validated: $24 accepted by market
- ✅ User pain confirmed: Competitor reviews mention update checking difficulty
- ✅ Feature gap identified: No monitoring tools exist, only installers
- ✅ Development feasible: 8-10 hours (not 12-16, we have all the code)

**Revenue Projections:**
- Conservative (50 sales @ $19.99): $1,000 year 1
- Realistic (150 sales @ $19.99): $3,000 year 1
- Optimistic (300 sales @ $22.49): $6,750 year 1

**Break-even:** 40 sales (2-3 months at realistic pace)

**ROI:** Even worst-case (20 sales) justifies build because it solves Firefrost's internal need (saves 120 hours/year manual checking)

---

## 🏗️ TECHNICAL ARCHITECTURE

### Platform Support
- **CurseForge** - Largest platform (60-70% market), requires API key
- **Modrinth** - Modern platform, no API key needed (works instantly)
- **FTB (Feed The Beast)** - Prestige segment (10-15% market), no API key needed

### Core Components

**Backend (PHP/Laravel):**
```
/app/Services/Extensions/ModpackVersionChecker/
├── ModpackDetector.php          # File scanning & platform detection
├── ModpackCacheService.php      # Egg Variable caching layer
├── Providers/
│   ├── ModpackProviderInterface.php
│   ├── CurseForgeProvider.php   # CurseForge API integration
│   ├── ModrinthProvider.php     # Modrinth API integration
│   └── FtbProvider.php          # FTB API integration
```

**Frontend (React/TypeScript):**
```
/resources/scripts/components/server/
└── ModpackStatusBadge.tsx       # Status badge component
```

**Database:**
- Egg Variables: `MODPACK_PLATFORM`, `MODPACK_ID`
- Stored in Pterodactyl MySQL database
- User-editable (manual override capability)

**Installation:**
- `install.sh` - Idempotent database injection
- `remove.sh` - Clean uninstall
- Blueprint YAML configuration

### Auto-Detection System

**Detection Priority:**
1. FTB (`instance.json`) - Most specific
2. Modrinth (`modrinth.index.json`) - Modern standard
3. CurseForge (`manifest.json`) - Common but sometimes leftover

**Caching Strategy:**
- Scan files on first page load
- Store result in Egg Variable (database)
- Future loads read from cache (fast)
- Force re-scan button for manual refresh

### API Integration

**CurseForge:**
- Requires API key (user-provided, stored in admin panel)
- Graceful degradation if no key (shows "API Key Required" badge)
- Rate limit protection via caching

**Modrinth:**
- Public API (no key needed)
- Works immediately on installation

**FTB:**
- Public API at `api.modpacks.ch`
- No key needed
- Two API calls required (version ID → version string)

---

## 🎨 USER EXPERIENCE

### Dashboard Integration

**Status Badges (Zero-click visibility):**
- 🟢 Green: "CurseForge: v1.0.2 (Up to date)"
- 🔴 Red: "FTB: v2.1.0 (Update Available)"
- 🟡 Yellow: "Platform: Unknown (Click to configure)"

**Source Indicators:**
- 🪄 Auto-detected (magic wand icon)
- 🔧 Manually configured (wrench icon)

**Force Re-scan Button:**
- Resets Egg Variable to `auto`
- Triggers fresh file detection
- Updates cache with new result

### Manual Override

Users can override auto-detection in Pterodactyl Startup tab:
- Set `MODPACK_PLATFORM` manually (curseforge/modrinth/ftb)
- Set `MODPACK_ID` to specific project ID
- Bypass detection entirely for custom packs

---

## 📊 FEATURE GATING

### Standard Tier - $14.99

**Included:**
- ✅ CurseForge support
- ✅ Modrinth support
- ✅ Smart auto-detection
- ✅ Dashboard status badges
- ✅ Manual check button
- ✅ Egg Variable caching
- ✅ Manual override capability
- ✅ Standard support (48h SLA)

**User flow:** Install → Works immediately (Modrinth/FTB) → Optionally add CurseForge API key later

### Professional Tier - $24.99

**Everything in Standard PLUS:**
- ✅ FTB platform support
- ✅ Background cron job (checks every 6 hours)
- ✅ Discord webhook notifications
- ✅ Email alerts
- ✅ Update history tracking
- ✅ Bulk operations (check all servers)
- ✅ Priority support (24h SLA)

**Key differentiator:** Proactive monitoring (cron) vs reactive checking (manual)

---

## 🛠️ DEVELOPMENT ROADMAP

### Phase 1: MVP Build (4-5 hours)

**Hour 1:**
- Set up Blueprint extension skeleton
- Create `blueprint.yml` configuration
- Database migration script for Egg Variables

**Hour 2-3:**
- Implement ModpackDetector service
- Implement 3 API providers (CurseForge, Modrinth, FTB)
- File fingerprinting logic

**Hour 4:**
- Implement ModpackCacheService
- Egg Variable read/write logic

**Hour 5:**
- Create React status badge component
- Blueprint UI injection configuration

**Testing checkpoint:** Works on Firefrost's 11 servers

### Phase 2: Commercial Polish (2-3 hours)

**Hour 1:**
- Admin settings page (API key input)
- Error handling (try/catch all API calls)
- Clear error messages

**Hour 2:**
- Force re-scan button
- Manual override UI
- Loading states

**Hour 3:**
- Write README.md
- User documentation
- API documentation

### Phase 3: Testing & Launch (2-3 hours)

**Hour 1:**
- Test on clean VPS (not Firefrost nodes)
- Run through essential test cases
- Fix any bugs found

**Hour 2:**
- Beta test with 3-5 users (1 week)
- Incorporate feedback
- Final bug fixes

**Hour 3:**
- Create BuiltByBit listing
- Record demo video (4 screenshots)
- Launch

**Total: 8-11 hours actual (not 12-16)**

---

## 🧪 TESTING STRATEGY

### DO NOT test on live Firefrost nodes
- Risk: One bad database query = panel lockup
- Solution: Use $5/month test VPS with clean Pterodactyl install

### Essential Test Cases (Critical Priority)

| Test Case | Expected Result | Pass/Fail |
|-----------|-----------------|-----------|
| Clean install | DB variables created, no errors | |
| CurseForge detection | Parses manifest.json correctly | |
| Modrinth detection | Parses modrinth.index.json | |
| FTB detection | Parses instance.json | |
| API timeout | Shows "API Offline" gracefully | |
| Clean uninstall | Removes variables, restores UI | |

### Beta Testing
- Invite 3-5 users from Pterodactyl Discord
- Duration: 1 week
- Focus: Edge cases (custom packs, weird configs)
- Deliverable: Bug-free v1.0.0

---

## 💬 SUPPORT STRATEGY

**Goal:** Maintain 2-5 hours/month support capacity

**Infrastructure:**
- Discord server (industry standard for BuiltByBit)
- Ticket bot (organize requests)
- GitBook documentation (free)

**Support Deflection Tactics:**

1. **"Blueprint First" Rule**
   - Stated prominently on BuiltByBit page
   - "REQUIREMENT: Blueprint must be installed first"
   - Prevents most support tickets

2. **Clear Error Messages**
   - ✅ "JSON Parse Error: Check manifest.json"
   - ❌ "Error 500"
   - Users can self-diagnose

3. **48-Hour SLA**
   - Posted in Discord
   - Manages expectations
   - Prevents "urgent" pressure

4. **FAQ Section**
   - Answers 8 common questions preemptively
   - Reduces tickets before they happen

---

## 🔄 UPDATE STRATEGY

### Update Delivery
- Upload new `.blueprint` file to BuiltByBit
- Users download, run `blueprint install` again
- Idempotent install.sh safely overwrites

### Versioning (Semantic)
- v1.0.0 = Initial launch
- v1.0.1 = Bug fix (patch)
- v1.1.0 = New feature (minor)
- v2.0.0 = Major rewrite (major)

### Changelog Best Practices
- ✅ User-friendly: "Fixed issue where newer FTB packs showed as unknown"
- ❌ Technical: "Updated FtbApiService.php to parse nested arrays"

### Maintenance Expectations
- API changes: Low frequency (1-2/year)
- Blueprint updates: Monitor compatibility
- Pterodactyl updates: Test before major versions
- **Time:** 2-3 hours/month average

---

## 📈 MARKETING STRATEGY

### Product Title (SEO Optimized)
```
[Pro] Modpack Version Monitor | CurseForge, FTB, Modrinth | Blueprint
```

### Positioning
**Primary:** "Stop manually checking for modpack updates"
**Secondary:** "Automated health monitoring for CurseForge, Modrinth, and FTB"
**Tertiary:** "Works instantly, scales effortlessly"

### Target Audience
1. Server owners managing 3+ modpack servers
2. Hosting companies offering modpack servers
3. Community admins lacking time for manual checks

### Key Differentiators
1. **Only monitoring tool** (competitors only install)
2. **Multi-platform** (CurseForge + Modrinth + FTB)
3. **Auto-detection** (zero configuration)
4. **Professional tier** (cron automation unique to market)

### Competitor Positioning
- **Frame as complementary, not competitive**
- Installer = Day 1 problem (setup)
- Monitor = Day 2-365 problem (maintenance)
- Many hosting companies use BOTH

---

## 🎯 SUCCESS CRITERIA

**Before marking this product COMPLETE:**

- [ ] All essential test cases pass
- [ ] Beta testing complete (3-5 users, 1 week)
- [ ] BuiltByBit listing published
- [ ] Demo video recorded
- [ ] Documentation complete
- [ ] Discord support server created
- [ ] First sale received
- [ ] Support system validated (can handle tickets in 2-5 hours/month)

**Ongoing success metrics:**
- 50+ sales in first 6 months (break-even)
- <5 hours/month support time
- 4+ star average rating on BuiltByBit
- Zero refund requests (quality product)

---

## 📚 DOCUMENT INDEX

**Read these documents for complete implementation:**

1. **README.md** (this file) - Overview and strategy
2. **IMPLEMENTATION-PLAN.md** - Complete code with all Gemini blocks
3. **MARKETING-STRATEGY.md** - BuiltByBit launch materials
4. **TESTING-GUIDE.md** - Test cases and QA procedures
5. **SUPPORT-PLAYBOOK.md** - Operations and support strategy

**All code blocks organized by component in IMPLEMENTATION-PLAN.md**

---

## 🔗 RESEARCH SOURCES

**This product plan was developed through comprehensive research with Gemini Pro covering:**
- Market analysis (competitor products, pricing, reviews)
- Technical architecture (API integration, caching, detection)
- Commercial strategy (pricing, feature gating, positioning)
- Operations planning (support, testing, maintenance)
- Marketing materials (copy, SEO, launch strategy)

**Research session:** February 22, 2026 (Chronicler #21)
**Total research time:** ~4 hours
**Value of research:** Compressed months of traditional planning into single session

---

**Fire + Frost + Foundation = Where Innovation Generates Income** 💙🔥❄️💰

**Built by:** The Chronicler #21  
**For:** Firefrost Gaming (internal use) + BuiltByBit marketplace (passive income)  
**With:** Gemini Pro (architecture) + Claude (execution)