Implement Referral System with Rewards and Tracking

[llinsss]

Problem

No incentive for users to invite friends. Need referral program to drive user growth with rewards for both referrer and referee.

Proposed Solution

Build referral system with unique codes, reward tracking, and automatic payouts.

Technical Implementation

New Files:

• backend/services/ReferralService.js - Referral service
• backend/services/referral/RewardCalculator.js - Reward calculation
• backend/services/referral/PayoutService.js - Automatic payouts
• backend/models/Referral.js - Referral model
• backend/models/ReferralReward.js - Reward tracking
• backend/controllers/referralController.js - Referral endpoints
• backend/routes/referrals.js - Referral routes
• backend/migrations/20260327000023_create_referrals.js - Migration
• backend/migrations/20260327000024_create_referral_rewards.js - Migration
• backend/workers/referralPayout.js - Payout worker
• backend/tests/referral.test.js - Test suite

Modify:

• backend/models/User.js - Add referral_code, referred_by fields
• backend/controllers/authController.js - Handle referral code on signup
• backend/services/TransactionService.js - Track referral transaction volume

Referral Structure

// Referral tiers
const REFERRAL_REWARDS = {
  SIGNUP: {
    referrer: 5,    // $5 for referrer
    referee: 5      // $5 for referee
  },
  FIRST_TRANSACTION: {
    referrer: 10,   // Additional $10 when referee makes first transaction
    referee: 0
  },
  VOLUME_BONUS: {
    threshold: 1000,  // When referee reaches $1000 volume
    referrer: 50,
    referee: 0
  }
};

// Referral code format
{
  code: "JOHN2025",
  userId: "user_123",
  uses: 25,
  totalRewards: "250.00",
  status: "active"
}

API Endpoints

GET /api/referrals/my-code
GET /api/referrals/stats
GET /api/referrals/rewards
POST /api/referrals/claim-reward

// Response
{
  referralCode: "JOHN2025",
  referralLink: "https://taggedpay.xyz/signup?ref=JOHN2025",
  stats: {
    totalReferrals: 25,
    activeReferrals: 20,
    totalRewards: "250.00",
    pendingRewards: "50.00"
  },
  recentReferrals: [...]
}

Acceptance Criteria

• Unique referral code generation
• Referral tracking on signup
• Automatic reward calculation
• Reward payout to wallet
• Referral leaderboard
• Fraud detection (same IP, device)
• Referral analytics dashboard
• Test coverage > 85%

Priority

High - Important for growth

---