Referrals

Referral system, EquaCash rewards, scratch card mechanics, invitation tracking, and EquaCash transfers

SPEC 015 — Referrals

Field	Value
Status	DRAFT
Priority	P2 — Growth
Backend	equa-server/modules/referral/
Frontend	equa-web/src/modules/referrals/
Endpoints	equa-server/modules/api/src/endpoints/referral-endpoints.ts

---

1. Feature Purpose

The referral system incentivizes user growth through a multi-layered reward mechanism. Users generate unique referral links, invite friends via email, and earn EquaCash (platform virtual currency) through scratch card rewards. The system supports both personal and organization-level referrals, invitation tracking, EquaCash transfers between users/organizations, and transaction history. Google Contacts integration for bulk invites was previously supported but has been deprecated.

---

2. Current State (Verified)

2.1 Referral Link Generation

Detail	Value
File	equa-server/modules/referral/src/referral.ts
Function	randomString() → uniqueReferral()
Algorithm	crypto.randomBytes(6).toString('hex').slice(0, 6) — 6-character hex string
Uniqueness	Recursive retry if link already exists in DB
Auto-creation	Referral record created at registration and on first access to referral page

2.2 Reward Generation

Detail	Value
File	equa-server/modules/referral/src/referral.ts
Function	generateReward()
Distribution	Random 1–100 → $10 (50%), $25 (25%), $50 (20%), $100 (5%)
Reward types	RewardType.signup, RewardType.referral, RewardType.organizationInfo, RewardType.obcl
Scratch mechanic	Reward amount hidden until user “scratches” the card

2.3 Referral Registration Flow

Detail	Value
Function	handleReferralRequest()
Steps	1. Generate referral link for new user 2. Insert signup reward 3. Add to waitlist 4. Look up referrer by link 5. Mark invitation as joined 6. Insert referral reward for referrer 7. Increment referrer’s count
IP limiting	REGISTRATION_IP_LIMIT env var (default 20 registrations per IP)
Blacklists	Email blacklist (getEmailBlacklist) and domain blacklist (getDomainBlacklist)

2.4 Scratch Card Reveal

Detail	Value
Function	revealCard()
Behavior	Accepts array of reward IDs; for each unscratched card owned by user, marks as scratched and adds reward to EquaCash balance
Organization rewards	If reward has an org association, cash goes to org’s balance
Idempotency	Already-scratched cards are returned unchanged

2.5 EquaCash Transfer

Detail	Value
Function	transferEquaCashFromRequest()
Validation	Sender must have sufficient balance (availableCash >= request.value)
Atomicity	Deducts from sender, adds to recipient, inserts transaction record
Request class	NewEquaCashRequest with from, to, fromType, toType, value, currency, currencyType, optional memo

2.6 Transaction History

Detail	Value
Function	transferHistoryFromRequest()
Fields per record	created, type, amount, totalAmount (running balance), earned (boolean), memo, source
Transfer types	EquaCashTransferType.earned, transferProfile, transferOrganization, spend
Source resolution	Earned from referral link, email, OBCL, profile, org, or annual subscription
Running balance	Computed in reverse chronological order

2.7 Invitation System

Detail	Value
Function	sendInvitationEmailFromRequest()
Input	Array of emails, referral link, recipient name
Template	authNotificationTemplates.userInvitation
Invitation URL	{appUrl}/invite/r?user={referralLink} (personal) or {appUrl}/invite/r?organization={orgLink}&user={userLink} (org)
Statuses	InviteStatus.invited, bounced, joined, registered
Upsert	Re-inviting same email updates existing invitation record

2.8 Google Contacts (Deprecated)

Detail	Value
Function	googleContacts()
Status	Throws BadRequest — “The legacy google contacts API is being removed by Google and no longer supported.”

2.9 Company Info Collection

Detail	Value
Function	addUserCompanyInfo()
Purpose	Collects company details during waitlist phase
Fields	name, email, phoneNumber, organizationType (public/private), scheduleTool (zoom/skype/meet), numberSecurityHolder
Reward	RewardType.organizationInfo scratch card on first submission
Email	Sends company info to [e-mail]

---

3. Data Model

Referrals

Column	Type	Constraints
id	uuid	PK
user	uuid	FK to Users
referralLink	text	UNIQUE, 6-char hex
equaCash	numeric	DEFAULT 0, current balance
noOfReferrals	number	DEFAULT 0, count of successful referrals
status	UserStatus	Enum
ipAddress	text	Registration IP

Rewards

Column	Type	Constraints
id	uuid	PK
reward	number	Amount ($10,$25, $50, or$100)
type	RewardType	signup, referral, organizationInfo, obcl
scratched	boolean	DEFAULT false
scratchedDate	Date	Set when card is scratched
user	uuid	FK to Users (reward recipient)
organization	uuid	FK to Organizations (nullable)
recipientByLink	citext	Email of user who joined via link
recipientByEmail	citext	Email of user who joined via email invite

Invitations

Column	Type	Constraints
id	uuid	PK
email	citext	Invitee email
user	uuid	FK to Users (inviter)
organization	uuid	FK to Organizations (nullable)
status	InviteStatus	invited, bounced, joined, registered
created	timestamp	Auto
modified	timestamp	Auto

CompaniesInfo

Column	Type	Constraints
id	uuid	PK
email	citext	Company contact email
name	text	Company name
phoneNumber	text
numberSecurityHolder	number	Expected member count
organizationType	OrganizationType	Enum (public/private)
scheduleTool	ToolType	Enum (zoom/skype/meet)
user	uuid	FK to Users, UNIQUE

UserCoupons

Column	Type	Constraints
user	uuid	FK to Users
code	text	Coupon code

Transactions (EquaCash transfers)

Column	Type	Constraints
id	uuid	PK
from	text	Sender address (user ID, org ID, or chargify)
fromType	AddressType	Enum
to	text	Recipient address
toType	AddressType	Enum
value	number	Transfer amount
currency	text
currencyType	CurrencyType	Enum
memo	text	Optional note
created	timestamp	Auto

---

4. API Endpoints

Method	Path	Auth	Description
GET	/api/v1/referral/:entity	Session	Get referral data (link, EquaCash balance, count, waitlist position)
GET	/api/v1/referral/:entity/rewards	Session	Get scratch cards with daily/monthly stats
GET	/api/v1/referral/:entity/invitations	Session	Get invitation list with stats
POST	/api/v1/referral/:entity/invite	Session	Send email invitations (array of emails)
POST	/api/v1/referral/:entity/reveal	Session	Scratch cards (array of reward IDs)
GET	/api/v1/referral/:entity/equacash	Session	Get EquaCash balance for org context
POST	/api/v1/referral/transfer	Session	Transfer EquaCash between users/orgs
GET	/api/v1/referral/:entity/history	Session	Get transaction history with running balance
POST	/api/v1/referral/company-info	Session	Submit company info during waitlist
GET	/api/v1/referral/waitlist-stats	Public	Get waitlist aggregate stats

---

5. Frontend Components

Module: equa-web/src/modules/referrals/

Pages:

Component	File	Purpose
MyReferrals	pages/my-referrals.tsx	Personal referral dashboard with scratch cards
OrganizationReferrals	pages/organization-referrals.tsx	Organization-level referral management
TransferEquaCash	pages/transfer-equa-cash.tsx	Personal EquaCash transfer form
TransferOrgEquaCash	pages/transfer-org-equa-cash.tsx	Organization EquaCash transfer form
TransferHistoryPage	pages/transfer-history-page.tsx	Personal transaction history
OrgTransferHistoryPage	pages/org-transfer-history-page.tsx	Organization transaction history

Components:

Component	File	Purpose
MyReferralsShared	components/referral-component.tsx	Core referral UI (shared between personal and org views)
ReferralStatistics	components/referral-statistics.tsx	Stats: total referrals, daily/monthly tickets, EquaCash earned
ReferralInvitePanel	components/referral-invite-panel.tsx	Invite-a-friend panel with link sharing
ReferralsTable	components/referrals-table.tsx	Table of sent invitations and their statuses
ScratchCardList	components/scratch-card-list/scratch-card-list.tsx	Grid of scratch cards
ScratchCard	components/scratch-card/scratch-card.tsx	Individual scratch card with reveal animation
ScratchOffPanels	components/scratch-off-panels.tsx	Scratch card section container
TransferCashForm	components/transfer-cash-form.tsx	EquaCash transfer form fields
TransferInfo	components/transfer-info.tsx	Transfer confirmation display
TransactionHistoryTable	components/transaction-history-table.tsx	Table of EquaCash transactions
InviteForm	components/invite-form.tsx	Email invitation form
EquaTransferComponent	components/equa-transfer-component.tsx	Transfer flow container
ClaimEquaCash	components/claim-equacash/claim-equacash.tsx	EquaCash claim UI
SnackBar	components/snack-bar.tsx	Toast notification for referral actions

Modals:

Component	File	Purpose
ConfirmTransferModal	components/modal/confirm-transfer-modal.tsx	Transfer confirmation dialog
ScratchTicketModal	components/modal/scratch-ticket-modal/scratch-ticket-modal.tsx	Full-screen scratch card reveal
LearnMoreModal	components/modal/learn-more-modal.tsx	Referral program explainer
WaitlistModal	components/modal/waitlist-modal.tsx	Waitlist position display
ConnectGmail	components/modal/connect-gmail.tsx	Gmail integration for contacts
DisconnectGmail	components/modal/disconnect-gmail.tsx	Gmail disconnection flow
SocialMediaLinks	components/modal/social-media-links.tsx	Social sharing options

Google Sign-In:

Component	File	Purpose
GoogleSignIn	components/google-sign-in/google-sign-in.tsx	Google OAuth for contact import (deprecated backend)
ConnectToGoogle	components/connect-to-google/connect-to-google.tsx	Google connection UI

---

6. Business Rules

1. Referral link is a 6-character hex string, cryptographically random, guaranteed unique via recursive retry.
2. Reward distribution uses weighted random: $10 (50%), $25 (25%), $50 (20%), $100 (5%).
3. Signup reward: Every new user gets one scratch card at registration.
4. Referral reward: The referrer gets one scratch card when their invitee registers.
5. Organization info reward: User gets one scratch card for submitting company information.
6. Scratch cards are one-time reveal — once scratched, the EquaCash is added to the user’s or org’s balance.
7. IP rate limiting: Max REGISTRATION_IP_LIMIT (default 20) referral registrations per IP address.
8. Email and domain blacklists prevent abusive registrations.
9. EquaCash transfers require the sender to have a balance >= the transfer amount. Transfer is atomic: deduct, credit, record.
10. Transaction history shows a running balance computed in reverse chronological order.
11. Invitation upsert: Re-inviting the same email updates the existing record rather than creating a duplicate.
12. Invitation statuses progress: invited → registered or joined; bounced emails are tracked separately.
13. Google Contacts import is deprecated — backend throws BadRequest if called.
14. Dual referral paths: Personal referral link (?user={link}) and organization referral link (?organization={orgLink}&user={userLink}).

---

7. Acceptance Criteria

• New user receives a unique 6-character referral link at registration
• User can share referral link and track how many people registered through it
• Signup generates one scratch card for the new user
• Successful referral generates one scratch card for the referrer
• Scratch card reveal animation works and adds correct EquaCash to balance
• Reward amounts follow the weighted distribution ($10/$25/$50/$100)
• User can send email invitations to multiple addresses
• Invitation table shows status (invited, registered, joined, bounced) with daily/monthly stats
• EquaCash transfers work between users and between user/org
• Transfer fails gracefully when balance is insufficient
• Transaction history shows all transfers, earned rewards, and subscription spends with running balance
• IP rate limiting blocks excessive registrations from a single IP
• Email and domain blacklists prevent blocked addresses from registering
• Organization-level referral page shows org-specific rewards and invite tracking

---

8. Risks

Risk	Impact	Mitigation
EquaCash balance stored as numeric on referral record, updated non-atomically in some paths	Race condition on concurrent scratch/transfer	Wrap balance updates in database transactions with row-level locking
IP limit is per-IP, not per-session	Shared IPs (corporate, VPN) may hit limit prematurely	Consider adding session-based rate limiting alongside IP
Google Contacts integration deprecated but UI components remain	Confusing UI if buttons are still visible	Remove or hide Google Contacts UI components
Scratch card reward amounts are deterministic given the random seed	No guaranteed prize pool budget control	Implement budget caps or reward rate adjustment based on total EquaCash issued
Transaction history computed in application code	Performance degradation with many transactions	Add database-level running balance or pagination
updateCash uses getUserByRewardId with user param that may actually be a reward ID	Potential data corruption	Refactor to use explicit parameter naming (noted as TODO in source)