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

Modpack Version Checker - Commercial Product Development

Project Overview

Build a Python CLI tool that checks CurseForge modpack versions and notifies server admins of updates. This will be sold as a commercial product on BuiltByBit marketplace.

Estimated Revenue: $500-2,600+ based on market analysis

---

Setup Instructions

1. Clone the Firefrost Operations Manual

cd /tmp
git clone https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual.git
cd firefrost-operations-manual

Note: If this fails due to authentication, the planning docs are also available at:

• https://git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual/src/branch/master/docs/tasks/modpack-version-checker

2. Read the Planning Documents

The complete specification exists in docs/tasks/modpack-version-checker/:

Read these files in order:

1. README.md - Project overview and business case
2. IMPLEMENTATION-PLAN.md - Complete technical specification
3. TESTING-GUIDE.md - Testing requirements
4. MARKETING-STRATEGY.md - Go-to-market strategy
5. SUPPORT-PLAYBOOK.md - Customer support procedures

3. Create Project Structure

Based on IMPLEMENTATION-PLAN.md, create:

modpack-version-checker/
├── src/
│   └── modpack_checker/
│       ├── __init__.py
│       ├── cli.py           # Click-based CLI
│       ├── curseforge.py    # API client
│       ├── database.py      # SQLite storage
│       ├── notifier.py      # Discord/webhook notifications
│       └── config.py        # Configuration management
├── tests/
│   ├── test_cli.py
│   ├── test_curseforge.py
│   ├── test_database.py
│   └── test_notifier.py
├── docs/
│   ├── README.md           # User documentation
│   ├── INSTALLATION.md
│   └── API.md
├── setup.py
├── requirements.txt
├── .gitignore
└── LICENSE

---

Development Tasks

Phase 1: Core Functionality (MVP)

Task 1.1: CurseForge API Client

• Implement API authentication
• Create methods for:
  • Get modpack info by ID
  • Get latest file version
  • Parse version numbers
• Handle rate limiting
• Error handling and retries

Task 1.2: Database Layer

• SQLite database for tracking:
  • Watched modpacks
  • Last known versions
  • Check history
  • Configuration
• Migration system for schema updates

Task 1.3: CLI Interface

• Commands:
  • add <modpack-id> - Add modpack to watch list
  • remove <modpack-id> - Remove from watch list
  • list - Show all watched modpacks
  • check - Check for updates now
  • status - Show current versions
• Use Click for clean CLI
• Pretty output with Rich library

Task 1.4: Notification System

• Discord webhook support
• Custom webhook support
• Email notifications (optional)
• Configurable notification format

Phase 2: Advanced Features

Task 2.1: Scheduling

• Built-in scheduler (APScheduler)
• Cron expression support
• Configurable check intervals

Task 2.2: Multi-Server Support

• Track different modpacks per server
• Server groups
• Bulk operations

Task 2.3: Version Comparison

• Semantic version parsing
• Changelog extraction
• Breaking change detection

Phase 3: Polish for Commercial Release

Task 3.1: Documentation

• Complete user guide
• API documentation
• Troubleshooting guide
• Video tutorials (script)

Task 3.2: Packaging

• PyPI package
• Docker image
• Windows .exe (PyInstaller)
• Linux .deb package

Task 3.3: Testing

• Unit tests (90%+ coverage)
• Integration tests
• End-to-end tests
• Performance tests

---

Technical Specifications

Dependencies

Core:

• requests - HTTP client
• click - CLI framework
• rich - Terminal formatting
• pydantic - Data validation
• sqlalchemy - Database ORM

Optional:

• apscheduler - Job scheduling
• pytest - Testing
• black - Code formatting
• pylint - Linting

API Integration

CurseForge API:

• Base URL: https://api.curseforge.com
• Requires API key (free tier available)
• Rate limit: 100 requests/minute
• Endpoints needed:
  • /v1/mods/{modId}
  • /v1/mods/{modId}/files

Database Schema

CREATE TABLE modpacks (
    id INTEGER PRIMARY KEY,
    curseforge_id INTEGER UNIQUE,
    name TEXT,
    current_version TEXT,
    last_checked TIMESTAMP,
    notification_enabled BOOLEAN
);

CREATE TABLE check_history (
    id INTEGER PRIMARY KEY,
    modpack_id INTEGER,
    checked_at TIMESTAMP,
    version_found TEXT,
    notification_sent BOOLEAN,
    FOREIGN KEY (modpack_id) REFERENCES modpacks(id)
);

---

Success Criteria

MVP (Minimum Viable Product)

• ✅ Can track multiple CurseForge modpacks
• ✅ Detects version changes
• ✅ Sends Discord notifications
• ✅ CLI is functional and user-friendly
• ✅ Runs on Linux servers

Commercial Release

• ✅ All MVP features plus:
• ✅ Comprehensive documentation
• ✅ 90%+ test coverage
• ✅ Multiple package formats
• ✅ Professional error messages
• ✅ Configuration file support
• ✅ Scheduling built-in

---

Development Approach

1. Read all planning docs first - Don't start coding until you understand the full scope
2. Build incrementally - Start with core API client, then add features
3. Test as you go - Write tests alongside code
4. Follow the spec - IMPLEMENTATION-PLAN.md has detailed requirements
5. Professional quality - This is a commercial product, code quality matters

---

Notes for Claude Code

• This is a commercial product that will be sold
• Code quality must be production-grade
• Follow Python best practices (PEP 8, type hints, docstrings)
• Prioritize user experience - clear error messages, helpful CLI
• Security matters - handle API keys safely, validate all inputs
• Think about support burden - make it easy to troubleshoot

---

Revenue Model

Pricing Strategy: $9.99 one-time purchase on BuiltByBit

• Conservative: 50-100 sales = $500-1,000
• Moderate: 150-200 sales = $1,500-2,000
• Optimistic: 260+ sales = $2,600+

This is passive income for Firefrost Gaming while building reputation in the marketplace.

---

Questions?

If you need clarification on any requirement, refer back to the planning docs in the firefrost-operations-manual repo, or ask for guidance.

Let's build something awesome that helps Minecraft server admins and generates revenue for Firefrost Gaming!

---

Created for: Claude Code (Research Preview)
Project: Modpack Version Checker
Owner: Firefrost Gaming
Target Market: BuiltByBit Marketplace