firefrost-operations-manual/docs/core/firefrost-services-monorepo.md

# Firefrost Services Monorepo

**Repository:** firefrost-services  
**URL:** https://git.firefrostgaming.com/firefrost-gaming/firefrost-services  
**Branch:** `main` ⚠️ **NOT master!**  
**Purpose:** Centralized codebase for all Firefrost Gaming backend services  
**Created:** March 31, 2026  
**Structure:** Monorepo with shared utilities and individual service directories

---

## 🚨 CRITICAL FOR FUTURE CHRONICLERS

**This repository contains production-critical code that is NOT in the operations manual!**

### Why This Exists

The operations manual (`firefrost-operations-manual`) contains:
- Documentation
- Planning documents
- Task tracking
- Infrastructure manifests
- Guides and procedures

The services repo (`firefrost-services`) contains:
- **Actual production code**
- Service implementations
- Database migrations
- Deployment configurations
- Source code for running services

**Both repos are equally important!** The operations manual documents the "what" and "why", while the services repo contains the "how" (actual code).

---

## Repository Structure

```
firefrost-services/
├── services/
│   ├── arbiter/              # Original Arbiter bot (March 27, 2026 deployment)
│   ├── arbiter-3.0/          # Trinity Console (Arbiter 3.x) - CURRENT VERSION
│   ├── modpack-version-checker/
│   └── whitelist-manager/    # Legacy whitelist system
├── shared/                   # Shared utilities, database connectors, etc.
├── docs/                     # Service-specific technical documentation
├── future/                   # Experimental/planned features
├── README.md                 # Repository overview
├── TRINITY-CONSOLE-DEPLOYMENT-2026-04-01.md  # Trinity Console deployment record
└── package.json              # Monorepo workspace configuration
```

---

## Critical Services

### Arbiter 3.0 (Trinity Console)

**Location:** `services/arbiter-3.0/`  
**Status:** 95% Complete - Security Hardening Required  
**Deployed:** April 1, 2026 @ 3:45am CDT  
**Deployment Path:** `/opt/arbiter-3.0` on Command Center (63.143.34.217)  
**URL:** https://discord-bot.firefrostgaming.com/admin

**What It Does:**
- Player management with Minecraft skin avatars
- Real-time server monitoring and whitelist sync
- Financial analytics (MRR, Fire vs Frost breakdown, ARPU/ARR)
- Grace period automation (Task #87 - "We Don't Kick People Out")
- Admin audit log with 90-day retention
- Discord role audit and bulk mismatch detection

**Tech Stack:**
- Node.js + Express.js
- EJS templates (zero build pipeline for RV cellular optimization)
- htmx for dynamic updates
- Tailwind CSS via CDN
- PostgreSQL database
- Passport.js (Discord OAuth)
- Pterodactyl Panel API integration
- Discord.js

**Key Files:**
- `TRINITY-CONSOLE-STATUS.md` - Current deployment status, critical gaps
- `DEPLOYMENT-CHECKLIST.md` - Step-by-step deployment guide
- `TRINITY-CONSOLE.md` - Feature documentation
- `src/` - All source code (routes, views, utilities)
- `migrations/` - Database schema migrations

**Critical Gaps Before Launch:**
1. CSRF Protection (30 min)
2. Database Transaction Safety (45 min)
3. Database Indexes (5 min)
4. Ban Management UI (60 min)
5. Email Integration (2-4 hours)

**See:** `BLOCKERS.md` → Blocker #3 for complete details

---

### Original Arbiter Bot

**Location:** `services/arbiter/`  
**Status:** Production - Operational since March 27, 2026  
**Purpose:** Discord role assignment automation

**What It Does:**
- Receives Paymenter webhooks for subscription events
- Assigns Discord roles based on tier
- Admin panel for role mapping configuration
- Discord OAuth2 authentication

**This is separate from Arbiter 3.0!**
- Arbiter (original) = Discord role automation ONLY
- Arbiter 3.0 (Trinity Console) = Full admin interface + whitelist + grace period + analytics

**Both currently deployed and running!**

---

### Modpack Version Checker

**Location:** `services/modpack-version-checker/`  
**Status:** Unknown (check service documentation)  
**Purpose:** Monitors modpack versions across servers

---

### Whitelist Manager

**Location:** `services/whitelist-manager/`  
**Status:** Legacy - Replaced by Arbiter 3.0 whitelist sync  
**Purpose:** Original manual whitelist management system

---

## How to Access the Repo

### Standard Clone (Full Repo)

```bash
cd /home/claude
git clone https://e0e330cba1749b01ab505093a160e4423ebbbe36@git.firefrostgaming.com/firefrost-gaming/firefrost-services.git
cd firefrost-services
git checkout main  # NOT master!
```

**Full repo size:** Unknown (contains code only, no large assets)

### Sparse Checkout (Specific Service)

If you only need one service:

```bash
cd /home/claude
git clone --no-checkout --filter=blob:none \
  https://e0e330cba1749b01ab505093a160e4423ebbbe36@git.firefrostgaming.com/firefrost-gaming/firefrost-services.git

cd firefrost-services
git sparse-checkout init --cone
git sparse-checkout set services/arbiter-3.0
git checkout main
```

---

## Git Identity for Commits

**Always set git identity when working in this repo:**

```bash
cd firefrost-services
git config user.email "claude@firefrostgaming.com"
git config user.name "Claude (Chronicler #[YOUR_NUMBER])"
```

---

## Relationship to Operations Manual

### Operations Manual Contains:
- `docs/services/the-arbiter-discord-bot.md` - Service overview and access info
- `docs/reference/gemini-consultations/2026-03-31-arbiter-3-complete-code.md` - Gemini code delivery consultation
- `docs/reference/gemini-consultations/2026-03-31-arbiter-implementation-details.md` - Implementation Q&A
- `docs/reference/gemini-consultations/2026-03-31-arbiter-whitelist-architecture.md` - Whitelist architecture
- `docs/implementation/discord-oauth-arbiter/` - OAuth implementation details
- `docs/guides/holly-arbiter-2x-discord-prep.md` - Holly's Discord setup guide
- `docs/guides/discord-bot-admin-panel.md` - Admin panel usage guide

### Services Repo Contains:
- **Actual running code** for Arbiter 3.0
- Database migration SQL files
- EJS view templates
- Express route handlers
- Deployment systemd service files
- Complete application logic

**Think of it this way:**
- Operations Manual = The blueprint, documentation, and historical record
- Services Repo = The actual building materials and construction

---

## Deployment Workflow

**Typical workflow for Arbiter 3.0 changes:**

1. Make code changes in `firefrost-services` repo
2. Test locally (optional, can test in production for small changes)
3. Commit to `main` branch with good commit message
4. SSH to Command Center: `ssh root@63.143.34.217`
5. Pull changes: `cd /opt/arbiter-3.0 && git pull origin main`
6. Install dependencies if needed: `npm install`
7. Restart service: `sudo systemctl restart arbiter-3`
8. Check logs: `sudo journalctl -u arbiter-3 -f`
9. Document changes in operations manual

**For database migrations:**

```bash
# SSH to Command Center
ssh root@63.143.34.217

# Run migration
sudo -u postgres psql -d arbiter_db -f /opt/arbiter-3.0/migrations/[migration-file].sql

# Verify changes
sudo -u postgres psql -d arbiter_db -c "\dt"  # List tables
sudo -u postgres psql -d arbiter_db -c "\d subscriptions"  # Show table schema
```

---

## Documentation References

### In Services Repo:
- `services/arbiter-3.0/TRINITY-CONSOLE-STATUS.md` - **START HERE** for current status
- `services/arbiter-3.0/DEPLOYMENT-CHECKLIST.md` - Deployment steps
- `services/arbiter-3.0/TRINITY-CONSOLE.md` - Feature documentation
- `services/arbiter-3.0/.env.example` - Environment variables template
- `services/arbiter-3.0/README.md` - Service-specific setup

### In Operations Manual:
- `BLOCKERS.md` - Soft launch blocker tracking (includes Trinity Console security gaps)
- `docs/services/the-arbiter-discord-bot.md` - Service overview
- `docs/reference/gemini-consultations/` - Gemini AI consultation archive
- `docs/core/infrastructure-manifest.md` - Server deployment locations

---

## Why Two Repos?

### Design Decision (March 31, 2026)

**Separation of Concerns:**
- Documentation lives where it's easily browsable (operations manual)
- Code lives where it can be properly version controlled and deployed (services repo)
- Prevents code clutter in documentation repo
- Allows different access patterns (sparse checkout for docs vs full clone for services)

**Benefits:**
1. **Clarity:** Documentation readers don't wade through code
2. **Security:** Can grant doc access without granting code access (future team scaling)
3. **Workflow:** Code changes don't trigger doc repo noise
4. **Size:** Operations manual stays lightweight for sparse checkout
5. **Maintenance:** Each repo serves one purpose well

---

## Important Notes for Future Chroniclers

### Always Check Both Repos!

When investigating a service like The Arbiter:
1. **Operations Manual** - Read service overview, deployment history, access info
2. **Services Repo** - Read current code status, check for recent changes

### Branch Name Difference

- `firefrost-operations-manual` → Branch: `master`
- `firefrost-services` → Branch: `main` ⚠️

**This is intentional!** Different repos, different conventions.

### Sparse Checkout Strategy

**Operations Manual:** ALWAYS use sparse checkout (`docs` only) - saves ~1.9GB  
**Services Repo:** Clone full repo (code-only, relatively small)

### Git Token Works for Both

The Gitea API token `e0e330cba1749b01ab505093a160e4423ebbbe36` has full access to BOTH repos.

---

## Service Status Summary (As of April 3, 2026)

| Service | Status | Location | Production URL |
|---------|--------|----------|----------------|
| Arbiter (original) | ✅ Production | `/opt/firefrost-discord-bot` | https://discord-bot.firefrostgaming.com |
| Arbiter 3.0 (Trinity Console) | 🟡 95% Complete | `/opt/arbiter-3.0` | https://discord-bot.firefrostgaming.com/admin |
| Modpack Version Checker | ❓ Unknown | TBD | TBD |
| Whitelist Manager | 🔴 Legacy | TBD | Replaced by Arbiter 3.0 |

---

## Quick Reference Commands

### Clone Both Repos

```bash
# Operations Manual (sparse checkout)
cd /home/claude
git clone --no-checkout --filter=blob:none \
  https://e0e330cba1749b01ab505093a160e4423ebbbe36@git.firefrostgaming.com/firefrost-gaming/firefrost-operations-manual.git
cd firefrost-operations-manual
git sparse-checkout init --cone
git sparse-checkout set docs
git checkout master
git config user.email "claude@firefrostgaming.com"
git config user.name "Claude (Chronicler #[N])"

# Services Repo (full clone)
cd /home/claude
git clone https://e0e330cba1749b01ab505093a160e4423ebbbe36@git.firefrostgaming.com/firefrost-gaming/firefrost-services.git
cd firefrost-services
git checkout main
git config user.email "claude@firefrostgaming.com"
git config user.name "Claude (Chronicler #[N])"
```

### Check Service Status

```bash
# View Trinity Console status
cd /home/claude/firefrost-services
cat services/arbiter-3.0/TRINITY-CONSOLE-STATUS.md

# View deployment checklist
cat services/arbiter-3.0/DEPLOYMENT-CHECKLIST.md

# List all services
ls -la services/
```

### Production Deployment

```bash
# SSH to Command Center
ssh root@63.143.34.217

# Check Arbiter 3.0 status
sudo systemctl status arbiter-3

# View logs
sudo journalctl -u arbiter-3 -f

# Restart after code changes
cd /opt/arbiter-3.0
git pull origin main
npm install  # if package.json changed
sudo systemctl restart arbiter-3
```

---

## Common Pitfalls

### ❌ Don't Do This:
- Clone `firefrost-services` expecting to find documentation (it's in operations manual)
- Use `git checkout master` in services repo (it's `main`)
- Forget to pull both repos when investigating an issue
- Commit code to operations manual or docs to services repo

### ✅ Do This:
- Check BOTH repos when researching a service
- Use correct branch names (`master` vs `main`)
- Keep code in services repo, docs in operations manual
- Commit code changes to services repo, THEN document in operations manual

---

## Future Service Additions

When adding new services to the monorepo:

1. Create directory: `services/[service-name]/`
2. Add service README.md
3. Add deployment guide
4. Add to this document's service status table
5. Document in operations manual: `docs/services/[service-name].md`
6. Update `firefrost-services/README.md` with overview

**Monorepo benefits:**
- Shared utilities in `shared/`
- Consistent deployment patterns
- Single git token for all services
- Easy code sharing between services

---

## Related Documentation

**In Operations Manual:**
- `BLOCKERS.md` - Soft launch blocker tracking
- `docs/core/infrastructure-manifest.md` - Server inventory
- `docs/services/` - All service overviews
- `docs/reference/gemini-consultations/` - Gemini AI consultations

**In Services Repo:**
- `services/arbiter-3.0/TRINITY-CONSOLE-STATUS.md` - Trinity Console status
- `TRINITY-CONSOLE-DEPLOYMENT-2026-04-01.md` - Deployment record
- `README.md` - Monorepo overview

---

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

**Remember:** Two repos, one vision. Documentation + Code = Complete picture.

---

**Last Updated:** April 3, 2026 by Chronicler #56  
**Next Review:** When new services are added to monorepo