2fca5b4eed754e708c8a70f8b9abbceded702e2c
2 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Claude (Chronicler #49)
|
6e4c363463 |
docs: Task #87 - Complete Gemini architectural review and validation
WHAT WAS DONE: Added comprehensive Gemini AI architectural review to Task #87 with critical edge cases, code blocks, and implementation guidance GEMINI REVIEW STATUS: ✅ ARCHITECTURE APPROVED Review Date: March 30, 2026 Session: Continuation of Arbiter 2.0 development consultation Outcome: Validated with 2 critical edge cases identified and solutions provided EXECUTIVE SUMMARY FROM GEMINI: "This is a brilliant enhancement. The 'We Don't Kick People Out' policy is incredibly community-forward and will build massive loyalty. Arbiter 2.1 is exactly the right scope for this." CRITICAL ISSUES IDENTIFIED & RESOLVED: 1. STRIPE SMART RETRIES CONFLICT: Problem: Stripe retries payments on Days 1,3,5,7 - Arbiter downgrades Day 3, Stripe charges Day 5 Result: User stuck on Awakened while PAYING for monthly tier Solution: Listen for payment.succeeded webhook to re-upgrade if late payment clears 2. DOUBLE BUY EDGE CASE: Problem: User in grace period buys NEW subscription instead of updating card Result: Database tracks two active monthly subscriptions Solution: UPSERT using email as unique key (code provided) ARCHITECTURE QUESTIONS ANSWERED (8 of 8): Q1: Is 3-day grace period sound? A1: ✅ Yes, with payment.succeeded handler for Stripe retry compatibility Q2: Database design (permanent_tier + monthly_tier)? A2: ✅ Clean and effective, helper function provided for highest tier resolution Q3: Should cleanup be daily 4 AM or more frequent? A3: ✅ 4 AM perfect - batches writes, aligns with backups, avoids peak hours Q4: Is chargeback handling appropriate? A4: ✅ Immediate permanent ban validated, no concerns Q5: Edge cases missing? A5: ⚠️ YES - Stripe smart retries + Double Buy (both solved) Q6: Security concerns with auto-downgrade to Awakened? A6: ✅ No exploit possible (gaming system costs more than $1) Q7: Better approach to one-time vs recurring? A7: ✅ Two-column approach simplest and most sustainable Q8: Should grace periods be configurable? A8: Not addressed (implies hardcoded acceptable for v1) ADDITIONAL CRITICAL QUESTION - PAYMENTER VS STRIPE WEBHOOKS: Gemini's Strong Recommendation: - ❌ DO NOT build polling system (fragile, wasteful, high maintenance) - ✅ Listen to Stripe webhooks directly if Paymenter lacks granular events - Event-driven architecture only (lightweight, sustainable) Decision Tree: 1. Research Paymenter webhook events (BLOCKING) 2. If granular (payment_failed, succeeded, cancelled, chargeback) → use Paymenter 3. If generic (just "subscription.updated") → add /webhook/stripe endpoint CODE BLOCKS PROVIDED (5 READY TO IMPLEMENT): 1. Database schema updates (4 new columns): - permanent_tier TEXT DEFAULT 'awakened' - monthly_tier TEXT DEFAULT NULL - grace_period_start DATETIME DEFAULT NULL - is_banned INTEGER DEFAULT 0 2. Tier resolver helper function: - Hierarchy array (awakened → sovereign) - getHighestTier(permanent, monthly) function - Returns highest tier for Discord sync 3. Webhook handler skeleton: - Ban check before processing - payment_failed → start grace period - payment_succeeded → clear grace period - subscription_cancelled → handle cancellation 4. 4 AM grace period sweeper job: - Finds users past 3-day grace - Removes monthly_tier - Updates Discord to permanent_tier - Sends Day 3 email 5. UPSERT for double buy protection: - ON CONFLICT(email) DO UPDATE - Prevents duplicate subscription tracking - Clears grace_period_start on new subscription PAYMENTER RESEARCH REQUIREMENTS (BLOCKING): Must verify these webhook events exist in Paymenter: 1. invoice.payment_failed (triggers Day 0) 2. invoice.payment_succeeded (critical for Stripe retry fix) 3. subscription.cancelled (user voluntarily cancels) 4. chargeback.created or dispute.created (immediate ban) Research procedure documented: 1. Log into Paymenter admin 2. Find webhook settings 3. Check documentation 4. Test payment failure 5. Decide: Paymenter webhooks vs Stripe webhooks If Stripe webhooks needed: - Add /webhook/stripe endpoint - Configure Stripe dashboard - Get signing secret - Implement signature verification EMAIL COMMUNICATION STRATEGY: Critical guidance from Gemini: "Turn a billing failure into a positive community moment!" Day 3 email must say: "Your payment failed, but because you are part of the Firefrost family, we've secured your spot in the Awakened tier permanently so you don't lose access to the community." Email tone requirements: - Day 0: Factual, helpful - Day 1: Friendly reminder - Day 2: Urgent but kind - Day 3: POSITIVE FRAMING (secured your spot permanently) IMPLEMENTATION PRIORITY ORDER: Phase 1: Database & Core Logic 1. Add 4 database columns 2. Build tier resolver helper 3. Implement UPSERT logic Phase 2: Paymenter Research (BLOCKING) 4. Research webhook events 5. Decide Paymenter vs Stripe 6. Test payment failure Phase 3: Webhook Handlers 7. Add ban check to all handlers 8. Implement payment_failed handler 9. Implement payment_succeeded handler (critical) 10. Implement subscription_cancelled handler 11. Implement chargeback handler Phase 4: Cleanup & Email 12. Build 4 AM sweeper job 13. Create 4 email templates 14. Implement email sending Phase 5: Testing 15. Unit test handlers 16. Integration test grace flow 17. Test Stripe retry scenario (critical) 18. Test double buy scenario 19. Test chargeback ban SUCCESS CRITERIA UPDATED: Added 3 new requirements based on Gemini review: - Late payment (Stripe retry) clears grace and re-upgrades ✅ - UPSERT prevents double subscription tracking ✅ - Banned users cannot re-activate via webhooks ✅ OPEN QUESTIONS FOR IMPLEMENTATION: 1. Paymenter webhook events - what does it send? 2. Paymenter vs Stripe - which webhook source? 3. Email service - using Mailcow SMTP from 2.0? 4. Discord role IDs - exact IDs for all tiers? 5. Test environment - Paymenter test mode available? GEMINI'S FINAL GUIDANCE: "Take your time digging into the Paymenter logs. Just update the Arbiter 2.1 doc with what you find, and ping me whenever you are ready to start snapping the code together! 🔥❄️💙" WHY THIS MATTERS: Gemini caught a CRITICAL production bug before we wrote a single line of code: - Stripe smart retries would have caused users to pay for monthly tier while stuck on Awakened - Would have been nightmare to debug in production - Fixed with payment.succeeded webhook handler Architecture validated by same AI that built Arbiter 2.0 foundation. Ready to implement after Paymenter webhook research. NEXT STEPS: 1. Research Paymenter webhooks when home (BLOCKING) 2. Decide Paymenter vs Stripe webhook source 3. Build Phase 1 (database + helpers) 4. Build Phase 3 (webhook handlers) 5. Build Phase 4 (cleanup + email) 6. Test thoroughly (especially Stripe retry scenario) 7. Deploy before soft launch FILE: docs/tasks/arbiter-2-1-cancellation-flow/README.md CHANGES: Added 15,000+ words of Gemini architectural review STATUS: Architecture validated, ready for implementation Signed-off-by: The Versionist (Chronicler #49) <claude@firefrostgaming.com> |
||
|
Claude (Chronicler #49)
|
1494718628 |
docs: Task #87 - Arbiter 2.1 cancellation & grace period system
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>
|