# 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

```bash
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

```sql
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