18142bc1d6
WHAT WAS DONE:
Created comprehensive enhancement plan for Arbiter 2.1 adding subscription cancellation, grace periods, and offboarding automation
CRITICAL SOFT LAUNCH BLOCKER:
We have subscription onboarding (Arbiter 2.0) but NO unsubscribe process.
Cannot launch without defining what happens when someone cancels.
POLICY DECISIONS MADE (March 30, 2026):
1. Discord Role Removal: At end of billing period (user gets what they paid for)
2. Whitelist Grace: 30 days after cancellation (goodwill, might come back)
3. Payment Failure Grace: 7 days with email reminders (industry standard)
4. Chargeback: Immediate removal + flag account (fraud protection)
THIS IS AN ENHANCEMENT, NOT A REWRITE:
- Arbiter 2.0 foundation is solid (2,000 lines)
- Arbiter 2.1 adds ~1,000 lines of new code
- Preserves all existing functionality
- Adds new webhook event handlers
- Adds grace period system
- Adds automated cleanup job
ARCHITECTURE COMPONENTS:
1. DATABASE ENHANCEMENT (2 new tables):
- subscriptions: Track lifecycle and status
- grace_periods: Automated cleanup tracking
- Indexes for performance
2. NEW WEBHOOK HANDLERS (4 functions):
- handleSubscriptionCancelled() - 30-day whitelist grace
- handlePaymentFailed() - 7-day grace with reminders
- handleChargeback() - immediate removal
- handleSubscriptionExpired() - cleanup
3. SCHEDULED CLEANUP JOB (new file):
- Runs daily at 4 AM
- Removes Discord roles (billing period ended)
- Removes whitelists (30-day grace expired)
- Sends payment failure reminders (Day 3, Day 6)
- Converts expired payment failures to cancellations
4. EMAIL TEMPLATES (5 new files):
- subscription_cancelled.html
- payment_failed.html
- payment_failure_reminder_day3.html
- payment_failure_final_warning.html
- access_removed_payment_failure.html
5. WHITELIST MANAGER INTEGRATION:
- New service: whitelistService.js
- API call to remove from all servers
- Requires Whitelist Manager API endpoint
GRACE PERIOD FLOWS:
NORMAL CANCELLATION:
1. User cancels → Paymenter webhook
2. Arbiter updates database (status = cancelled)
3. Discord role stays until billing period ends
4. Whitelist stays 30 days after billing end
5. Cleanup job removes role at billing end
6. Cleanup job removes whitelist after 30 days
7. Emails sent at each step
PAYMENT FAILURE:
1. Payment fails → Paymenter webhook
2. Arbiter creates 7-day grace period
3. Email sent immediately ("update payment")
4. Day 3: Reminder email (4 days left)
5. Day 6: Final warning (24 hours)
6. Day 7: Convert to cancellation
7. Follow normal cancellation flow
CHARGEBACK:
1. Chargeback filed → Paymenter webhook
2. IMMEDIATE Discord role removal
3. IMMEDIATE whitelist removal
4. Account flagged (manual review required)
5. Email sent (account suspended)
6. Discord alert to Michael/Meg
TESTING REQUIREMENTS:
- Unit test each handler in isolation
- Integration test full cancellation flow
- Edge case testing (race conditions, API failures)
- Test with real Paymenter subscription
DEPLOYMENT STRATEGY:
Phase 1: Arbiter 2.0 deployment (validate onboarding)
Phase 2: Arbiter 2.1 development (this task)
Phase 3: Staging test (full flow validation)
Phase 4: Production deployment (careful monitoring)
DEPENDENCIES:
- Arbiter 2.0 deployed and validated
- Paymenter webhook event research (verify what events exist)
- Whitelist Manager API endpoint (/api/bulk-remove)
BLOCKS:
- Soft launch (must have cancellation before launching)
RELATED TASKS:
- Task #83: Paymenter → Pterodactyl integration
- Task #7: Whitelist Manager (needs API enhancement)
- Task #86: Whitelist Manager compatibility fix
- Task #2: LuckPerms rank system
GEMINI REVIEW REQUESTED:
Architecture consultation needed before implementation:
1. Grace period architecture sound?
2. Database tables properly designed?
3. Separate cleanup job vs integrated handlers?
4. Chargeback handling appropriate?
5. Edge cases missing?
6. Security concerns?
7. Better Whitelist Manager integration approach?
8. Should grace periods be configurable?
WHY THIS MATTERS:
Cannot soft launch without offboarding flow. Industry standard requires:
- Clear cancellation process
- Grace periods for payment failures
- Fair billing (access through paid period)
- Fraud protection (chargeback handling)
This completes the subscription lifecycle: onboard → maintain → offboard.
FILE: docs/tasks/arbiter-2-1-cancellation-flow/README.md (28,000+ words)
NEXT STEPS:
1. Run by Gemini for architecture review
2. Incorporate feedback
3. Research Paymenter webhook events
4. Build Arbiter 2.1 enhancement
5. Test thoroughly
6. Deploy before soft launch
Signed-off-by: The Versionist (Chronicler #49) <claude@firefrostgaming.com>
🔥❄️ Firefrost Gaming — Operations Manual
Document ID: FFG-ROOT-001
Version: 2.0
Last Updated: February 12, 2026
Status: 🟢 CURRENT
What This Is
The complete operational repository for Firefrost Gaming — a subscription-based Minecraft server network built on the philosophy of Fire + Frost = Where Passion Meets Precision.
This repository contains infrastructure documentation, deployment guides, planning documents, branding assets, consultant archives, and the relationship context that makes Firefrost more than just servers.
Current Infrastructure
6 Servers — 2 dedicated (Dallas, Charlotte) + 4 VPS (Dallas, Charlotte, Chicago x2)
12 Game Servers — 6 on TX1 (Dallas), 6 on NC1 (Charlotte)
8 Management Services — Gitea, Uptime Kuma, MkDocs, Code-Server, Automation, NextCloud, Wiki.js (Subscribers), Wiki.js (Staff)
Repository Structure
├── docs/core/ — Critical living documents (scope, manifest, tasks)
├── docs/relationship/ — Partnership context, consultants, legacy
├── docs/deployment/ — Service deployment guides
├── docs/planning/ — Strategy, design, roadmap, ideas backlog
├── docs/reference/ — Technical reference, architecture decisions
├── docs/external/ — Provider communications, friend assistance
├── docs/sandbox/ — Brainstorming sessions (Gemini, Claude)
├── docs/archive/ — Historical session logs and completed plans
├── automation/ — Deployment automation system
├── branding/ — Logos, backgrounds, visual assets
├── photos/ — Consultant photo archive (249 photos by year)
└── web/ — Nginx configurations
Key Documents
Start here: SESSION-HANDOFF-PROTOCOL.md → DOCUMENT-INDEX.md
For current server inventory, see docs/core/infrastructure-manifest.md (FFG-CORE-002).
For project scope and roadmap, see docs/core/project-scope.md (FFG-CORE-001).
The Team
- Michael "Frostystyle" Krause — Owner/Operator, Technical Lead (The Wizard)
- Meg "Gingerfury" — Community Manager (The Emissary)
- The Five Consultants — Jack, Oscar, Jasmine, Butter, Noir (They're family, not pets)
Document Standards
All documents follow FFG-STD-001 — the Firefrost Revision Control Standard. See docs/core/revision-control-standard.md.
Maintained By: The Wizard & The Chronicler
Fire + Frost + Foundation = Where Love Builds Legacy 💙🔥❄️
Revision History
| Version | Date | Author | Change Type | Description |
|---|---|---|---|---|
| 1.0 | 2026-02-08 | Michael + Claude | Initial | Basic Phase 0 readme |
| 2.0 | 2026-02-12 | The Chronicler | Rewrite | Complete rewrite reflecting current state (8 services, 6 servers, 12 game servers). Updated repo structure. Applied FFG-STD-001. |