dubs-server 1.0.0

package/documentation/CLI_TOOL_GUIDE.md

@@ -0,0 +1,372 @@
+# 🎮 Dubs CLI - Interactive Testing Tool
+
+**Beautiful interactive menu for testing the Dubs voting system!**
+
+---
+
+## 🚀 **Quick Start**
+
+```bash
+cd dubs-server
+npm run cli
+```
+
+**That's it!** 🎉
+
+---
+
+## 📋 **Features**
+
+```
+✅ Interactive menu (no typing curl commands!)
+✅ Auto-save game IDs
+✅ Track player addresses
+✅ Colorful terminal output
+✅ Complete voting workflows
+✅ Automated test scenarios
+✅ Pretty JSON responses
+✅ Error handling
+```
+
+---
+
+## 🎮 **Main Menu**
+
+```
+╔═══════════════════════════════════════════════════════╗
+║           🎮  DUBS CLI - VOTING TESTER  🎮            ║
+╚═══════════════════════════════════════════════════════╝
+
+📡 Server: http://localhost:3001
+🎮 Current Game: a1b2c3d4-e5f6-7890...
+
+═══ GAME MANAGEMENT ═══
+1. 📋 List Demo Wallets
+2. 💸 Airdrop SOL to Player
+3. 🎮 Create New Game
+4. 📊 Get Game Info
+
+═══ GAME PLAY ═══
+5. 👥 Player Joins Game
+6. 🗳️  Cast Vote (NEW!)
+7. 🏆 Distribute by Vote (NEW!)
+8. 💰 Distribute Manually
+
+═══ QUICK TESTS ═══
+9. 🚀 Full Voting Test (Auto)
+10. 🎲 3-Way Tie Test
+
+0. ❌ Exit
+```
+
+---
+
+## 🎯 **How to Use**
+
+### **Option 1: Manual Step-by-Step**
+
+```
+1. Run: npm run cli
+2. Select: 1 (List Wallets)
+   → See all demo wallets
+3. Select: 3 (Create Game)
+   → Enter buy-in, players, etc.
+4. Select: 5 (Join Game) multiple times
+   → Alice, Bob, Charlie join
+5. Select: 4 (Get Game Info)
+   → See player addresses
+6. Select: 6 (Cast Vote) multiple times
+   → Each player votes
+7. Select: 7 (Distribute by Vote)
+   → Winner determined democratically!
+```
+
+### **Option 2: Automated Tests**
+
+```
+1. Run: npm run cli
+2. Select: 9 (Full Voting Test)
+   → Runs complete flow automatically!
+   → Creates game
+   → Players join
+   → Players vote
+   → Distributes by vote
+   → Shows results!
+```
+
+### **Option 3: Tie Testing**
+
+```
+1. Run: npm run cli
+2. Select: 10 (3-Way Tie Test)
+   → Tests equal split scenario
+   → Each player votes for themselves
+   → All 3 tied at 1 vote
+   → Prize split 3 ways!
+```
+
+---
+
+## 📊 **What Each Option Does:**
+
+### **1. List Demo Wallets**
+```
+Shows:
+- Creator: address (balance)
+- Alice: address (balance)
+- Bob: address (balance)
+- etc.
+
+Auto-saves addresses for voting!
+```
+
+### **2. Airdrop SOL**
+```
+Enter player name → Airdrops 2 SOL
+Useful for funding test wallets
+```
+
+### **3. Create Game**
+```
+Prompts for:
+- Creator name
+- Buy-in amount
+- Max players
+- Operator fee
+- Operator player
+
+Auto-saves game ID!
+```
+
+### **4. Get Game Info**
+```
+Shows:
+- Players list
+- Pot amount
+- Votes cast
+- Voting status
+- Majority progress
+
+Auto-saves player addresses!
+```
+
+### **5. Player Joins**
+```
+Enter:
+- Player name (alice/bob/etc.)
+- Game ID (uses current game)
+
+Player joins game automatically!
+```
+
+### **6. Cast Vote** 🗳️
+```
+Enter:
+- Voter name
+- Game ID
+- Address to vote for (shows saved addresses!)
+
+Vote cast on blockchain!
+```
+
+### **7. Distribute by Vote** 🗳️
+```
+Enter:
+- Game ID
+
+Distributes based on votes!
+Shows:
+- Winners
+- Vote counts
+- Transaction signature
+```
+
+### **8. Distribute Manually**
+```
+Enter:
+- Game ID
+- Winner addresses (comma-separated)
+
+Creator chooses winners manually
+```
+
+### **9. Full Voting Test** ⚡
+```
+Automated test:
+✅ Creates game
+✅ Alice & Bob join
+✅ Creator votes for Alice
+✅ Alice votes for herself (majority!)
+✅ Distributes by vote
+✅ Shows results
+
+Perfect for quick testing!
+```
+
+### **10. 3-Way Tie Test** ⚡
+```
+Automated test:
+✅ Creates game
+✅ 3 players join
+✅ Each votes for themselves
+✅ All tied at 1 vote
+✅ Prize split equally!
+
+Tests tie handling!
+```
+
+---
+
+## 🎨 **Color Coding**
+
+```
+✅ Green = Success
+❌ Red = Error
+ℹ️  Blue = Info
+🎮 Yellow = Game ID
+📊 Cyan = JSON output
+```
+
+---
+
+## ⚙️ **Configuration**
+
+### **Change Server URL:**
+```bash
+# Test against devnet (when Heroku is back)
+DUBS_URL=https://dubs-server-dev-55d1fba09a97.herokuapp.com npm run cli
+
+# Test locally (default)
+npm run cli
+```
+
+---
+
+## 🧪 **Testing Workflows**
+
+### **Quick Smoke Test:**
+```
+1. npm run cli
+2. Select: 9 (Full Voting Test)
+3. Watch it run!
+4. Done! ✅
+```
+
+### **Manual Testing:**
+```
+1. List wallets (option 1)
+2. Create game (option 3)
+3. Join with multiple players (option 5)
+4. Get game info to see addresses (option 4)
+5. Cast votes (option 6)
+6. Distribute by vote (option 7)
+```
+
+### **Tie Testing:**
+```
+1. Select: 10 (3-Way Tie Test)
+2. Watch equal split in action!
+```
+
+---
+
+## 🎯 **Pro Tips**
+
+### **Game ID Auto-Save:**
+```
+Create a game → Game ID saved automatically
+Future prompts → Press Enter to use current game
+```
+
+### **Address Auto-Save:**
+```
+Get game info → Player addresses saved
+Cast vote → Shows saved addresses to choose from
+```
+
+### **Pretty Output:**
+```
+All JSON responses formatted beautifully
+Color-coded for easy reading
+```
+
+---
+
+## 🚀 **Usage Examples**
+
+### **Example 1: Test Voting**
+```bash
+$ npm run cli
+
+Select: 9
+→ Full automated voting test runs
+→ Alice wins by majority vote!
+→ Results displayed beautifully
+```
+
+### **Example 2: Custom Game**
+```bash
+$ npm run cli
+
+Select: 3 (Create Game)
+  Buy-in: 1.0
+  Max players: 4
+  
+Select: 5 (Join) - Alice
+Select: 5 (Join) - Bob  
+Select: 5 (Join) - Charlie
+
+Select: 4 (Game Info)
+  → Copy addresses
+
+Select: 6 (Vote) - Creator votes for Alice
+Select: 6 (Vote) - Alice votes for Alice
+Select: 6 (Vote) - Bob votes for Charlie
+
+Select: 7 (Distribute by Vote)
+  → Alice wins!
+```
+
+---
+
+## 📦 **Requirements**
+
+```
+Node.js 20.x (already have it!)
+npm packages: (already installed!)
+  - node-fetch (built-in in Node 18+)
+  - readline (built-in)
+```
+
+**No additional dependencies!**
+
+---
+
+## 🎊 **Why This is Awesome**
+
+```
+✅ No Postman (AWS down anyway!)
+✅ No manual curl commands
+✅ Beautiful interactive menu
+✅ Auto-saves everything
+✅ Color-coded output
+✅ Automated test scenarios
+✅ Error handling
+✅ Production-quality tool
+```
+
+---
+
+## 🎮 **Ready to Test!**
+
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+npm run cli
+```
+
+**Select option 9 for instant voting test! 🗳️🚀**
+
+---
+
+**Enjoy your new CLI tool! 🎉**
+

package/documentation/COHORT_RETENTION_ANALYSIS.md

@@ -0,0 +1,295 @@
+# Cohort Retention Analysis - Implementation Plan
+
+## Executive Summary
+
+✅ **Cohort retention analysis is FEASIBLE** with current production data!
+
+**Production Database Status:**
+- **Total Users**: 19 registered users
+- **Data Range**: Dec 14, 2025 - Jan 1, 2026 (17 days)
+- **Registration Events**: 31 events tracked
+- **Cohort Grouping**: Weekly cohorts working perfectly
+
+## Current Data Structure
+
+### Registration Events (audit_logs table)
+```sql
+SELECT 
+  log_type,
+  user_id,
+  created_at,
+  metadata
+FROM audit_logs
+WHERE log_type IN ('registration_started', 'registration_completed', 'registration_submitted')
+```
+
+**Key Fields:**
+- `user_id`: Wallet address (unique identifier)
+- `created_at`: Timestamp of registration
+- `metadata`: JSON with additional context (referralCode, username, etc.)
+
+### Sample Cohort Retention Data (Production)
+
+| Cohort Week | Users | D1 Users | D1% | D7 Users | D7% | D14 Users | D14% | D30 Users | D30% |
+|-------------|-------|----------|-----|----------|-----|-----------|------|-----------|------|
+| Dec 29, 2025 | 4 | 4 | 100.0% | 0 | 0.0% | 0 | 0.0% | 0 | 0.0% |
+| Dec 22, 2025 | 9 | 5 | 55.6% | 0 | 0.0% | 0 | 0.0% | 0 | 0.0% |
+| Dec 15, 2025 | 5 | 2 | 40.0% | 4 | 80.0% | 4 | 80.0% | 0 | 0.0% |
+| Dec 8, 2025 | 1 | 1 | 100.0% | 1 | 100.0% | 1 | 100.0% | 0 | 0.0% |
+
+## Metrics We Can Deliver
+
+Based on your community manager's requirements:
+
+### 1. **signup_cohort** ✅
+- Weekly cohorts: `DATE_TRUNC('week', signup_date)`
+- Monthly cohorts: `DATE_TRUNC('month', signup_date)`
+- Format: "Week of Jan 1, 2026" or "January 2026"
+
+### 2. **signup_date_range** ✅
+- Weekly: "Jan 1-7, 2026"
+- Monthly: "January 2026"
+
+### 3. **total_signups** ✅
+- Count of unique users who completed registration in cohort period
+
+### 4. **d1_users, d1_pct** ✅
+- Users who returned on Day 1 (24-48 hours after signup)
+- Percentage: `(d1_users / total_signups) * 100`
+
+### 5. **d7_users, d7_pct** ✅
+- Users who returned on Day 7 (7-8 days after signup)
+- Percentage: `(d7_users / total_signups) * 100`
+
+### 6. **d14_users, d14_pct** ✅
+- Users who returned on Day 14 (14-15 days after signup)
+- Percentage: `(d14_users / total_signups) * 100`
+
+### 7. **d30_users, d30_pct** ✅
+- Users who returned on Day 30 (30-31 days after signup)
+- Percentage: `(d30_users / total_signups) * 100`
+
+### 8. **source** ⚠️ (Limited)
+- Currently tracking: `metadata->>'hasReferralCode'`
+- Can add: Referral code, UTM parameters, invite source
+- **Recommendation**: Enhance registration tracking to capture source
+
+## SQL Query for Cohort Retention
+
+```sql
+WITH signups AS (
+  -- Get first registration event per user
+  SELECT 
+    user_id,
+    MIN(DATE(created_at)) as signup_date,
+    MIN(metadata->>'referralCode') as referral_code
+  FROM audit_logs
+  WHERE log_type = 'registration_completed'
+    AND user_id IS NOT NULL
+  GROUP BY user_id
+),
+weekly_cohorts AS (
+  -- Group signups into weekly cohorts
+  SELECT 
+    DATE_TRUNC('week', signup_date) as cohort_week,
+    user_id,
+    signup_date,
+    CASE 
+      WHEN referral_code IS NOT NULL THEN 'referral'
+      ELSE 'organic'
+    END as source
+  FROM signups
+),
+user_activity AS (
+  -- Get all user activity after signup
+  SELECT 
+    wc.cohort_week,
+    wc.user_id,
+    wc.signup_date,
+    wc.source,
+    DATE(al.created_at) as activity_date,
+    al.created_at - wc.signup_date as time_since_signup
+  FROM weekly_cohorts wc
+  LEFT JOIN audit_logs al ON al.user_id = wc.user_id
+    AND DATE(al.created_at) >= wc.signup_date
+),
+retention_calc AS (
+  -- Calculate retention metrics
+  SELECT 
+    cohort_week,
+    source,
+    COUNT(DISTINCT user_id) as total_users,
+    -- Day 1 retention (24-48 hours)
+    COUNT(DISTINCT CASE 
+      WHEN time_since_signup >= INTERVAL '1 day' 
+      AND time_since_signup < INTERVAL '2 days' 
+      THEN user_id 
+    END) as d1_users,
+    -- Day 7 retention (7-8 days)
+    COUNT(DISTINCT CASE 
+      WHEN time_since_signup >= INTERVAL '7 days' 
+      AND time_since_signup < INTERVAL '8 days' 
+      THEN user_id 
+    END) as d7_users,
+    -- Day 14 retention (14-15 days)
+    COUNT(DISTINCT CASE 
+      WHEN time_since_signup >= INTERVAL '14 days' 
+      AND time_since_signup < INTERVAL '15 days' 
+      THEN user_id 
+    END) as d14_users,
+    -- Day 30 retention (30-31 days)
+    COUNT(DISTINCT CASE 
+      WHEN time_since_signup >= INTERVAL '30 days' 
+      AND time_since_signup < INTERVAL '31 days' 
+      THEN user_id 
+    END) as d30_users
+  FROM user_activity
+  GROUP BY cohort_week, source
+)
+SELECT 
+  cohort_week as signup_cohort,
+  TO_CHAR(cohort_week, 'Mon DD') || ' - ' || TO_CHAR(cohort_week + INTERVAL '6 days', 'Mon DD, YYYY') as signup_date_range,
+  total_users as total_signups,
+  d1_users,
+  ROUND(100.0 * d1_users / NULLIF(total_users, 0), 1) as d1_pct,
+  d7_users,
+  ROUND(100.0 * d7_users / NULLIF(total_users, 0), 1) as d7_pct,
+  d14_users,
+  ROUND(100.0 * d14_users / NULLIF(total_users, 0), 1) as d14_pct,
+  d30_users,
+  ROUND(100.0 * d30_users / NULLIF(total_users, 0), 1) as d30_pct,
+  source
+FROM retention_calc
+WHERE total_users > 0
+ORDER BY cohort_week DESC, source;
+```
+
+## Implementation Plan
+
+### Phase 1: Backend API Endpoint ✅ READY
+**File**: `routes/analyticsRoutes.js`
+
+**Endpoint**: `GET /api/analytics/cohort-retention`
+
+**Query Parameters**:
+- `period`: 'weekly' | 'monthly' (default: 'weekly')
+- `source`: 'all' | 'organic' | 'referral' (default: 'all')
+- `limit`: number (default: 12 cohorts)
+
+**Response**:
+```json
+{
+  "success": true,
+  "period": "weekly",
+  "cohorts": [
+    {
+      "signup_cohort": "2025-12-29T00:00:00.000Z",
+      "signup_date_range": "Dec 29 - Jan 04, 2026",
+      "total_signups": 4,
+      "d1_users": 4,
+      "d1_pct": 100.0,
+      "d7_users": 0,
+      "d7_pct": 0.0,
+      "d14_users": 0,
+      "d14_pct": 0.0,
+      "d30_users": 0,
+      "d30_pct": 0.0,
+      "source": "all"
+    }
+  ]
+}
+```
+
+### Phase 2: Frontend Dashboard Component
+**File**: `dubs-jackpot-spa/app/v2/components/overlay/AnalyticsDashboard.tsx`
+
+**Features**:
+1. Cohort retention table (like examples provided)
+2. Period selector (weekly/monthly)
+3. Source filter (all/organic/referral)
+4. CSV export button
+5. Visual retention heatmap (color-coded percentages)
+
+### Phase 3: CSV Export
+**Format**: Matches community manager's requirements exactly
+
+```csv
+signup_cohort,signup_date_range,total_signups,d1_users,d1_pct,d7_users,d7_pct,d14_users,d14_pct,d30_users,d30_pct,source
+"Week of Dec 29, 2025","Dec 29 - Jan 04, 2026",4,4,100.0,0,0.0,0,0.0,0,0.0,all
+"Week of Dec 22, 2025","Dec 22 - Dec 28, 2025",9,5,55.6,0,0.0,0,0.0,0,0.0,all
+```
+
+## Analysis Scripts
+
+### Development Database
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+node scripts/analyze-cohort-data.js
+```
+
+### Production Database (Heroku)
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+bash scripts/analyze-prod-cohorts.sh
+```
+
+## Recommendations
+
+### 1. **Enhance Source Tracking** 🎯
+Add to registration events:
+```javascript
+analytics.track('registration_completed', 'USER', {
+  username,
+  hasReferralCode: !!referralCode,
+  referralCode: referralCode || null,
+  // NEW: Add these
+  source: 'telegram' | 'twitter' | 'direct' | 'referral',
+  utm_source: params.get('utm_source'),
+  utm_medium: params.get('utm_medium'),
+  utm_campaign: params.get('utm_campaign'),
+});
+```
+
+### 2. **Define "Active" User** 📊
+Currently using ANY event as activity. Consider defining specific engagement events:
+- Game created
+- Game joined
+- Bet placed
+- Chat message sent
+- Friend added
+
+### 3. **Add Cohort Comparison** 📈
+Compare cohorts side-by-side:
+- Week 1 vs Week 2 retention curves
+- Organic vs Referral retention
+- Monthly trend analysis
+
+### 4. **Automated Reports** 📧
+Schedule weekly cohort reports for community manager:
+- Email with CSV attachment
+- Slack notification with key metrics
+- Dashboard link
+
+## Next Steps
+
+1. ✅ **Data Analysis Complete** - Verified production data
+2. 🔄 **Create API Endpoint** - `/api/analytics/cohort-retention`
+3. 🔄 **Build Dashboard UI** - Cohort table in AnalyticsDashboard
+4. 🔄 **Add CSV Export** - Download button for community manager
+5. ⏳ **Test with Real Data** - Validate with production database
+6. ⏳ **Deploy to Production** - Push to Heroku
+
+## Questions for Community Manager
+
+1. **Cohort Period**: Weekly or monthly preferred?
+2. **Retention Definition**: Any activity, or specific actions (games played, bets placed)?
+3. **Source Tracking**: What sources should we track? (Telegram, Twitter, Referrals, etc.)
+4. **Export Format**: CSV sufficient, or need Google Sheets integration?
+5. **Automated Reports**: Want scheduled reports? (Daily, weekly, monthly?)
+
+---
+
+**Status**: ✅ Ready to implement
+**Estimated Time**: 4-6 hours for full implementation
+**Dependencies**: None - all data available in production database
+