Design a user referral system for an existing app

Problem Statement

Design a referral system for a sports betting application that enables existing users to invite new users through unique referral codes or links. When a referred user signs up and completes their first deposit, the referrer receives a ten-dollar reward credited to their in-app balance. The system must integrate with the existing signup and payments infrastructure without disrupting those critical paths.

The core engineering challenges are reliable attribution across platforms (web, iOS, Android), exactly-once reward distribution despite retries and concurrent events, fraud prevention against self-referrals and bot farming, and financial auditability for every reward issued. The referral flow spans multiple services and can take days between code share and qualifying deposit, requiring durable state tracking and asynchronous event processing.

Key Requirements

Functional

• Code generation and sharing -- users generate a unique referral code or deep link that attributes new signups to them, shareable via SMS, email, or social media
• Cross-platform attribution -- correctly attribute signups to referrers across web, iOS, and Android, handling app installs, browser redirects, and session changes
• Reward distribution -- credit a ten-dollar reward to the referrer once the referred user's first deposit clears, with no double payouts
• Referral dashboard -- users view their referral history, pending conversions, and earned rewards; receive notifications when rewards are credited

Non-Functional

• Scalability -- handle 100,000 new referrals per day during promotions with burst capacity to 500,000
• Reliability -- guarantee no reward is lost or double-credited; 99.9 percent uptime for tracking endpoints
• Latency -- generate referral links in under 200 milliseconds; process rewards within 5 minutes of qualifying deposit
• Consistency -- strong consistency for reward credits and balance updates; eventual consistency acceptable for analytics dashboards

What Interviewers Focus On

Based on real interview experiences, these are the areas interviewers probe most deeply:

1. Attribution Across Platforms and Sessions

Linking a new signup to the correct referrer is harder than it appears. Users share links via SMS that open in different browsers, install the app days later, or switch devices before signing up. Interviewers want to see how you handle these attribution gaps.

Hints to consider:

• Embed signed metadata (referrer ID, campaign ID, expiration) in referral links rather than relying on simple sequential codes
• Use deep linking services that bridge web-to-app transitions and preserve attribution through app installs
• Implement server-side attribution lookup at signup time: check for a stored referral token from deep link, cookie, or clipboard
• Define an attribution window (e.g., 30 days) after which unclaimed referrals expire

2. Exactly-Once Reward Distribution

Deposit events may be delivered multiple times due to retries, and concurrent processing could trigger duplicate payouts. Interviewers expect idempotent, transactional reward issuance.

Hints to consider:

• Model referrals as a state machine: Pending, Signup Completed, Deposit Detected, Reward Issued, with idempotent state transitions
• Use a unique constraint in the database on (referral_id, reward_type) to prevent double-crediting at the storage level
• Wrap reward issuance in a database transaction: insert reward record and update user balance atomically
• Implement event sourcing so every state change is logged for audit trails and dispute resolution

3. Fraud Prevention and Abuse Controls

Simple referral systems attract exploitation through self-referrals, VPN-based account farming, and shared payment methods across fake accounts. Interviewers look for defense in depth.

Hints to consider:

• Block self-referrals by comparing device fingerprints, IP addresses, and payment methods between referrer and referee
• Implement velocity checks: flag accounts that generate an unusual number of referrals in a short time period
• Require minimum account age or activity level before referral rewards become withdrawable
• Design a manual review queue for high-value or suspicious referrals with automated risk scoring

4. Asynchronous Event Processing

The qualifying deposit may happen days after signup, requiring durable event handling across service boundaries. Interviewers want to see decoupled, resilient processing.

Hints to consider:

• Publish deposit events to Kafka partitioned by user ID to guarantee ordering for a single user's events
• Use the transactional outbox pattern in the payments service to avoid lost events when the database commits but the message send fails
• Design reward workers to be idempotent: if a deposit event is reprocessed, the worker checks whether the reward has already been issued before proceeding
• Implement dead-letter queues for events that fail processing repeatedly, with monitoring and manual resolution workflows

Suggested Approach

Step 1: Clarify Requirements

Confirm what constitutes a qualifying action -- is it any first deposit above a threshold, or does the deposit amount matter? Ask about reward tiers versus a flat rate. Clarify the attribution window duration. Understand whether the referral system needs to support concurrent promotional campaigns with different reward structures. Verify regulatory requirements around promotional rewards in the sports betting jurisdictions.

Step 2: High-Level Architecture

Sketch core components: Referral Service (generates codes, stores referral records, manages attribution), Event Stream (Kafka for capturing signup, deposit, and reward events), Reward Engine (consumes qualifying events, validates eligibility, credits accounts with idempotency guarantees), Fraud Detection Service (scores referrals in real time using device, IP, and payment signals), User Account Service (existing service managing balances and transaction history), and Analytics Pipeline (aggregates referral funnel metrics for marketing dashboards). Show the flow: referrer generates code, referee clicks link and signs up with attribution token, referee makes first deposit, deposit event triggers reward evaluation, reward engine credits referrer.

Step 3: Deep Dive on Reward Distribution

Walk through the critical path from deposit to reward. The payments service commits the deposit transaction and writes a "DepositCompleted" event to an outbox table. A Kafka Connect connector publishes the outbox event to a Kafka topic partitioned by user ID. The Reward Engine consumes the event and looks up the referral record for this user. It verifies the referral is still within the attribution window, the referee has not already triggered a reward, and the deposit meets the minimum threshold. The engine then executes a database transaction: insert a reward record with status ISSUED, update the referrer's balance, and mark the referral as completed. A unique constraint on (referral_id, reward_type) prevents double-crediting on retry. On success, a "RewardGranted" event is published for notification delivery and analytics. If fraud signals are present, the reward enters a HELD state for manual review.

Step 4: Address Secondary Concerns

Cover analytics: referral events feed a data warehouse for funnel analysis (shares, clicks, signups, deposits, rewards). Discuss campaign management using a configuration-driven rule engine where marketers can adjust reward amounts, qualifying criteria, and duration without code changes. Address monitoring by tracking conversion rates, time-to-conversion, fraud flag rates, and system latency. Explain how to handle reward reversals if a qualifying deposit is later refunded or charged back, using compensating transactions to debit the referrer's balance and mark the referral as reversed. Touch on internationalization for multi-currency support and localized notification messaging.

Related Learning Resources

• Design Bitly -- covers unique code generation, link attribution, and redirect tracking at scale
• Databases -- transactional guarantees, unique constraints, and the outbox pattern for event-driven workflows
• Message Queues -- Kafka-based event processing with exactly-once semantics and dead-letter queues