Viral by Design: A Django Deep-Dive into Referral Systems That Boost Long Term Value

1┌─────────────────────────────────────────────────────────────┐
2│                     USER JOURNEY FLOW                        │
3└─────────────────────────────────────────────────────────────┘
4                              │
5                              ▼
6                    ┌──────────────────┐
7                    │   User Signs Up   │
8                    │   Creates Account │
9                    └──────────────────┘
10                              │
11                              ▼
12                    ┌──────────────────┐
13                    │ Unique Referral  │
14                    │  Code Generated  │
15                    │   (e.g., abc123) │
16                    └──────────────────┘
17                              │
18                              ▼
19                    ┌──────────────────┐
20                    │  User Shares URL │
21                    │ /abc123/ via     │
22                    │ Social/Email/Link│
23                    └──────────────────┘
24                              │
25                              ▼
26                    ┌──────────────────┐
27                    │  Friend Clicks   │
28                    │  Referral Link   │
29                    │  (Tracked in     │
30                    │   Session)       │
31                    └──────────────────┘
32                              │
33                              ▼
34                    ┌──────────────────┐
35                    │ Auto-Redirect to │
36                    │   Signup Page    │
37                    │ (Shows "Referred │
38                    │  by Username")   │
39                    └──────────────────┘
40                              │
41                              ▼
42                    ┌──────────────────┐
43                    │  Friend Creates  │
44                    │     Account      │
45                    └──────────────────┘
46                              │
47                              ▼
48                    ┌──────────────────┐
49                    │ Referral Tracked │
50                    │  in Database     │
51                    │ (referred_by FK) │
52                    └──────────────────┘
53                              │
54                              ▼
55                    ┌──────────────────┐
56                    │  Original User's │
57                    │   Stats Update   │
58                    │ Total Referrals++│
59                    │  Rewards += 10   │
60                    └──────────────────┘

1-- Core Profile Model
2CREATE TABLE profiles_profile (
3    id SERIAL PRIMARY KEY,
4    user_id INTEGER UNIQUE REFERENCES auth_user(id),
5    code VARCHAR(12) UNIQUE NOT NULL,  -- Referral code
6    referred_by_id INTEGER REFERENCES profiles_profile(id),  -- Who referred them
7    updated TIMESTAMP DEFAULT NOW(),
8    created TIMESTAMP DEFAULT NOW()
9);
10
11-- Indexes for Performance
12CREATE INDEX idx_profile_code ON profiles_profile(code);
13CREATE INDEX idx_profile_referred_by ON profiles_profile(referred_by_id);
14CREATE INDEX idx_profile_user ON profiles_profile(user_id);

1# filepath: backend/profiles/models.py
2import random
3import string
4
5def code_generator(length=8):
6    """
7    Generate cryptographically random referral code.
8    
9    Why 8 characters?
10    - 62^8 = 218 trillion possible combinations
11    - Collision probability < 0.000001% at 1M users
12    """
13    chars = string.ascii_lowercase + string.digits  # a-z, 0-9
14    return ''.join(random.choice(chars) for _ in range(length))
15
16class Profile(models.Model):
17    user = models.OneToOneField(User, on_delete=models.CASCADE)
18    code = models.CharField(max_length=12, blank=True, unique=True)
19    referred_by = models.ForeignKey(
20        'self', 
21        on_delete=models.SET_NULL, 
22        null=True, 
23        blank=True,
24        related_name='referrals'  # Access via user.profile.referrals.all()
25    )
26    
27    def save(self, *args, **kwargs):
28        if not self.code:
29            # Generate unique code on first save
30            self.code = code_generator()
31        super().save(*args, **kwargs)

1# filepath: backend/backend/views.py
2def main_view(request, ref_code=None):
3    """
4    Handle referral link visits and tracking.
5    
6    Flow:
7    1. User clicks /abc123/
8    2. Store code in session
9    3. Redirect to signup
10    4. On signup, retrieve code and link users
11    """
12    if ref_code:
13        # Verify code exists
14        if Profile.objects.filter(code=ref_code).exists():
15            # Store in session (persists across requests)
16            request.session['ref_code'] = ref_code
17            
18            # Get referrer's username for display
19            profile = Profile.objects.select_related('user').get(code=ref_code)
20            request.session['ref_username'] = profile.user.username
21            
22            # Redirect to signup with context
23            return redirect('signup-view')
24        else:
25            # Invalid code - proceed normally
26            return redirect('main-view')
27    
28    # Regular dashboard view for logged-in users
29    if request.user.is_authenticated:
30        profile = request.user.profile
31        
32        # Calculate real-time stats (optimized queries)
33        stats = {
34            'total_referrals': profile.get_total_referrals(),
35            'rewards': profile.get_rewards_earned(),
36            'active_network': profile.get_total_referrals(),
37        }
38        
39        return render(request, 'main.html', stats)
40    
41    return render(request, 'main.html')

1# filepath: backend/backend/views.py
2def signup_view(request):
3    # Retrieve referral context from session
4    ref_code = request.session.get('ref_code')
5    ref_username = request.session.get('ref_username')
6    
7    if request.method == 'POST':
8        form = UserCreationForm(request.POST)
9        
10        if form.is_valid():
11            # Create user account
12            new_user = form.save()
13            
14            # Link to referrer if code exists
15            if ref_code:
16                try:
17                    referrer = Profile.objects.get(code=ref_code)
18                    new_user.profile.referred_by = referrer
19                    new_user.profile.save()
20                    
21                    # Clean up session
22                    del request.session['ref_code']
23                    del request.session['ref_username']
24                    
25                    # Optional: Send notification to referrer
26                    # notify_referrer(referrer, new_user)
27                    
28                except Profile.DoesNotExist:
29                    pass  # Code expired/invalid - proceed anyway
30            
31            # Auto-login new user
32            login(request, new_user)
33            return redirect('main-view')
34    else:
35        form = UserCreationForm()
36    
37    context = {
38        'form': form,
39        'ref_username': ref_username,  # Show "Referred by John"
40    }
41    return render(request, 'signup.html', context)

1# filepath: backend/profiles/models.py
2class Profile(models.Model):
3    # ...existing fields...
4    
5    def get_total_referrals(self):
6        """
7        Count all users this profile has referred.
8        
9        SQL Generated:
10        SELECT COUNT(*) FROM profiles_profile 
11        WHERE referred_by_id = {self.id}
12        
13        Performance: O(1) - Database index scan
14        """
15        return Profile.objects.filter(referred_by=self).count()
16    
17    def get_rewards_earned(self):
18        """
19        Calculate reward points.
20        
21        Business Logic:
22        - 10 points per referral
23        - Linear scaling (could add tiers)
24        """
25        return self.get_total_referrals() * 10
26    
27    def get_active_network(self):
28        """
29        Return active referrals (currently all are active).
30        
31        Future Enhancement:
32        - Filter by last_login > 30 days
33        - Add 'active' status field
34        """
35        return self.get_total_referrals()

-- Without Optimization (N+1 Query Problem)
SELECT * FROM profiles_profile WHERE user_id = 1;  -- Get user profile
-- Then for EACH referral:
SELECT * FROM profiles_profile WHERE referred_by_id = 1;  -- 100 queries if 100 referrals

-- With Optimization (Single Query)
SELECT COUNT(*) FROM profiles_profile WHERE referred_by_id = 1;  -- 1 query total

1<!-- filepath: backend/templates/main.html -->
2<div class="referral-card bg-gradient-to-br from-purple-600 to-blue-600 rounded-2xl p-8 text-white">
3    <h3 class="text-2xl font-bold mb-4">Your Referral Link</h3>
4    
5    <!-- The URL users share -->
6    <div class="flex gap-2 items-center bg-white/20 rounded-lg p-4">
7        <input 
8            type="text" 
9            id="referralLink" 
10            value="http://{{ request.get_host }}/{{ profile.code }}/" 
11            readonly
12            class="flex-1 bg-transparent border-none text-white"
13        >
14        
15        <!-- Copy button with visual feedback -->
16        <button 
17            onclick="copyReferralLink()" 
18            class="bg-white text-purple-600 px-6 py-2 rounded-lg hover:bg-purple-50 transition"
19        >
20            <i class="fas fa-copy mr-2"></i>
21            <span id="copyText">Copy</span>
22        </button>
23    </div>
24    
25    <!-- Social sharing buttons -->
26    <div class="flex gap-4 mt-6">
27        <a href="https://twitter.com/intent/tweet?text=Join me on ReferralHub!&url=http://{{ request.get_host }}/{{ profile.code }}/" 
28           class="share-btn bg-[#1DA1F2] hover:bg-[#1a8cd8]">
29            <i class="fab fa-twitter"></i> Twitter
30        </a>
31        
32        <a href="https://www.facebook.com/sharer/sharer.php?u=http://{{ request.get_host }}/{{ profile.code }}/" 
33           class="share-btn bg-[#4267B2] hover:bg-[#365899]">
34            <i class="fab fa-facebook"></i> Facebook
35        </a>
36        
37        <a href="mailto:?subject=Join ReferralHub&body=Hey! Join me on ReferralHub: http://{{ request.get_host }}/{{ profile.code }}/" 
38           class="share-btn bg-gray-600 hover:bg-gray-700">
39            <i class="fas fa-envelope"></i> Email
40        </a>
41    </div>
42</div>
43
44<script>
45function copyReferralLink() {
46    const input = document.getElementById('referralLink');
47    const button = document.getElementById('copyText');
48    
49    // Modern clipboard API (more secure than execCommand)
50    navigator.clipboard.writeText(input.value).then(() => {
51        // Visual feedback
52        button.textContent = 'Copied!';
53        button.parentElement.classList.add('bg-green-500');
54        
55        // Reset after 2 seconds
56        setTimeout(() => {
57            button.textContent = 'Copy';
58            button.parentElement.classList.remove('bg-green-500');
59        }, 2000);
60    });
61}
62</script>

# filepath: backend/backend/settings.py
MIDDLEWARE = [
    'django.middleware.csrf.CsrfViewMiddleware',  # Prevents cross-site request forgery
    # ...other middleware
]

# In templates
{% csrf_token %}  # Generates unique token per session

❌ Malicious site submits form on behalf of user
✅ Request rejected (no valid CSRF token)

# ❌ VULNERABLE (Don't do this)
Profile.objects.raw(f"SELECT * FROM profiles_profile WHERE code = '{user_input}'")

# ✅ SECURE (Django ORM auto-escapes)
Profile.objects.filter(code=user_input)  # Parameterized query

SELECT * FROM profiles_profile WHERE code = %s  -- %s is safely escaped

<!-- Django auto-escapes by default -->
{{ user.username }}  <!-- <script>alert('xss')</script> → &lt;script&gt;... -->

<!-- Explicit escaping for extra safety -->
{{ user_input|escape }}

1# filepath: backend/backend/settings.py
2# Using django-ratelimit package
3
4from ratelimit.decorators import ratelimit
5
6@ratelimit(key='ip', rate='5/m')  # 5 signups per minute per IP
7def signup_view(request):
8    # Prevents abuse/bot attacks
9    pass

1# ❌ SLOW: N+1 Query Problem
2profile = Profile.objects.get(user=request.user)  # 1 query
3referrals = profile.referrals.all()  # 1 query
4for ref in referrals:
5    print(ref.user.username)  # N queries (1 per referral!)
6
7# ✅ FAST: Prefetch Related Data
8profile = Profile.objects.select_related('user').get(user=request.user)  # 1 query
9referrals = profile.referrals.select_related('user').all()  # 1 query (with JOIN)
10for ref in referrals:
11    print(ref.user.username)  # No additional queries!

1# filepath: backend/backend/views.py
2from django.core.cache import cache
3
4def get_user_stats(profile):
5    cache_key = f'stats_{profile.id}'
6    
7    # Try cache first (Redis/Memcached)
8    stats = cache.get(cache_key)
9    
10    if not stats:
11        # Cache miss - calculate from database
12        stats = {
13            'total_referrals': profile.get_total_referrals(),
14            'rewards': profile.get_rewards_earned(),
15        }
16        # Cache for 5 minutes
17        cache.set(cache_key, stats, 300)
18    
19    return stats

1<!-- filepath: backend/templates/base.html -->
2
3<!-- Preload critical CSS -->
4<link rel="preload" href="{% static 'css/main.css' %}" as="style">
5
6<!-- Defer non-critical JavaScript -->
7<script src="{% static 'js/analytics.js' %}" defer></script>
8
9<!-- Use CDN for third-party libraries -->
10<link href="https://cdn.jsdelivr.net/npm/tailwindcss@3/dist/tailwind.min.css" rel="stylesheet">

1# 1. Install Heroku CLI
2curl https://cli-assets.heroku.com/install.sh | sh
3
4# 2. Login
5heroku login
6
7# 3. Create app
8heroku create referralhub-app
9
10# 4. Add PostgreSQL (required for production)
11heroku addons:create heroku-postgresql:hobby-dev
12
13# 5. Set environment variables
14heroku config:set SECRET_KEY='your-secret-key'
15heroku config:set DEBUG=False
16heroku config:set ALLOWED_HOSTS='referralhub-app.herokuapp.com'
17
18# 6. Deploy
19git push heroku main
20
21# 7. Run migrations
22heroku run python backend/manage.py migrate
23
24# 8. Create superuser
25heroku run python backend/manage.py createsuperuser
26
27# Done! Visit: https://referralhub-app.herokuapp.com

1# 1. Create Ubuntu 22.04 Droplet ($6/month)
2# 2. SSH into server
3ssh root@your-droplet-ip
4
5# 3. Install dependencies
6apt update && apt upgrade -y
7apt install python3-pip python3-venv postgresql nginx -y
8
9# 4. Clone repository
10git clone https://github.com/yourusername/referralhub.git
11cd referralhub
12
13# 5. Setup virtual environment
14python3 -m venv venv
15source venv/bin/activate
16pip install -r requirements.txt
17
18# 6. Configure PostgreSQL
19sudo -u postgres psql
20CREATE DATABASE referralhub;
21CREATE USER referraluser WITH PASSWORD 'securepassword';
22GRANT ALL PRIVILEGES ON DATABASE referralhub TO referraluser;
23\q
24
25# 7. Configure environment
26export DATABASE_URL='postgresql://referraluser:securepassword@localhost/referralhub'
27export SECRET_KEY='your-secret-key'
28export DEBUG=False
29
30# 8. Collect static files
31python backend/manage.py collectstatic --noinput
32
33# 9. Setup Gunicorn (WSGI server)
34pip install gunicorn
35gunicorn --chdir backend backend.wsgi:application --bind 0.0.0.0:8000
36
37# 10. Configure Nginx (reverse proxy)
38# See detailed config in repository

1# filepath: docker-compose.yml
2version: '3.8'
3
4services:
5  web:
6    build: .
7    command: gunicorn backend.wsgi:application --bind 0.0.0.0:8000
8    volumes:
9      - .:/code
10    ports:
11      - "8000:8000"
12    environment:
13      - DATABASE_URL=postgresql://user:password@db:5432/referralhub
14      - REDIS_URL=redis://redis:6379/0
15    depends_on:
16      - db
17      - redis
18  
19  db:
20    image: postgres:14
21    environment:
22      - POSTGRES_DB=referralhub
23      - POSTGRES_USER=user
24      - POSTGRES_PASSWORD=password
25    volumes:
26      - postgres_data:/var/lib/postgresql/data
27  
28  redis:
29    image: redis:7-alpine
30    
31  nginx:
32    image: nginx:alpine
33    ports:
34      - "80:80"
35    volumes:
36      - ./nginx.conf:/etc/nginx/nginx.conf
37    depends_on:
38      - web
39
40volumes:
41  postgres_data:

1# Build and push to ECR
2aws ecr get-login-password | docker login --username AWS --password-stdin
3docker build -t referralhub .
4docker tag referralhub:latest {aws-account-id}.dkr.ecr.{region}.amazonaws.com/referralhub:latest
5docker push {aws-account-id}.dkr.ecr.{region}.amazonaws.com/referralhub:latest
6
7# Deploy via ECS Fargate (serverless containers)
8aws ecs create-service --cluster referralhub-cluster --service-name referralhub \
9  --task-definition referralhub:1 --desired-count 2 --launch-type FARGATE

[Heroku Hobby Dyno] → [PostgreSQL] → [Redis Cloud (Free)]
Cost: ~$15/month
Response Time: <100ms

1         [Load Balancer]
2               ↓
3    ┌──────────┴──────────┐
4    ↓                     ↓
5[App Server 1]      [App Server 2]
6    ↓                     ↓
7         [RDS PostgreSQL]
8               ↓
9         [ElastiCache Redis]
10Cost: ~$150/month
11Response Time: <50ms

1[Cloudflare CDN] → [API Gateway] → [ECS/Kubernetes]
2                                           ↓
3                        ┌──────────────────┴───────────┐
4                        ↓                              ↓
5                [Referral Service]           [User Service]
6                        ↓                              ↓
7                [Aurora PostgreSQL (Multi-AZ)]
8                        ↓
9                [ElastiCache Cluster]
10Cost: ~$500-1000/month
11Response Time: <20ms globally

// ❌ Problem: GDPR compliance issues, easily manipulated
document.cookie = `ref_code=${code}; max-age=2592000`;  // 30 days

# ✅ Server-side, secure, GDPR-friendly
request.session['ref_code'] = code

1# 1. Prevent self-referrals
2if ref_code and Profile.objects.get(code=ref_code).user == request.user:
3    return redirect('main-view')  # Don't allow self-referral
4
5# 2. Email verification required
6def signup_view(request):
7    # ...
8    send_verification_email(new_user.email)
9    new_user.is_active = False  # Activate after email confirmation
10    # ...
11
12# 3. Rate limiting (already covered in security section)
13@ratelimit(key='ip', rate='5/h')  # 5 signups per hour per IP

# Generates 1 + N queries
for referral in user.profile.referrals.all():
    print(referral.user.email)  # Database hit each iteration!

# Single query with JOIN
referrals = user.profile.referrals.select_related('user').all()
for referral in referrals:
    print(referral.user.email)  # No additional queries

# settings.py
if DEBUG:
    INSTALLED_APPS += ['debug_toolbar']
    MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware']

1<!-- Pre-filled tweet -->
2<a href="https://twitter.com/intent/tweet?text=Check out ReferralHub!&url={{ referral_url }}">
3    Share on Twitter
4</a>
5
6<!-- Pre-filled email -->
7<a href="mailto:?subject=Join me on ReferralHub&body=Sign up here: {{ referral_url }}">
8    Email a Friend
9</a>

1# 1. Clone repository
2git clone https://github.com/yourusername/referral-program-in-Django.git
3cd referral-program-in-Django
4
5# 2. Create virtual environment
6python3 -m venv venv
7source venv/bin/activate  # On Windows: venv\Scripts\activate
8
9# 3. Install dependencies
10pip install -r requirements.txt
11
12# 4. Run migrations
13cd backend
14python manage.py migrate
15
16# 5. Create superuser
17python manage.py createsuperuser
18
19# 6. Run development server
20python manage.py runserver
21
22# 7. Visit http://127.0.0.1:8000/

# filepath: backend/profiles/models.py
def get_rewards_earned(self):
    return self.get_total_referrals() * 20  # Change 10 → 20 for 20 points per referral

1# filepath: backend/backend/views.py
2from django.core.mail import send_mail
3
4def notify_referrer(referrer_profile, new_user):
5    send_mail(
6        subject='New Referral!',
7        message=f'{new_user.username} just signed up using your link!',
8        from_email='noreply@referralhub.com',
9        recipient_list=[referrer_profile.user.email],
10    )

1# filepath: backend/profiles/models.py
2def get_reward_tier(self):
3    referrals = self.get_total_referrals()
4    if referrals >= 100:
5        return 'Diamond'
6    elif referrals >= 50:
7        return 'Gold'
8    elif referrals >= 10:
9        return 'Silver'
10    else:
11        return 'Bronze'