Ambassador Program & Referral System

Overview

The Ambassador Program lets startups recruit ambassadors who promote the startup via shareable referral links. Ambassadors earn click/conversion tracking. Admins can enable the program to make their startup discoverable on the Ambassador Opportunities page.

---

Features

For Admins (Startup Owners)

• Enable/Disable the ambassador program via Org Settings toggle (ambassadorProgramEnabled)
• View all ambassadors and their stats on the Org Ambassadors page (/org/:orgId/ambassadors)
• When enabled, the startup appears on the public Ambassador Opportunities discovery page

For Users (Ambassadors)

• Discover startups with ambassador programs at /ambassador-opportunities
• Join a startup's ambassador program from /org/:orgId/ambassadors
• Share clean referral links: app.seedstart.space/r/<token>
• Track clicks and conversions on the My Ambassadorships page (/ambassadorships)

---

Architecture

Data Model

Firestore Collections:

• orgs/{orgId}/ambassadors/{ambassadorId} — ambassador records
  • userId, referralCode, referralToken, status, clickCount, conversionCount
• orgs/{orgId}/referralClicks/{clickId} — click tracking
  • referralToken, ambassadorUserId, clickedAt, ip (hashed), userAgent, referer
• orgs/{orgId}/referralConversions/{conversionId} — conversion tracking
  • referralToken, ambassadorUserId, convertedUserId, convertedAt

OrganizationPublic fields:

• ambassadorProgramEnabled?: boolean — controls visibility on discovery page

Referral Link Flow

User clicks: app.seedstart.space/r/<token>
  → Frontend /r/:token route (ReferralRedirectPage)
  → Calls POST /api/v1/referral/click/<token> (records click, returns orgId)
  → Navigates to /org/<orgId>?ref=<token>

The referral link is a clean frontend URL. Click tracking happens via a non-redirecting API call. No server-side redirects or WEB_URL env var needed.

For orgs with webhook integration, the API returns { externalUrl } instead, and the frontend redirects there.

API Endpoints

Method	Path	Auth	Description
POST	/api/v1/referral/click/:token	Public	Record a referral click. Returns { orgId } or { externalUrl }
POST	/api/v1/referral/convert	Required	Record a conversion. Body: { orgId, referralToken?, referralCode? }
POST	/api/v1/ambassadors/become	Required	Join a startup's ambassador program. Body: { orgId }
GET	/api/v1/ambassadors/mine	Required	List current user's ambassadorships

Frontend Routes

Path	Component	Description
/ambassador-opportunities	AmbassadorOpportunitiesPage	Discovery page — browse startups with ambassador programs
/ambassadorships	MyAmbassadorshipsPage	User's active ambassadorships with referral links & stats
/org/:orgId/ambassadors	OrgAmbassadorsPage	Org-specific ambassador page (join, view stats)
/r/:token	ReferralRedirectPage	Public referral redirect — tracks click, navigates to org

Navigation

• Desktop: TopBar "Explore" dropdown contains "Ambassador Opportunities"
• Mobile: Hamburger menu has dedicated "Ambassador Opportunities" entry
• My Ambassadorships page: "Browse Opportunities" button links to discovery page
• Empty state: CTA directs users to browse ambassador opportunities

---

Admin Setup

1. Go to Org Settings (/org/:orgId/settings)
2. In the Member Authentication section, toggle "Enable Ambassador Program"
3. Click Save Settings
4. Your startup now appears on the Ambassador Opportunities page

---

Local Development

Works on localhost out of the box:

• Frontend runs on http://localhost:5173 (in API CORS allowlist)
• VITE_API_URL in web/.env points to the dev Cloud Run API
• Referral links resolve as http://localhost:5173/r/<token>
• Click tracking calls the dev API — CORS is pre-configured

To test the full flow locally:

1. Start the web app: pnpm dev:web
2. Enable ambassador program on a test org via Settings
3. Become an ambassador on that org
4. Copy the referral link from My Ambassadorships
5. Open the link in a browser — should track click and land on the org page

---

Files

Shared

• shared/src/types/organization.ts — ambassadorProgramEnabled field on OrganizationPublic

Backend (functions/)

• functions/src/routes/referral.ts — Click tracking (POST /click/:token) and conversion (POST /convert) endpoints
• functions/src/routes/ambassadors.ts — Ambassador CRUD (become, list, stats)

Frontend (web/)

• web/src/pages/Ambassador/AmbassadorOpportunitiesPage.tsx — Discovery page
• web/src/pages/Ambassador/MyAmbassadorshipsPage.tsx — User's ambassadorships
• web/src/pages/Ambassador/OrgAmbassadorsPage.tsx — Org ambassador management
• web/src/pages/Referral/ReferralRedirectPage.tsx — Clean referral link handler
• web/src/pages/Org/OrgSettingsPage.tsx — Ambassador program toggle
• web/src/components/TopBar/TopBar.tsx — Explore dropdown with Ambassador Opportunities
• web/src/components/HamburgerMenu/HamburgerMenu.tsx — Mobile nav entry
• web/src/routes/routes.tsx — Route definitions