Universal Affiliate Foundation (Silent Mode)
Goal
Put the invisible groundwork in place for a built-in affiliate program. Every user gets a unique referral identity and any incoming traffic with that code is tracked.
👉 No payouts yet. No user-facing dashboard. No banners. Just schema + tracking so we can flip it on later without migrations.
Scope (Phase 1: Tracking only)
- Auto-Affiliate for All Users
Every new user gets a referralCode (aff_xxxxxx) on account creation.
Add referredByUserId to User (nullable).
- Link Handling
Accept ?aff=xxxxxx on any entry URL.
Store cookie (30 days) + localStorage backup.
On signup, set referredByUserId and record an attribution row.
- Tracking Tables (silent)
ReferralClick { id, refCode, ts, ipHash, uaHash, landingPath?, metaJSON? }
ReferralAttribution { id, referredUserId, referrerUserId, at: Date, source: 'link'|'invite'|'share', metaJSON? }
Always org-scoped (multi-org safe).
No duplicate attribution if already referred.
- Exports / Shared Links (future-ready)
Add hook so any public/shared export can append an affiliate link parameter automatically.
Keep disabled until we decide to turn it on.
- Silent Admin View
Only dev/admin can query referral counts.
No user-facing affiliate dashboard yet.
Non-Goals (for now)
❌ No payouts (crypto or fiat).
❌ No affiliate dashboards, reminders, or notifications.
❌ No commission logic or thresholds.
❌ No Mudul token integration.
Future Phase 2 (when flipped on)
Affiliate dashboard (clicks, signups, earnings).
Export-injected links (PDF, public pages).
Payout logic (BTC/ETH/USDC, configurable % + thresholds).
Notifications/reminders for affiliates.
Admin panel for commission management.
Acceptance Criteria (Phase 1)
-
Every user has a referralCode persisted in DB.
-
Visiting with ?aff=code stores attribution and is linked on signup.
-
Attribution records saved in DB (click + signup events).
-
Self-referrals blocked (same user/IP/email).
-
No UI changes visible to end users.
Tasks
[ ] Add referralCode + referredByUserId to User model.
[ ] Generate code on user creation (backfill existing users).
[ ] Implement /ref/click endpoint with rate limits + bot filtering.
[ ] Parse ?aff= on frontend; set cookie + call /ref/click.
[ ] Link referral on signup; write ReferralAttribution.
[ ] Add admin-only query/logs for testing.
[ ] Tests: self-ref prevention, window expiry, last-click wins, IDOR prevention.
👉 This way, the rails are there: codes, attribution, tables, silent logging.
When you’re ready to “flip the switch,” you only build the payouts + UI layer on top.
Universal Affiliate Foundation (Silent Mode)
Goal
Put the invisible groundwork in place for a built-in affiliate program. Every user gets a unique referral identity and any incoming traffic with that code is tracked.
👉 No payouts yet. No user-facing dashboard. No banners. Just schema + tracking so we can flip it on later without migrations.
Scope (Phase 1: Tracking only)
Every new user gets a referralCode (aff_xxxxxx) on account creation.
Add referredByUserId to User (nullable).
Accept ?aff=xxxxxx on any entry URL.
Store cookie (30 days) + localStorage backup.
On signup, set referredByUserId and record an attribution row.
ReferralClick { id, refCode, ts, ipHash, uaHash, landingPath?, metaJSON? }
ReferralAttribution { id, referredUserId, referrerUserId, at: Date, source: 'link'|'invite'|'share', metaJSON? }
Always org-scoped (multi-org safe).
No duplicate attribution if already referred.
Add hook so any public/shared export can append an affiliate link parameter automatically.
Keep disabled until we decide to turn it on.
Only dev/admin can query referral counts.
No user-facing affiliate dashboard yet.
Non-Goals (for now)
❌ No payouts (crypto or fiat).
❌ No affiliate dashboards, reminders, or notifications.
❌ No commission logic or thresholds.
❌ No Mudul token integration.
Future Phase 2 (when flipped on)
Affiliate dashboard (clicks, signups, earnings).
Export-injected links (PDF, public pages).
Payout logic (BTC/ETH/USDC, configurable % + thresholds).
Notifications/reminders for affiliates.
Admin panel for commission management.
Acceptance Criteria (Phase 1)
Every user has a referralCode persisted in DB.
Visiting with ?aff=code stores attribution and is linked on signup.
Attribution records saved in DB (click + signup events).
Self-referrals blocked (same user/IP/email).
No UI changes visible to end users.
Tasks
[ ] Add referralCode + referredByUserId to User model.
[ ] Generate code on user creation (backfill existing users).
[ ] Implement /ref/click endpoint with rate limits + bot filtering.
[ ] Parse ?aff= on frontend; set cookie + call /ref/click.
[ ] Link referral on signup; write ReferralAttribution.
[ ] Add admin-only query/logs for testing.
[ ] Tests: self-ref prevention, window expiry, last-click wins, IDOR prevention.
👉 This way, the rails are there: codes, attribution, tables, silent logging.
When you’re ready to “flip the switch,” you only build the payouts + UI layer on top.