Complete technical specification and implementation guide
┌───────────────────────────────────────────────────────────────────────────┐
│ MEMBER REFERRAL SYSTEM FLOW │
└───────────────────────────────────────────────────────────────────────────┘
╔═══════════════════════════════════════════════════════════════════════════╗
║ PHASE 1: MEMBER IMPORT (Studio Owner/Staff) ║
╚═══════════════════════════════════════════════════════════════════════════╝
┌─────────────────┐
│ IMPORT METHOD │
│ SELECTION │
└────────┬────────┘
│
┌────────┴────────────────────────────┐
│ │
▼ ▼
┌────────────┐ ┌──────────────┐
│ CSV UPLOAD │ │ MANUAL ENTRY │
└────────────┘ └──────────────┘
│ │
├─► Upload file ├─► Enter: name, email, phone
├─► Parse with AI extraction ├─► Real-time validation
├─► Validate all rows: ├─► Check duplicate email
│ • Required: name, email ├─► Create User record
│ • Email format check └─► Create Member record
│ • Duplicate detection │
├─► Generate results: │
│ • Success list │
│ • Error list with row numbers │
├─► Bulk create User records │
└─► Bulk create Member records │
│ │
└─────────────────┬───────────────────┘
▼
┌─────────────────────┐
│ REFERRAL CODE GEN │
│ 8-char alphanumeric │
│ Uppercase, unique │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ SEND INVITE EMAIL │
│ "Join our program" │
└─────────────────────┘
┌──────────────────┐
│ INVITE LINK │ Alternative method
│ GENERATION │
└──────────────────┘
│
├─► Generate: yoursite.com/join/{studio_id}
├─► Studio owner shares link
└─► Members self-enroll
╔═══════════════════════════════════════════════════════════════════════════╗
║ PHASE 2: MEMBER OPT-IN & CONSENT ║
╚═══════════════════════════════════════════════════════════════════════════╝
Member clicks invite link/email
│
▼
┌─────────────────────┐
│ CONSENT SCREEN │
│ Shows: │
│ • How it works │
│ • What we track │
│ • Rewards info │
└─────────────────────┘
│
├─► Accept ───────┐
├─► Decline ──────┤
│ │
▼ ▼
┌──────────────────┐ ┌─────────────┐
│ REQUIRED CONSENT │ │ SKIP │
│ ✓ Terms │ │ (Can join │
│ ✓ Data tracking │ │ later) │
└──────────────────┘ └─────────────┘
│
├─► Update user.preferences
├─► Set member.status = 'active'
├─► Generate unique referral_code
├─► Create referral link
└─► Redirect to Member Dashboard
╔═══════════════════════════════════════════════════════════════════════════╗
║ PHASE 3: REFERRAL LINK GENERATION & STRUCTURE ║
╚═══════════════════════════════════════════════════════════════════════════╝
LINK STRUCTURE:
┌──────────────────────────────────────────────────────────┐
│ https://yoursite.com/refer/{REFERRAL_CODE} │
│ │
│ Example: https://app.com/refer/A7K9M2XQ │
└──────────────────────────────────────────────────────────┘
CODE GENERATION RULES:
• Format: 8 characters, uppercase alphanumeric
• Character set: A-Z, 0-9 (excludes confusing chars: O, 0, I, 1)
• Uniqueness: Checked against existing codes before creation
• Reset: Owner can regenerate if member loses link (old code invalidated)
COOKIE & TRACKING:
┌──────────────────────────────────────────────────────────┐
│ When link is clicked: │
│ 1. Set cookie: referral_code={CODE}, expires 30 days │
│ 2. Track click event (optional analytics) │
│ 3. Redirect to signup page │
│ 4. On signup, check cookie for attribution │
└──────────────────────────────────────────────────────────┘
╔═══════════════════════════════════════════════════════════════════════════╗
║ PHASE 4: MEMBER DASHBOARD & SHARING ║
╚═══════════════════════════════════════════════════════════════════════════╝
Member Dashboard displays:
┌───────────────────────────────────────┐
│ 1. Referral Link (one-tap copy) │
│ 2. Referral Code (displayed large) │
│ 3. Pre-written captions │
│ 4. One-tap share buttons: │
│ • Instagram (copy caption) │
│ • Facebook (native share) │
│ • WhatsApp (pre-filled message) │
│ • Email (mailto link) │
│ • SMS (sms: protocol) │
│ 5. Performance stats: │
│ • Total referrals │
│ • Conversion rate │
│ • Rewards earned │
│ 6. Referral history with statuses │
│ 7. "How it works" guide │
└───────────────────────────────────────┘
╔═══════════════════════════════════════════════════════════════════════════╗
║ PHASE 5: FRAUD PREVENTION ║
╚═══════════════════════════════════════════════════════════════════════════╝
┌─────────────────────────┐
│ PREVENTION RULES │
└─────────────────────────┘
│
┌─────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌──────┐ ┌─────────┐ ┌──────────┐
│RULE 1│ │ RULE 2 │ │ RULE 3 │
│Self- │ │Duplicate│ ... │ Pattern │
│refer │ │ email │ │ detection│
└──────┘ └─────────┘ └──────────┘
│ │ │
└─────────┼─────────────────────┘
▼
┌──────────────────────┐
│ FLAG MEMBER │
│ • Add to review list│
│ • Notify owner │
│ • Log to audit │
└──────────────────────┘
│
┌─────────┴──────────┐
│ │
▼ ▼
┌─────────┐ ┌──────────────┐
│ APPROVE │ │ SUSPEND │
│ (Clear) │ │ (Block refs) │
└─────────┘ └──────────────┘
{
"member": {
"id": "uuid (auto-generated)",
"user_id": "uuid (references User entity)",
"studio_id": "uuid (references Studio)",
"referral_code": "string (8 chars, uppercase alphanumeric, unique)",
"status": "enum: active | inactive | suspended | churned",
"membership_type": "enum: monthly | annual | class_pack | drop_in | trial",
"member_since": "date (ISO 8601)",
"tier": "enum: bronze | silver | gold | platinum",
"total_referrals": "number (default: 0, auto-incremented)",
"successful_referrals": "number (default: 0, counts conversions)",
"total_rewards_earned": "number (default: 0, in dollars)",
"total_rewards_redeemed": "number (default: 0, in dollars)",
"notes": "string (staff notes, visible to owner/staff only)",
"created_date": "datetime (auto)",
"updated_date": "datetime (auto)",
"created_by": "email (auto)"
},
"referral_code_format": {
"length": 8,
"character_set": "ABCDEFGHJKLMNPQRSTUVWXYZ23456789",
"excluded_chars": "O, 0, I, 1 (prevent confusion)",
"uniqueness": "checked against all existing codes",
"example": "A7K9M2XQ"
},
"referral_link_format": {
"pattern": "{base_url}/refer/{referral_code}",
"examples": [
"https://app.referralhub.com/refer/A7K9M2XQ",
"https://yourstudio.com/refer/B3H8K5LP"
],
"tracking": {
"cookie_name": "referral_code",
"cookie_duration_days": 30,
"attribution_model": "first_touch"
}
},
"fraud_detection_flags": {
"self_referral": {
"trigger": "lead.email === member.user.email",
"action": "auto_block",
"severity": "critical"
},
"duplicate_email": {
"trigger": "lead.email exists in system",
"action": "auto_block",
"severity": "high"
},
"low_conversion": {
"trigger": "referrals >= 10 AND conversion_rate < 5%",
"action": "flag_for_review",
"severity": "medium"
},
"rapid_referrals": {
"trigger": "5+ referrals within 24 hours",
"action": "flag_for_review",
"severity": "medium"
},
"similar_emails": {
"trigger": "2+ emails with same prefix (before @)",
"action": "flag_for_review",
"severity": "medium"
}
},
"sharing_integrations": {
"instagram": {
"method": "copy_caption",
"reason": "Instagram API limits, copy-paste is standard UX",
"caption_includes": "link + message"
},
"facebook": {
"method": "native_share_api",
"url": "https://www.facebook.com/sharer/sharer.php?u={link}"e={caption}"
},
"whatsapp": {
"method": "url_scheme",
"url": "https://wa.me/?text={caption_with_link}"
},
"email": {
"method": "mailto_link",
"url": "mailto:?subject={subject}&body={caption}"
},
"sms": {
"method": "sms_protocol",
"url": "sms:?body={caption}"
},
"web_share_api": {
"method": "navigator.share()",
"fallback": "copy_to_clipboard"
}
}
}Page Title:
"Join the Referral Program"
Subtitle:
"Earn rewards by sharing [Studio Name] with friends"
Consent Checkboxes:
Button Labels:
"Join & Start Earning" (primary) | "Maybe Later" (secondary)
Section Title:
"Sharing Tools"
Default Captions by Voice:
Share Button Labels:
"Instagram" | "Facebook" | "WhatsApp" | "Email" | "SMS"
Toast Messages:
Import Errors:
Sharing Errors:
💡 CSV Template: "Required columns: name, email | Optional: phone"
💡 Referral Code: "Share this code with friends who prefer typing to clicking"
💡 Caption Customization: "Personalize this message to get better results"
💡 Privacy: "We never share your personal contact information with referred leads"
💡 Fraud Prevention: "Studios that reward on 'Paid Membership' see 73% fewer fraudulent referrals"