Designing a Referral System Without a Heavy Backend

// utils/referralCode.ts
// 28 chars with confusing ones removed. 8 places ~= 4.7 trillion combinations
const ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
 
export function generateReferralCode(length = 8): string {
  let code = "";
  const bytes = new Uint8Array(length);
  // On Expo, use getRandomValues from expo-crypto
  crypto.getRandomValues(bytes);
  for (let i = 0; i < length; i++) {
    code += ALPHABET[bytes[i] % ALPHABET.length];
  }
  return code;
}

// convex/referrals.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";
 
export const ensureMyCode = mutation({
  args: { ownerId: v.string(), candidate: v.string() },
  handler: async (ctx, { ownerId, candidate }) => {
    // Reuse an existing code so re-issuing never changes the number
    const existing = await ctx.db
      .query("referralCodes")
      .withIndex("by_owner", (q) => q.eq("ownerId", ownerId))
      .unique();
    if (existing) return existing.code;
 
    // Check the candidate is not already taken
    const clash = await ctx.db
      .query("referralCodes")
      .withIndex("by_code", (q) => q.eq("code", candidate))
      .unique();
    if (clash) {
      throw new Error("CODE_TAKEN"); // client makes a new candidate and retries
    }
 
    await ctx.db.insert("referralCodes", {
      ownerId,
      code: candidate,
      createdAt: Date.now(),
    });
    return candidate;
  },
});

<!-- Referral landing page (e.g. https://example.com/i/ABCD2345 ) -->
<script>
  const code = location.pathname.split("/").pop();
  // To the clipboard (some browsers require a user gesture, so offer a button too)
  navigator.clipboard?.writeText("ref:" + code).catch(() => {});
  // Send to the store
  const ua = navigator.userAgent;
  const store = /android/i.test(ua)
    ? "https://play.google.com/store/apps/details?id=YOUR_PACKAGE"
    : "https://apps.apple.com/app/idYOUR_APP_ID";
  document.getElementById("go").href = store;
</script>

// hooks/useDeferredReferral.ts
import * as Clipboard from "expo-clipboard";
import AsyncStorage from "@react-native-async-storage/async-storage";
 
const FLAG = "referral.checkedClipboard";
const PENDING = "referral.pendingCode";
 
export async function captureDeferredReferralOnce(): Promise<string | null> {
  // Run only once on first launch (do not re-read on every restart)
  if (await AsyncStorage.getItem(FLAG)) return null;
  await AsyncStorage.setItem(FLAG, "1");
 
  try {
    const text = await Clipboard.getStringAsync();
    if (text?.startsWith("ref:")) {
      const code = text.slice(4).trim();
      if (/^[A-Z0-9]{6,12}$/.test(code)) {
        await AsyncStorage.setItem(PENDING, code);
        return code;
      }
    }
  } catch {
    // Failure is not fatal (the referral simply does not attach)
  }
  return null;
}

import * as Linking from "expo-linking";
 
// Pick up ?ref= from the launch URL (already-installed path)
const url = await Linking.getInitialURL();
if (url) {
  const { queryParams } = Linking.parse(url);
  if (typeof queryParams?.ref === "string") {
    await AsyncStorage.setItem(PENDING, queryParams.ref);
  }
}

// convex/referrals.ts
export const claimReferral = mutation({
  args: { code: v.string(), inviteeId: v.string(), deviceId: v.string() },
  handler: async (ctx, { code, inviteeId, deviceId }) => {
    const owner = await ctx.db
      .query("referralCodes")
      .withIndex("by_code", (q) => q.eq("code", code))
      .unique();
    if (!owner) return { ok: false, reason: "INVALID_CODE" };
 
    // Forbid self-referral
    if (owner.ownerId === inviteeId) return { ok: false, reason: "SELF" };
 
    // One claim per invitee
    const already = await ctx.db
      .query("referrals")
      .withIndex("by_invitee", (q) => q.eq("inviteeId", inviteeId))
      .unique();
    if (already) return { ok: false, reason: "ALREADY_CLAIMED" };
 
    // Simple device-dedupe (guards against farming on one device)
    const sameDevice = await ctx.db
      .query("referrals")
      .withIndex("by_device", (q) => q.eq("deviceId", deviceId))
      .collect();
    if (sameDevice.length >= 1) return { ok: false, reason: "DEVICE_LIMIT" };
 
    await ctx.db.insert("referrals", {
      referrerId: owner.ownerId,
      inviteeId,
      deviceId,
      code,
      status: "pending", // reward not yet finalized
      claimedAt: Date.now(),
    });
    return { ok: true };
  },
});

// convex/referrals.ts
export const fulfillReferral = mutation({
  args: { inviteeId: v.string() },
  handler: async (ctx, { inviteeId }) => {
    const ref = await ctx.db
      .query("referrals")
      .withIndex("by_invitee", (q) => q.eq("inviteeId", inviteeId))
      .unique();
    if (!ref) return { ok: false, reason: "NO_REFERRAL" };
 
    // Already finalized? Do nothing (the heart of idempotency)
    if (ref.status === "fulfilled") return { ok: true, idempotent: true };
 
    // Judge the condition on the server (never trust the client's self-report)
    const milestone = await ctx.db
      .query("milestones")
      .withIndex("by_user", (q) => q.eq("userId", inviteeId))
      .unique();
    if (!milestone || milestone.savedCount < 3) {
      return { ok: false, reason: "CONDITION_NOT_MET" };
    }
 
    // Advance state to fulfilled FIRST, then grant to both (order matters)
    await ctx.db.patch(ref._id, { status: "fulfilled", fulfilledAt: Date.now() });
    await grantReward(ctx, ref.referrerId, "referrer");
    await grantReward(ctx, inviteeId, "invitee");
    return { ok: true };
  },
});