firefrost-operations-manual/docs/planning/modpack-version-checker-research.md

# Modpack Version Checker - Research Summary

**Date:** April 1, 2026  
**Researched by:** Chronicler #52  
**Purpose:** Gather technical resources for MVP development

---

## Blueprint Framework - Key Resources

### Official Documentation
- **Main Site:** https://blueprint.zip/
- **Documentation:** https://blueprint.zip/docs/
- **Quick Start Guide:** https://blueprint.zip/guides/dev/quickstart
- **GitHub:** https://github.com/BlueprintFramework/framework
- **Templates Repo:** https://github.com/BlueprintFramework/templates

### Key Facts About Blueprint
- Open-source extension framework for Pterodactyl Panel
- Fiscally sponsored by The Hack Foundation (501c3 nonprofit)
- Industry-leading modding platform (well-established)
- Extensions install/remove in seconds via CLI
- No manual file editing or merge conflicts
- Laravel/PHP backend + React frontend support
- **Active marketplace on BuiltByBit** (already has Blueprint category)

### Development Workflow
1. **Create extension:** `blueprint -init`
2. **Development location:** `.blueprint/dev/` (relative to Pterodactyl directory)
3. **Build/test:** `blueprint -build` (apply changes to live panel)
4. **Package:** Creates `.blueprint` file for distribution
5. **Install:** `blueprint -i extension.blueprint`

### Extension Structure (from docs)
```
extension-name/
├── conf.yml              # Extension metadata (name, author, version)
├── components.yml        # Component definitions
├── console.yml           # Console/CLI commands
├── admin/               # Admin panel views (Blade templates)
├── controllers/         # Custom PHP controllers
├── database/            # Migrations
└── public/              # Assets (CSS, JS, images)
```

---

## CurseForge API

### API Key Status
**Michael says:** "I think I already have the CurseForge API key"

### Testing the API Key
```bash
curl -H "x-api-key: YOUR_KEY_HERE" \
  "https://api.curseforge.com/v1/mods/search?gameId=432&classId=4471"
```

**What this tests:**
- `gameId=432` = Minecraft
- `classId=4471` = Modpacks
- Should return JSON array of modpack data

### Key Endpoints We'll Need
1. **Search Modpacks:** `/v1/mods/search?gameId=432&classId=4471`
2. **Get Modpack Details:** `/v1/mods/{modId}`
3. **Get Modpack Files:** `/v1/mods/{modId}/files`
4. **Get Latest File:** `/v1/mods/{modId}/files` (filter by latest)

### Rate Limits (to verify)
- Need to check CurseForge API docs for rate limits
- BYOK model means each buyer uses their own limits
- We cache results, so checking once per 12-24 hours is fine

---

## Modrinth API

### API Docs
- **Main API:** https://docs.modrinth.com/api-spec/
- **No API key required** (public API, rate limited by IP)
- **User-Agent header required** (per Gemini's guidance)

### User-Agent Format (per Gemini)
```
FirefrostExtension/1.0 (Contact: admin@buyer-domain.com)
```

### Key Endpoints We'll Need
1. **Get Project:** `/v2/project/{id|slug}`
2. **Get Project Versions:** `/v2/project/{id|slug}/version`
3. **Search Projects:** `/v2/search?facets=[["project_type:modpack"]]`

### Rate Limits
- Public API, IP-based rate limiting
- Need to check exact limits in docs
- Same 12-24 hour caching strategy applies

---

## BuiltByBit Marketplace

### Key Facts
- Blueprint category already exists: https://builtbybit.com/resources/blueprint.29609/
- Active marketplace with lots of Blueprint extensions
- Pricing range for extensions: $5-$30 typically
- Gemini recommended: **$15** (sweet spot)

### Top Blueprint Extensions (for research)
From search results, popular extensions include:
- Announcements system
- Theme customizations
- Server management tools
- Analytics/monitoring tools

### Submission Requirements (need to research)
- Product description
- Screenshots
- Installation guide
- Support policy
- License terms
- Refund policy

---

## Pterodactyl Modpack Installer Egg

### Environment Variables (per Gemini)
The Modpack Installer egg uses environment variables to specify platform:
- Common variable names: `INSTALL_TYPE`, `PLATFORM`, `MODPACK_API`
- Values: `curseforge`, `modrinth`, `ftb`, `atlauncher`, `technic`, `voidswrath`

### Detection Strategy
```php
// Pseudocode
$envVars = $server->environment;
$platform = $envVars['INSTALL_TYPE'] ?? $envVars['PLATFORM'] ?? 'unknown';

if (in_array($platform, ['curseforge', 'modrinth'])) {
    $is_supported = true;
} else {
    $is_supported = false;
    $unsupported_reason = "Platform '$platform' does not provide public API";
}
```

---

## Database Schema (Final from Gemini)

```sql
CREATE TABLE modpack_version_tracker (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    server_id INT NOT NULL,
    platform VARCHAR(50) NOT NULL,  -- Future-proof (not ENUM)
    project_id VARCHAR(255) NOT NULL,
    current_version_id VARCHAR(255),
    latest_version_id VARCHAR(255),
    is_supported BOOLEAN DEFAULT TRUE,
    unsupported_reason VARCHAR(255),  -- NULL if supported
    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
);
```

---

## Laravel Task Scheduler

### How It Works (per Gemini)
- Pterodactyl already runs `php artisan schedule:run` every minute via cron
- We inject our version-checking logic into Laravel's Task Scheduler
- No separate systemd service needed (plug-and-play for buyers)

### Implementation Pattern
```php
// In our extension's service provider
protected function schedule(Schedule $schedule)
{
    $schedule->call(function () {
        // Check modpack versions
    })->everyTwelveHours(); // Configurable by buyer
}
```

---

## Next Steps - Action Items

### Immediate (Tonight/Tomorrow)
1. ✅ **Test CurseForge API key** (Michael to run curl command)
2. ⏳ **Read Blueprint quick start guide** (blueprint.zip/guides/dev/quickstart)
3. ⏳ **Clone Blueprint templates repo** (for extension scaffold)
4. ⏳ **Read CurseForge API docs** (endpoints, rate limits, authentication)
5. ⏳ **Read Modrinth API docs** (endpoints, User-Agent requirements)

### Research Phase (1-2 days)
1. ⏳ Study Blueprint extension examples on GitHub
2. ⏳ Review BuiltByBit Blueprint marketplace listings
3. ⏳ Document exact API calls needed for both platforms
4. ⏳ Create development environment on Dev VPS
5. ⏳ Test API calls manually (curl/Postman)

### Development Phase (After Research)
1. Scaffold extension with Blueprint CLI
2. Implement platform detection
3. Build API integration
4. Create admin UI
5. Test on Panel VPS

---

## Questions to Answer During Research

1. **CurseForge:**
   - Exact rate limits?
   - How to detect deleted modpacks (404 handling)?
   - Best way to compare version IDs?

2. **Modrinth:**
   - Exact rate limits?
   - User-Agent format verification?
   - Version comparison logic?

3. **Blueprint:**
   - How to add admin settings page?
   - How to create database migrations?
   - How to schedule Laravel tasks from extension?
   - How to package for distribution?

4. **Pterodactyl:**
   - How to query server environment variables?
   - Where is server data stored in Panel database?
   - API vs direct database access?

---

**Status:** Research phase ready to begin  
**Next Action:** Michael tests CurseForge API key  
**Timeline:** 1-2 days research → 1-2 weeks development → Launch

---

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