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)

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:

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:

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:

# 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

# 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

# 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

# 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