Shared User Stories
Cross-role journeys that span both Individual and Partner users.
1. Store Referral Attribution
A partner shares a referral link; an individual signs up via that link; the system attributes the signup to the partner’s store.Actors
| Actor | Role | What They Do |
|---|---|---|
| Store partner | Partner | Generates and shares referral link from /partners/dashboard Referrals tab |
| Visitor | Anonymous | Clicks referral link, lands on public page |
| New user | Individual (after signup) | Signs up via Clerk, becomes attributed to the store |
End-to-End Flow
Step-by-Step
Partner side (before referral):- Partner signs in at
/partners/sign-in, lands on/partners/dashboard - Opens Referrals tab → sees referral link with
store-{slug}-{hex}code - Copies link via copy button (fires
AFFILIATE_REFERRAL_LINK_COPIEDPostHog event) - Shares on Instagram, email, in-store signage, etc.
- Visitor clicks the shared link → lands on
/?ref=store-chen-well-a1b2 - Landing page JS stores
store-chen-well-a1b2in a 30-day browser cookie - Visitor browses the site (cookie persists across page navigation)
- Visitor clicks “Sign Up” → Clerk sign-up flow
- After Clerk auth completes,
handle_referral_cookie()fires:- Reads
refcookie value - Validates format (
^[a-zA-Z0-9_\-]+$, max 64 chars) - Persists to
User.referral_source(generic tracking) - Detects
store-prefix → callsrecord_referral_signup_sync() - Fires
STORE_REFERRAL_SIGNUPPostHog event
- Reads
- User lands on
/shrine/dashboardas a normal individual user
- Partner refreshes
/partners/dashboard→ Referrals tab - Stats update: total clicks, total signups, conversion rate, recent 30d signups
- Referred users list shows the new signup (anonymized by default)
Referral Code Convention
Store referral codes follow:store-{slug[:12]}-{4hex}
store-prefix discriminates store referrals from generic user referrals- Examples:
store-chen-well-a1b2,store-vitaminwor-f3e4 - Generic (non-store) referral codes have no prefix and use a different attribution path
Data Model
| Table | Key Fields | Role |
|---|---|---|
Store | referral_code, clerk_owner_id, slug | Partner’s store entity |
StoreReferral | store_id, referral_code, status, referred_clerk_user_id | Per-event referral record |
User (Clerk metadata) | referral_source | Generic referral tracking on the individual user |
PostHog Events
| Event | When | Actor |
|---|---|---|
AFFILIATE_REFERRAL_LINK_COPIED | Partner copies link | Partner |
STORE_REFERRAL_LINK_CLICKED | Visitor lands with ?ref=store-* | Visitor |
REFERRAL_SIGNUP_COMPLETED | Any referral signup (generic) | New user |
STORE_REFERRAL_SIGNUP | Store-prefixed referral signup | New user |
Where Stats Are Consumed
| Consumer | How | Status |
|---|---|---|
| Partner portal (Referrals tab) | PartnerPortalState computed vars | Config-gated (on hold per PRD-17) |
| Integration API | GET /api/v1/analytics/summary | Pending (PRD-17 Phase 6) |
| External Shopify app | Consumes Integration API | Future |
Edge Cases
| Scenario | Behavior |
|---|---|
Invalid referral code (!!!) | Cookie not set (sanitized) |
Non-store code (friend-code) | Generic attribution only — no StoreReferral row |
| Expired/cleared cookie | No referral attribution |
| Same user signs up twice with same ref | One StoreReferral row per user |
| Partner without Store entity | Falls back to User.referral_code (generic) |
Related Docs
- Store Referral Module — technical implementation (data model, DB utils, pipeline)
- QA Checklist — manual testing steps
- Partner User Story §3.5 — partner portal referrals tab detail
- Individual User Story §1.2 — referral tracking during signup
2. Protocol Discovery & Adoption
An individual browses the public catalog, adopts a partner’s protocol, and the partner sees adoption metrics.Documented in detail in:
3. Data Sharing Opt-In
An individual opts in to share adherence data with a partner; the partner sees anonymized feedback in the Lounge.Documented in detail in:
- Individual §3.5 — Settings (Data Sharing & Privacy section)
- Partner §3.4 — Lounge Tab