How referrals work

When someone signs up, we generate a unique 8-character referral_code using nanoid with a URL-safe alphabet. That code becomes their personal share link: qubed.xyz/<slug>?ref=<code>. The code is stored on the subscribers row alongside their email and queue position.

When a friend signs up via that link, we set referred_by on the new subscriber to point at the referrer's row, then increment the referrer's referral_count. Both events are logged to the events table as referral_click and referral_convert.

Position improves with each successful referral. The default boost is 3 spots per referral, configurable per page (see Adjust the boost amount). Effective position = original_position - (referral_count * boost), with a floor of 1 so nobody jumps ahead of the very first signup.

The whole loop closes with email. Both the referrer and the referred friend get a confirmation, and crossing milestones (5, 10, 25 referrals) triggers a referral-reward email built with React Email. Every send is idempotent — duplicates are dropped by (subscriber_id, milestone).