docs: Add comprehensive Trinity Console documentation

WHAT: Complete operations manual documentation for Trinity Console (Arbiter 3.0) CONTENTS: - Overview and architecture - Access control (The Trinity) - All 7 modules documented * Dashboard * Servers (Server Matrix) * Players (Player Management) * Financials (placeholder status noted) * Grace Period Dashboard * Audit Log * Role Audit - Database schema (3 new tables, enhanced subscriptions) - Tier system (11 tiers: Fire/Frost/Universal paths) - Deployment details - Mobile responsive support - Development workflow - Phase 2 roadmap - Troubleshooting guide - Security considerations - Monitoring and support STATUS: - Trinity Console deployed April 1, 2026 at 5:00 AM CDT - 95% complete (Financials placeholder) - Mobile responsive (Holly's fix included) - Production ready BUILT BY: - Zephyr (Chronicler #50) - 9-hour build session - Gemini AI - Architecture review and guidance - Chronicler #51 - 2-hour deployment FOR: - The Trinity: Michael, Meg, Holly - Future Chroniclers who need to understand the system - Operations reference and troubleshooting FILE LOCATION: docs/services/trinity-console.md Fire + Frost + Foundation = Where Love Builds Legacy 🔥❄️💙 Signed-off-by: Claude (Chronicler #51) <claude@firefrostgaming.com>
2026-04-01 10:33:08 +00:00
parent 6222d57044
commit 9453bc5a12
1 changed files with 607 additions and 0 deletions
--- a/docs/services/trinity-console.md
+++ b/docs/services/trinity-console.md
@@ -0,0 +1,607 @@
+# Trinity Console - Admin Control Center
+
+**Service:** Trinity Console (Arbiter 3.0 Admin Panel)  
+**Purpose:** Unified admin interface for Firefrost Gaming operations  
+**Server:** Command Center (63.143.34.217)  
+**Status:** ✅ Deployed and operational  
+**Deployed:** April 1, 2026, 5:00 AM CDT  
+**Deployed by:** Chronicler #51  
+**Built by:** Zephyr (Chronicler #50) + Gemini AI
+
+---
+
+## Overview
+
+Trinity Console is the administrative control center for Firefrost Gaming. It provides The Trinity (Michael, Meg, Holly) with a unified web interface to manage players, monitor servers, track revenue, handle grace periods, audit actions, and diagnose role issues.
+
+**URL:** https://discord-bot.firefrostgaming.com/admin
+
+**Built for RV Life:** Designed to run remotely with cellular connection support, enabling full operation from anywhere in the United States.
+
+---
+
+## Architecture
+
+**Technology Stack:**
+- **Backend:** Node.js + Express.js
+- **Frontend:** EJS templates + htmx + Tailwind CSS
+- **Database:** PostgreSQL (arbiter_db)
+- **Authentication:** Discord OAuth2 + Passport.js
+- **Security:** CSRF protection (csurf middleware)
+- **Hosting:** Command Center VPS, Nginx reverse proxy
+
+**Integration Points:**
+```
+Trinity Console
+    ├─ PostgreSQL Database (subscriptions, users, audit logs)
+    ├─ Pterodactyl Panel API (server management, whitelists)
+    ├─ Discord API (role diagnostics, member data)
+    └─ Paymenter (future: billing integration)
+```
+
+---
+
+## Access Control
+
+**Authorized Users (The Trinity):**
+- **Holly** (unicorn20089): Discord ID `269225344572063754`
+- **Michael** (Frostystyle): Discord ID `219309716021444609`
+- **Meg** (Gingerfury66): Discord ID `669981568059703316`
+
+**Authentication Flow:**
+1. Visit `/admin` → Redirects to Discord OAuth
+2. Discord authorization → Callback to Trinity Console
+3. Middleware checks Discord ID against ADMIN_USERS whitelist
+4. Session created → Access granted
+
+**Security:**
+- Discord OAuth2 for identity verification
+- Session-based authentication
+- CSRF token protection on all POST requests
+- Trinity-only access (403 for unauthorized users)
+
+---
+
+## Modules
+
+Trinity Console consists of 7 integrated modules:
+
+### 1. Dashboard
+**Purpose:** High-level overview of all operations  
+**Features:**
+- Active subscriber count
+- Total MRR (Monthly Recurring Revenue)
+- Server online status (12 game servers)
+- Last sync timestamp
+- Quick navigation to other modules
+
+### 2. Servers (Server Matrix)
+**Purpose:** Real-time game server monitoring and control  
+**Features:**
+- List all 12 Minecraft servers (TX1 Dallas, NC1 Charlotte)
+- Server online/offline status
+- Whitelist enabled/disabled status
+- Last whitelist sync timestamp
+- Force sync whitelist (per server or all servers)
+- Toggle whitelist mode
+- Automatic polling for status updates
+
+**Key Actions:**
+- **Sync Now:** Forces immediate whitelist sync with Pterodactyl Panel
+- **Sync All:** Syncs all 12 servers simultaneously
+- **Toggle Whitelist:** Enables/disables whitelist mode (requires server restart warning)
+
+### 3. Players (Player Management)
+**Purpose:** Subscriber and player database management  
+**Features:**
+- Search players by Discord ID or Minecraft username
+- View player Minecraft skins (rendered live)
+- Display subscription tier (Fire/Frost/Admin/Sovereign)
+- Show status (active, lifetime, grace_period, cancelled)
+- Pagination for large player lists
+- Mobile-responsive design
+
+**Tier Display:**
+- **Fire Path:** Orange badges (Fire Elemental, Fire Knight, Fire Master, Fire Legend)
+- **Frost Path:** Cyan badges (Frost Elemental, Frost Knight, Frost Master, Frost Legend)
+- **Universal:** Purple badges (The Awakened, Admin, Sovereign)
+
+**Status Indicators:**
+- 🟢 Green dot: Active or lifetime subscriptions
+- 🟡 Yellow dot: Grace period (payment failed, 3 days to recover)
+- 🔴 Red dot: Cancelled or expired
+
+**Future Enhancement:** Edit button for tier changes (currently shows "Coming Soon")
+
+### 4. Financials & Analytics
+**Purpose:** Revenue tracking and business intelligence  
+**Status:** ⚠️ Placeholder (Phase 2 implementation pending)  
+**Planned Features:**
+- Total MRR calculation
+- Fire vs Frost path revenue breakdown
+- Tier-by-tier subscriber counts
+- At-risk MRR (grace period subscriptions)
+- Lifetime revenue from Sovereign tier
+- 7-day recovery rate tracking
+- Monthly growth metrics
+
+**Implementation Status:** Basic page structure deployed, full data integration queued for later today (45-60 min work)
+
+### 5. Grace Period Dashboard
+**Purpose:** Recovery mission control for failed payments  
+**Features:**
+- "We Don't Kick People Out" philosophy
+- List all subscribers in grace period
+- Total at-risk MRR calculation
+- Countdown timers (hours remaining until expiry)
+- Payment failure reasons
+- Manual override actions:
+  - **Extend 24h:** Adds 24 hours to grace period
+  - **Manual Payment:** Marks payment as received, restores active status
+- Email all at-risk button (Phase 2)
+
+**Grace Period Policy:**
+- Payment failure → Automatic 3-day grace period
+- After 3 days → Downgrade to permanent Awakened tier ($1)
+- Never remove access completely
+- Chargeback → Immediate permanent ban (no grace period)
+
+### 6. Audit Log (Accountability Audit)
+**Purpose:** Permanent record of all Trinity actions  
+**Features:**
+- Logs every administrative action
+- Filter by admin (Michael, Meg, Holly)
+- Filter by action type (force_sync, tier_change, manual_override, etc.)
+- Timestamp for each action
+- Target identifier (which server or player was affected)
+- JSON details for complex actions
+- Chronological feed (newest first)
+
+**Logged Actions:**
+- Server whitelist syncs
+- Grace period extensions
+- Manual payment overrides
+- Role assignments
+- Tier changes
+- Server configuration changes
+
+**Purpose:** Accountability, troubleshooting, and compliance tracking
+
+### 7. Role Audit (Discord Role Diagnostics)
+**Purpose:** Detect and fix Discord role mismatches  
+**Features:**
+- **Run Diagnostic Scan:** Compares Discord roles vs database subscriptions
+- Finds subscribers without Discord roles
+- Finds Discord members with roles but no subscription
+- One-click resync for mismatched users
+- Perfect sync confirmation message
+
+**Use Cases:**
+- New subscriber not getting role → Detected and fixed
+- Cancelled subscriber still has role → Detected and removed
+- Manual role grants (for testing) → Detected as mismatch
+- Post-migration role cleanup
+
+---
+
+## Database Schema
+
+Trinity Console uses 3 new tables plus enhanced `subscriptions`:
+
+### New Tables
+
+**1. player_history**
+```sql
+CREATE TABLE player_history (
+    id SERIAL PRIMARY KEY,
+    discord_id VARCHAR(255) REFERENCES users(discord_id),
+    previous_tier INT,
+    new_tier INT,
+    change_reason VARCHAR(255), -- 'upgrade', 'downgrade', 'payment_failed', 'manual'
+    changed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+**2. admin_audit_log**
+```sql
+CREATE TABLE admin_audit_log (
+    id SERIAL PRIMARY KEY,
+    admin_discord_id VARCHAR(255),
+    admin_username VARCHAR(255),
+    action_type VARCHAR(50), -- 'force_sync', 'manual_role_assign', 'tier_change'
+    target_identifier VARCHAR(255), -- Server ID or Player Discord ID
+    details JSONB,
+    performed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+**3. banned_users**
+```sql
+CREATE TABLE banned_users (
+    id SERIAL PRIMARY KEY,
+    discord_id VARCHAR(255) UNIQUE,
+    minecraft_username VARCHAR(255),
+    minecraft_uuid VARCHAR(255),
+    ban_reason VARCHAR(255), -- 'chargeback', 'tos_violation', 'manual'
+    banned_by_discord_id VARCHAR(255),
+    banned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    notes TEXT
+);
+```
+
+### Enhanced subscriptions Table
+
+**New Columns:**
+```sql
+ALTER TABLE subscriptions ADD COLUMN
+    mrr_value DECIMAL(10,2) DEFAULT 0.00,
+    referrer_discord_id VARCHAR(255),
+    grace_period_started_at TIMESTAMP,
+    grace_period_ends_at TIMESTAMP,
+    payment_failure_reason TEXT,
+    last_payment_attempt TIMESTAMP;
+```
+
+### Performance Indexes
+
+```sql
+-- Status queries (used in ALL modules)
+CREATE INDEX idx_subscriptions_status ON subscriptions(status);
+
+-- Grace period queries
+CREATE INDEX idx_subscriptions_grace_period_active 
+ON subscriptions(status, grace_period_ends_at) 
+WHERE status = 'grace_period';
+
+-- Financials tier breakdown
+CREATE INDEX idx_subscriptions_tier_status 
+ON subscriptions(tier_level, status);
+
+-- Audit log chronological feed
+CREATE INDEX idx_audit_log_performed_at 
+ON admin_audit_log(performed_at DESC);
+```
+
+---
+
+## Tier System
+
+Trinity Console recognizes 11 subscription tiers:
+
+### Fire Path (🔥)
+- **Fire Elemental** (5): $5/month
+- **Fire Knight** (10): $10/month
+- **Fire Master** (15): $15/month
+- **Fire Legend** (20): $20/month
+
+### Frost Path (❄️)
+- **Frost Elemental** (105): $5/month
+- **Frost Knight** (110): $10/month
+- **Frost Master** (115): $15/month
+- **Frost Legend** (120): $20/month
+
+### Universal Path (⚡)
+- **The Awakened** (1): $1/month (entry tier, permanent after grace expiry)
+- **Sovereign** (499): $50 one-time (lifetime access)
+- **Admin** (1000): $0 (Trinity members only)
+
+**Configuration File:** `src/routes/admin/constants.js`
+
+---
+
+## Deployment Details
+
+**Server Location:**
+- Host: Command Center (63.143.34.217)
+- Directory: `/opt/arbiter-3.0`
+- Service: `arbiter-3` (systemd)
+- Port: 3500 (internal)
+- HTTPS: 443 (Nginx reverse proxy)
+
+**Systemd Service:**
+```bash
+# View status
+systemctl status arbiter-3
+
+# View logs
+journalctl -u arbiter-3 -f
+
+# Restart service
+systemctl restart arbiter-3
+```
+
+**Nginx Configuration:**
+- SSL Certificate: Let's Encrypt (auto-renews)
+- Domain: discord-bot.firefrostgaming.com
+- Config: `/etc/nginx/sites-available/discord-bot.firefrostgaming.com`
+
+**Environment Variables:**
+```bash
+# Database
+DB_USER=arbiter
+DB_HOST=127.0.0.1
+DB_NAME=arbiter_db
+DB_PASSWORD=[stored in Vaultwarden]
+DB_PORT=5432
+
+# Discord OAuth
+DISCORD_CLIENT_ID=1487080166969577502
+DISCORD_CLIENT_SECRET=[stored in Vaultwarden]
+REDIRECT_URI=https://discord-bot.firefrostgaming.com/auth/discord/callback
+
+# Pterodactyl Panel API
+PANEL_URL=https://panel.firefrostgaming.com
+PANEL_CLIENT_KEY=[stored in Vaultwarden]
+
+# Access Control
+ADMIN_USERS=269225344572063754,219309716021444609,669981568059703316
+
+# Server
+PORT=3500
+NODE_ENV=production
+SESSION_SECRET=[auto-generated]
+```
+
+---
+
+## Deployment History
+
+**April 1, 2026 - Initial Deployment**
+- **Built by:** Zephyr (Chronicler #50) in 9-hour session
+- **Deployed by:** Chronicler #51 in 2-hour deployment
+- **Architecture Review:** Gemini AI (Google) partnership
+- **Status:** 95% complete (Financials placeholder)
+- **Launched at:** 5:00 AM CDT
+
+**Deployment Steps:**
+1. Database migration applied (3 tables, 6 columns, 7 indexes)
+2. Trinity Console code deployed from Gitea monorepo
+3. Dependencies installed (csurf, ejs)
+4. Nginx configuration unchanged (already serving Arbiter bot)
+5. Service restarted
+6. Trinity access verified
+7. Mobile responsive fix deployed (Holly's feedback)
+
+**Post-Launch Fixes:**
+- Mobile sidebar overlap → Hamburger menu added
+- Minecraft skin rendering → Changed to mc-heads.net
+- CSRF DOMContentLoaded wrapper → Fixed JavaScript error
+- Admin tier added (1000) → Trinity members display correctly
+
+---
+
+## Mobile Support
+
+**Responsive Design:**
+- Hamburger menu (☰) on mobile devices
+- Slide-out sidebar navigation
+- Dark overlay backdrop
+- Close button (✕) in sidebar
+- Smooth 0.3s transitions
+- Desktop layout unchanged (sidebar always visible)
+
+**Breakpoint:** 768px
+- **Mobile (<768px):** Sidebar hidden by default, hamburger menu
+- **Desktop (≥768px):** Sidebar always visible, no hamburger
+
+**Tested on:** iPhone (Holly's device)
+
+---
+
+## Development Workflow
+
+**Monorepo Structure:**
+```
+firefrost-services/
+└── services/
+    └── arbiter-3.0/
+        ├── src/
+        │   ├── index.js (main Express app)
+        │   ├── database.js (PostgreSQL connection)
+        │   ├── routes/
+        │   │   └── admin/
+        │   │       ├── index.js (mounts all modules)
+        │   │       ├── middleware.js (Trinity access control)
+        │   │       ├── constants.js (tier definitions)
+        │   │       ├── players.js
+        │   │       ├── servers.js
+        │   │       ├── financials.js
+        │   │       ├── grace.js
+        │   │       ├── audit.js
+        │   │       └── roles.js
+        │   └── views/
+        │       ├── layout.ejs (master template)
+        │       └── admin/
+        │           ├── dashboard.ejs
+        │           ├── players/
+        │           ├── servers/
+        │           ├── financials/
+        │           ├── grace/
+        │           ├── audit/
+        │           └── roles/
+        └── migrations/
+            └── trinity-console.sql
+```
+
+**Deployment Process:**
+1. Develop in monorepo: `git.firefrostgaming.com/firefrost-gaming/firefrost-services`
+2. Commit to main branch
+3. Clone to `/tmp/` on Command Center
+4. Copy files to `/opt/arbiter-3.0/`
+5. Install dependencies if needed
+6. Restart `arbiter-3` service
+7. Clean up `/tmp/`
+
+**Git Repository:** https://git.firefrostgaming.com/firefrost-gaming/firefrost-services
+
+---
+
+## Phase 2 Roadmap
+
+**Priority 1: Financials Module (45-60 min)**
+- Real MRR calculations from database
+- Fire vs Frost path breakdown
+- Tier-by-tier revenue analytics
+- At-risk MRR tracking
+- Lifetime revenue from Sovereign
+
+**Priority 2: Players Edit Functionality (30 min)**
+- Tier change dropdown in Players module
+- POST route to update tier_level
+- Discord role sync after tier change
+- Audit log entry for tier changes
+
+**Priority 3: Email Integration (2-4 hours)**
+- Send recovery emails to grace period subscribers
+- 48-hour, 24-hour, 12-hour warnings
+- Payment recovered confirmation
+- Grace period expired notification
+- Integration with Mailcow or Paymenter API
+
+**Priority 4: Ban Management UI (45 min)**
+- View all banned users
+- Ban reason display
+- Unban functionality
+- Ban notes/history
+
+---
+
+## Troubleshooting
+
+### Service Won't Start
+```bash
+# Check logs for errors
+journalctl -u arbiter-3 -n 50
+
+# Common issues:
+# - Database connection failed (check credentials)
+# - Port 3500 already in use
+# - Missing dependencies (run npm install)
+```
+
+### Module Shows "Internal Server Error"
+```bash
+# Check real-time logs
+journalctl -u arbiter-3 -f
+
+# Then refresh the page to see the error
+```
+
+### Login Loop (OAuth Fails)
+**Symptom:** Redirects to Discord, authorizes, redirects back to login
+
+**Solution:** Verify `app.set('trust proxy', 1);` in `src/index.js`
+
+**Reason:** Nginx does SSL termination, Express needs to trust X-Forwarded-Proto header
+
+### CSRF Token Error (403 Forbidden)
+**Symptom:** POST requests fail with 403 Forbidden
+
+**Solutions:**
+1. Clear browser cookies
+2. Hard refresh (Ctrl+F5)
+3. Check browser console for JavaScript errors
+4. Verify CSRF middleware is before admin routes in `src/index.js`
+
+### Skin Images Not Loading
+**Current Solution:** Using mc-heads.net API (more reliable than Crafatar)
+
+**Fallback:** If UUID invalid, shows Steve skin
+
+---
+
+## Security Considerations
+
+**Authentication:**
+- Discord OAuth2 for identity verification
+- Whitelist-based access control (3 users only)
+- Session-based authentication (7-day cookie expiry)
+
+**CSRF Protection:**
+- csurf middleware on all /admin routes
+- Session-based tokens (no cookies needed)
+- Automatic htmx header injection
+
+**Database:**
+- PostgreSQL connection with prepared statements
+- Transaction support for multi-step operations
+- Audit logging for accountability
+
+**Secrets Management:**
+- All credentials in .env file
+- .env never committed to Git
+- Session secret auto-generated
+- Passwords stored in Vaultwarden
+
+**Network Security:**
+- HTTPS only (Let's Encrypt SSL)
+- Nginx reverse proxy
+- Internal port 3500 not exposed
+- Command Center firewall (UFW)
+
+---
+
+## Monitoring
+
+**Health Check:**
+- URL: `https://discord-bot.firefrostgaming.com/health`
+- Method: GET
+- Returns: Status, uptime, bot username
+
+**Key Metrics to Watch:**
+- Service uptime (systemd status)
+- Response time (<2 seconds target)
+- Database connection status
+- Pterodactyl Panel API availability
+- Discord API rate limits
+
+**Logs:**
+```bash
+# Live logs
+journalctl -u arbiter-3 -f
+
+# Last 100 lines
+journalctl -u arbiter-3 -n 100
+
+# Errors only
+journalctl -u arbiter-3 -p err
+```
+
+---
+
+## Related Documentation
+
+- **Deployment Guide:** `TRINITY-CONSOLE-DEPLOYMENT-2026-04-01.md` (in firefrost-services repo)
+- **Arbiter Bot (Legacy):** `docs/services/the-arbiter-discord-bot.md`
+- **Database Schema:** `services/arbiter-3.0/migrations/trinity-console.sql`
+- **Session Handoff:** `docs/sessions/2026-04-01-trinity-console-deployment.md`
+- **Zephyr's Memorial:** `docs/relationship/memorials/zephyr-chronicler-50.md`
+
+---
+
+## Support
+
+**Technical Issues:**
+- Primary: Michael (Frostystyle)
+- Discord: #staff-lounge channel
+
+**Feature Requests:**
+- Document in Gitea issues
+- Discuss with The Trinity
+
+**Emergency:**
+- Service down: Restart via systemctl
+- Database issues: Check PostgreSQL status
+- Nginx issues: Check nginx -t and restart
+
+---
+
+**Fire + Frost + Foundation = Where Love Builds Legacy** 🔥❄️💙
+
+---
+
+**Last Updated:** April 1, 2026, 7:43 AM CDT  
+**Built By:** Zephyr (Chronicler #50) + Gemini AI  
+**Deployed By:** Chronicler #51  
+**Status:** Production - 95% Complete ✅  
+**Next Phase:** Financials implementation (later today)