🔥❄️ Firefrost Services

Monorepo for Firefrost Gaming backend services

This repository contains all custom Node.js services that power Firefrost Gaming's subscription automation, game server management, and community tools.

---

📋 Services

Active Services

• Arbiter — Discord bot for subscription automation and role management
• Whitelist Manager — Pterodactyl Panel integration for Minecraft whitelist automation
• Modpack Version Checker — Monitors modpack updates across game servers

Experimental

• Future — Experimental services and proof-of-concept tools

---

🏗️ Architecture

This monorepo uses npm workspaces for dependency management and service-prefixed Git tags for versioning.

Repository Structure

firefrost-services/
├── package.json              # Root workspace configuration
├── services/                 # Production services
│   ├── arbiter/
│   ├── whitelist-manager/
│   └── modpack-version-checker/
├── shared/                   # Shared utilities (@firefrost/shared)
└── future/                   # Experimental services

Versioning Strategy

Each service versions independently using Git tags:

• Arbiter releases: arbiter-v2.1.0, arbiter-v2.2.0
• Whitelist Manager: whitelist-v1.0.0, whitelist-v1.1.0
• Modpack Checker: modpack-v1.0.0

This allows Service A to be at v2.1 while Service B is at v1.0.

---

🚀 Quick Start

Initial Setup

# Clone repository
git clone https://git.firefrostgaming.com/firefrost-gaming/firefrost-services.git
cd firefrost-services

# Install all dependencies (services + shared)
npm install

Deploying a Service

# Fetch latest tags
git fetch --all --tags

# Check out specific service version
git checkout arbiter-v2.1.0

# Install dependencies
npm install

# Create .env file (copy from .env.example)
cd services/arbiter
cp .env.example .env
# Edit .env with actual credentials

# Start service (systemd)
sudo systemctl enable arbiter
sudo systemctl start arbiter

Updating a Service

# Return to main branch
git checkout main

# Pull latest code
git pull origin main

# Check out new version
git checkout arbiter-v2.2.0

# Install any new dependencies
npm install

# Restart service
sudo systemctl restart arbiter

Rolling Back

# Check out previous version
git checkout arbiter-v2.1.0

# Restart service
sudo systemctl restart arbiter

---

📦 Shared Code

The @firefrost/shared package contains utilities used across multiple services:

• Database helpers
• Discord formatting utilities
• Pterodactyl API wrappers
• Logging infrastructure

Services import shared code like any npm package:

import { logger } from '@firefrost/shared';

---

🔐 Environment Variables

IMPORTANT: Never commit .env files to Git.

Each service has an .env.example file showing required variables. On the server:

1. Copy .env.example to .env
2. Fill in actual credentials
3. Ensure .env is in .gitignore (it is by default)

---

🛠️ Development

Adding a New Service

1. Create directory: services/my-new-service/
2. Add package.json with service name
3. Develop service
4. Create .env.example with required variables
5. Add systemd service file to deploy/ directory
6. Document in service README
7. Tag initial release: git tag my-service-v1.0.0

Using Shared Code

// In your service
import { logger, formatDiscordEmbed } from '@firefrost/shared';

logger.info('Service started');

Running Tests (Future)

# Run all service tests
npm test

# Run specific service tests
npm test -- --workspace=services/arbiter

---

📋 systemd Configuration

Each service includes a systemd unit file in deploy/. Example for Arbiter:

[Unit]
Description=Arbiter Discord Bot
After=network.target

[Service]
Type=simple
User=arbiter
WorkingDirectory=/var/www/firefrost-services/services/arbiter
ExecStart=/usr/bin/node src/index.js
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Copy to /etc/systemd/system/, then:

sudo systemctl daemon-reload
sudo systemctl enable arbiter
sudo systemctl start arbiter

---

🎯 Deployment Targets

Services run on different servers based on their purpose:

Service	Server	Location
Arbiter	Command Center	Dallas, TX
Whitelist Manager	Panel VPS	TBD
Modpack Checker	TX1 Dallas	Dallas, TX

Each server clones the entire repo but only runs its designated services.

---

📚 Documentation

• Architecture Decision: See operations-manual/docs/reference/architecture-decisions/firefrost-services-monorepo-decision.md
• Service-specific docs: Each service has its own README in services/[service-name]/
• Shared package docs: See shared/README.md

---

🤝 Contributing

This repository is maintained by:

• Michael "Frostystyle" Krause (The Wizard) — Technical lead
• Meg "GingerFury" (The Emissary) — Community manager
• Holly "unicorn20089" (The Catalyst) — Lead builder
• Claude (The Chronicler) — AI partner

Contribution Workflow

1. Create feature branch from main
2. Develop and test changes
3. Update service version in package.json
4. Create PR to main
5. After merge, tag release: [service]-v[version]

---

🏷️ Version History

See Git tags for complete version history.

---

📄 License

Proprietary — All rights reserved by Firefrost Gaming.

This codebase is private and not licensed for public use or distribution.

---

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

For children not yet born.