Complete referral-aware signup experience
╔═══════════════════════════════════════════════════════════════════════════════╗
║ NEW CLIENT SIGNUP FLOW - REFERRAL ATTRIBUTION SYSTEM ║
╚═══════════════════════════════════════════════════════════════════════════════╝
┌───────────────────────────────────────────────────────────────────────────────┐
│ PHASE 1: REFERRAL LINK CLICK & ATTRIBUTION CAPTURE │
└───────────────────────────────────────────────────────────────────────────────┘
Potential client clicks: app.com/refer/A7K9M2XQ
│
▼
┌────────────────────────────────────────┐
│ EXTRACT REFERRAL CODE │
│ • Parse URL param: A7K9M2XQ │
│ • Lookup Member by referral_code │
│ • Verify member & studio are active │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────┐
│ PERSIST ATTRIBUTION (Multi-Layer) │
│ │
│ Layer 1: Cookies (30-day expiration) │
│ ├─ ref_code: A7K9M2XQ │
│ ├─ ref_member: member_uuid │
│ ├─ ref_studio: studio_uuid │
│ ├─ ref_campaign: campaign_uuid │
│ ├─ ref_first_click: timestamp │
│ └─ ref_session_id: unique_session │
│ │
│ Layer 2: Session Storage (same session) │
│ └─ Same keys as cookies for immediate access │
│ │
│ Layer 3: URL Parameters (fallback) │
│ └─ Preserve ref= param through multi-step flow │
│ │
│ Layer 4: Local Storage (backup) │
│ └─ 30-day persistent fallback if cookies blocked │
└────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ CREATE REFERRAL CLICK EVENT │
│ INSERT ReferralClick: │
│ • referral_code │
│ • member_id │
│ • studio_id │
│ • session_id │
│ • ip_address │
│ • user_agent │
│ • device_type │
│ • click_timestamp │
└────────────────────────────────────────┘
│
▼
Load Referral Landing Page
┌───────────────────────────────────────────────────────────────────────────────┐
│ PHASE 2: REFERRAL LANDING PAGE (Branded & Personalized) │
└───────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ REFERRAL LANDING PAGE LAYOUT │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ HERO SECTION │ │
│ │ • Studio logo (top left) │ │
│ │ • Background: studio.images.hero or brand gradient │ │
│ │ • Primary color overlay │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ PERSONALIZED HEADLINE │ │
│ │ "{Referrer First Name} invited you to {Studio Name}!" │ │
│ │ (or) "Welcome to {Studio Name}!" │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ OFFER CALLOUT │ │
│ │ 🎁 YOUR EXCLUSIVE OFFER │ │
│ │ "Get {offer_description}" │ │
│ │ e.g., "Free 7-Day Trial" | "$50 Off First Month" │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ STUDIO DESCRIPTION │ │
│ │ • Short description (2-3 sentences) │ │
│ │ • Class types offered │ │
│ │ • Community highlights │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ SOCIAL PROOF (optional) │ │
│ │ ⭐⭐⭐⭐⭐ "500+ happy members" │ │
│ │ Member photos (if available) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ CALL-TO-ACTION │ │
│ │ [Claim Your Offer →] │ │
│ │ (Scrolls to form or opens form) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Branding Applied:
├─ Logo: organization.logo_url
├─ Colors: organization.primary_color
├─ Studio: studio.name, studio.description
└─ Offer: campaign.reward_structure.description
┌───────────────────────────────────────────────────────────────────────────────┐
│ PHASE 3: LEAD CAPTURE FORM │
└───────────────────────────────────────────────────────────────────────────────┘
User clicks "Claim Your Offer"
│
▼
┌─────────────────────────────────────────┐
│ LEAD CAPTURE FORM │
│ │
│ Required Fields: │
│ ┌───────────────────────────────────┐ │
│ │ First Name * │ │
│ │ [John ] │ │
│ │ ✓ Min 2 chars, letters only │ │
│ └───────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────┐ │
│ │ Last Name * │ │
│ │ [Doe ] │ │
│ │ ✓ Min 2 chars, letters only │ │
│ └───────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────┐ │
│ │ Email Address * │ │
│ │ [john@example.com] │ │
│ │ ✓ Valid email format │ │
│ └───────────────────────────────────┘ │
│ │
│ Optional Fields: │
│ ┌───────────────────────────────────┐ │
│ │ Phone Number │ │
│ │ [+1 (555) 123-4567] │ │
│ │ ✓ Valid phone format │ │
│ └───────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────┐ │
│ │ Interested In │ │
│ │ [Select class type ▾] │ │
│ │ Options: Yoga, Strength, HIIT... │ │
│ └───────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────┐ │
│ │ Preferred Time │ │
│ │ [Select time ▾] │ │
│ │ Morning, Afternoon, Evening... │ │
│ └───────────────────────────────────┘ │
│ │
│ [✓ Claim Your Offer] │
│ │
│ Fine print: │
│ "By submitting, you agree to receive │
│ communications about classes." │
└─────────────────────────────────────────┘
Validation Rules:
┌────────────────────────────────────────────────────┐
│ first_name: │
│ • Required: true │
│ • Min length: 2 │
│ • Pattern: Letters and spaces only │
│ • Error: "First name is required" │
│ │
│ last_name: │
│ • Required: true │
│ • Min length: 2 │
│ • Pattern: Letters and spaces only │
│ • Error: "Last name is required" │
│ │
│ email: │
│ • Required: true │
│ • Pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$ │
│ • Error: "Please enter a valid email address" │
│ │
│ phone: │
│ • Required: false │
│ • Pattern: ^\+?[\d\s\-()]+$ │
│ • Error: "Please enter a valid phone number" │
│ │
│ preferred_class_type: │
│ • Required: false │
│ • Options: yoga, strength, cardio, hiit, etc. │
│ │
│ preferred_time: │
│ • Required: false │
│ • Options: early_morning, morning, midday, etc. │
└────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────┐
│ PHASE 4: FORM SUBMISSION & ATTRIBUTION LOCKING │
└───────────────────────────────────────────────────────────────────────────────┘
User clicks "Claim Your Offer"
│
▼
┌────────────────────────────────────────┐
│ VALIDATE FORM │
│ • Check all required fields │
│ • Run validation rules │
│ • Show errors inline if invalid │
└────────────────────────────────────────┘
│
▼ (if valid)
┌────────────────────────────────────────────────────┐
│ RETRIEVE REFERRAL ATTRIBUTION DATA │
│ • Read from cookies/session/localStorage │
│ • Fallback chain: │
│ 1. Session storage (immediate) │
│ 2. Cookies (30-day persist) │
│ 3. Local storage (backup) │
│ 4. URL params (last resort) │
└────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ CREATE LEAD RECORD │
│ INSERT Lead: │
│ • studio_id │
│ • referred_by_member_id ← attribution │
│ • referral_code_used ← attribution │
│ • first_name, last_name, email │
│ • phone (if provided) │
│ • status: 'new' │
│ • interested_in: [class_types] │
│ • utm_params: { source: 'referral' } │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ LOCK ATTRIBUTION │
│ CREATE AttributionRecord: │
│ • lead_id │
│ • member_id │
│ • studio_id │
│ • referral_code │
│ • attribution_model: 'first_touch' │
│ • first_click_date │
│ • signup_date: NOW() │
│ • locked: true ← IMMUTABLE │
│ • locked_date: NOW() │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ CREATE REFERRAL EVENT │
│ INSERT ReferralEvent: │
│ • event_type: 'lead_signup' │
│ • member_id │
│ • lead_id │
│ • studio_id │
│ • campaign_id │
│ • referral_code │
│ • timestamp: NOW() │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ UPDATE REFERRAL CLICK │
│ SET: │
│ • converted_to_lead: true │
│ • lead_id: [new_lead_id] │
└────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ NOTIFY REFERRING MEMBER │
│ CREATE Notification: │
│ • member_id │
│ • type: 'lead_signup' │
│ • priority: 'high' │
│ • title: "New Lead Signed Up! 🎉" │
│ • message: "{Name} just signed up!" │
│ • action_url: /my-referrals │
└────────────────────────────────────────┘
│
▼
Show Confirmation Screen
┌───────────────────────────────────────────────────────────────────────────────┐
│ PHASE 5: CONFIRMATION & NEXT STEPS │
└───────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ CONFIRMATION SCREEN │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────┐ │
│ │ ✅ │ │
│ │ You're All Set! 🎉 │ │
│ │ Welcome to {Studio Name}! │ │
│ └────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ YOUR EXCLUSIVE OFFER │ │
│ │ 🎁 {offer_description} │ │
│ │ │ │
│ │ Thanks to {referrer_name}'s referral! │ │
│ │ │ │
│ │ Your Details: │ │
│ │ • {first_name} {last_name} │ │
│ │ • {email} │ │
│ │ • {phone} │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ WHAT HAPPENS NEXT? │ │
│ │ │ │
│ │ 1️⃣ We'll Contact You Soon │ │
│ │ Our team will reach out within 24 hours │ │
│ │ │ │
│ │ 2️⃣ Book Your First Class │ │
│ │ Choose a time that works for you │ │
│ │ │ │
│ │ 3️⃣ Start Your Journey │ │
│ │ Meet the community and discover your potential │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ CONTACT {STUDIO_NAME} │ │
│ │ 📞 {phone} │ │
│ │ 📧 {email} │ │
│ │ 📍 {address} │ │
│ │ │ │
│ │ [📅 Call to Schedule Now] │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ 📧 Confirmation email sent to {email} │
│ │
└─────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────┐
│ PHASE 6: STUDIO NOTIFICATIONS │
└───────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────┐
│ NOTIFY STUDIO OWNER/STAFF │
│ │
│ Trigger: New lead signup │
│ │
│ Notification channels: │
│ • In-app notification │
│ • Email to studio contact │
│ • (Optional) SMS to staff │
│ │
│ Content: │
│ ┌──────────────────────────────────────────────┐ │
│ │ 🎉 New Referral Lead! │ │
│ │ │ │
│ │ {First Name} {Last Name} just signed up │ │
│ │ via {Referrer Name}'s referral link │ │
│ │ │ │
│ │ Contact Info: │ │
│ │ • Email: {email} │ │
│ │ • Phone: {phone} │ │
│ │ │ │
│ │ Preferences: │ │
│ │ • Interested in: {class_type} │ │
│ │ • Preferred time: {time} │ │
│ │ │ │
│ │ [View Lead Details] [Contact Lead] │ │
│ └──────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────┘
Additional Notifications:
┌────────────────────────────────────────────────────┐
│ TRIAL BOOKED │
│ "🏋️ {Lead Name} scheduled their trial for {date}" │
└────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────┐
│ CONVERSION │
│ "💰 {Lead Name} became a paying member!" │
│ "🎁 {Referrer Name} earned {reward_amount}" │
└────────────────────────────────────────────────────┘
Duration: 30 days
Scope: Domain-wide
SameSite: Lax (allows cross-origin navigation)
Secure: true (HTTPS only)
Stored Data:
Duration: Browser session only
Purpose: Immediate access during signup flow
Advantage: Not subject to cookie restrictions
Cleared when browser tab closes
Duration: 30 days (manual expiration)
Purpose: Backup if cookies blocked
Check: Verify timestamp on read, purge if expired
Format: ?ref=A7K9M2XQ
Purpose: Preserve through page navigation
Limitation: Can be lost on external redirects
1. Session Storage (check first - immediate)
└─ If found → use immediately
2. Cookies (check second - persistent)
└─ If found → copy to session storage
3. Local Storage (check third - fallback)
└─ If found and not expired → use
4. URL Parameters (check last)
└─ If found → persist to all layers
5. None found
└─ Direct visit (no referral)
⚠️ Attribution Locking
Once a lead submits the form, attribution is permanently locked via the AttributionRecord entity with locked: true. This prevents:
✗ "First name is required"
✗ "Last name is required"
✗ "Email is required"
✗ "Please enter a valid email address"
✗ "Please enter a valid phone number"
✗ "Invalid referral code"
✗ "This referral link has expired"
✗ "Referral program is no longer active"
✗ "This member is no longer active"
✗ "Failed to submit. Please try again."
✗ "You've already signed up using this email"
✗ "Network error. Please check your connection."
✓ "You're all set! Welcome to [studio_name]!"
✓ "Confirmation email sent to [email]"
✓ "We'll contact you within 24 hours"
Subject: Welcome to [studio_name]! 🎉
Hi [first_name],
Thanks for signing up! We're excited to welcome you to [studio_name].
Your Offer: [offer_description]
What's next?
Questions? Reply to this email or call us at [studio_phone].
See you soon!
— The [studio_name] Team
Subject: 🎉 New Referral Lead: [first_name] [last_name]
A new lead just signed up via [referrer_name]'s referral!
Lead Details:
Next Steps: Contact them within 24 hours to schedule their first visit.
[View in Dashboard →]
Subject: Great news! Your referral signed up 🎊
Hi [member_name],
Awesome news! [lead_first_name] just signed up using your referral link!
We'll reach out to them soon to get them started. You're one step closer to earning your reward! 🎁
Keep sharing your link to earn more rewards.
[Track Your Referrals →]