firefrost-services/README.md

# 🔥❄️ 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](services/arbiter/)** — Discord bot for subscription automation and role management
- **[Whitelist Manager](services/whitelist-manager/)** — Pterodactyl Panel integration for Minecraft whitelist automation
- **[Modpack Version Checker](services/modpack-version-checker/)** — Monitors modpack updates across game servers

### Experimental

- **[Future](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

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

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

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

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

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

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

logger.info('Service started');
```

### Running Tests (Future)

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

```ini
[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:

```bash
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](https://git.firefrostgaming.com/firefrost-gaming/firefrost-services/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.**