Affiliate Program

IgnitionStack ships a full affiliate program with public signup (/[locale]/affiliates), a logged-in dashboard (/[locale]/affiliates/dashboard), Supabase-backed tracking tables, and GA4 instrumentation. This guide explains how the feature is wired so future changes stay aligned with the architecture playbook.

Page Overview

Data Model

Types live in src/app/types/affiliate.ts and mirror the Supabase schema:

• Affiliate – aggregated counters (totalClicks, pendingPayout, commissionRate, etc.) plus payment props (paypalEmail, pixKey).
• AffiliateClick, AffiliateConversion, AffiliatePayout – used in dashboard tables.
• Input helpers (CreateAffiliateInput, RecordClickInput, RequestPayoutInput, …). Always validate via src/app/lib/validations/affiliate.ts (Zod schemas for commission ranges, payment methods, PIX keys, etc.).

Supabase Policies & Triggers

Key migrations:

1. 66_affiliates.sql – base table with affiliate_code, commission/discount ranges, and counter columns updated by triggers.
2. 67-69_* – click/conversion/payout tables with foreign keys and indexes.
3. 70_affiliate_rls_enable.sql + 71_affiliate_policies.sql – enforce RLS: users read/update their own records, anonymous visitors can insert clicks, only service-role inserts conversions.
4. 72_affiliate_triggers.sql – auto-increment stats, keep updated_at fresh, generate codes, and sync payouts. Remember to update supabase/migrations/roolback/06_drop_tables.sql when adding new functions/triggers.
5. seed/05_seed_affiliates.sql – demo records for local testing (admin user + sample activity).

After editing migrations run:

npm run db:push
npm run db:gen

Tracking & Analytics

GA4 events live in src/app/lib/analytics-events.ts under affiliateEvents:

• pageViewed, signupStarted, signupCompleted
• dashboardViewed, linkCopied, referralClicked
• conversion, payoutRequested, settingsUpdated, couponApplied

Emitters:

• AffiliateLandingAnalytics (client) fires pageViewed.
• AffiliateSignupForm emits signupStarted/completed and logs failures with createLogger.
• AffiliateLinkShare fires linkCopied and wraps clipboard/share errors in structured logs.
• AffiliateTracker (client) validates codes via server action, records clicks, and triggers referralClicked. It’s mounted inside a <Suspense> boundary in the locale layout to satisfy Next.js’ useSearchParams requirements.
• Dashboard components dispatch affiliateEvents.dashboardViewed upon render.

For any new interaction, extend affiliateEvents instead of scattering trackGAEvent calls.

Internationalization

All copy sits under the Affiliates namespace inside src/i18n/messages/{locale}.json with the following structure:

Affiliates: {
  meta, landing, signup, linkShare,
  dashboard: { meta, title, subtitle, stats.*, commissionInfo.*, payout.* },
  conversions, settings
}

When adding new UI, add keys to pt.json (source), then mirror en/es. Use npm run i18n:check before committing.

Extending the Feature

1. New payout methods – add enum entries to paymentMethodSchema, update Supabase column checks, extend repository createPayout, and surface UI in AffiliateSignupForm + translations.
2. Additional dashboard widgets – expand AffiliateRepository.getStats to return aggregated data, update AffiliateDashboard to render cards, and document metrics here.
3. Webhook automation – record conversions via recordAffiliateConversion from Stripe webhooks, then call completeConversion once payment settles.
4. Cookie window – adjust AFFILIATE_COOKIE_DAYS in affiliate-tracker.tsx and ensure marketing copy (landing stats) matches.
5. Admin tooling – use AffiliateRepository.findAll/count from a protected admin route; reuse adminUpdateAffiliateSchema for moderation.

Testing Checklist

• Unit: add tests for new components (src/app/test/unit/components/affiliates/*) or validation logic.
• Integration: cover server actions (e.g., becomeAffiliate, requestPayout) using Vitest’s Supabase mocks.
• E2E: ensure Playwright flows cover /pt/affiliates (signup), /pt/affiliates/dashboard (stats render, copy link), and affiliate referral cookie tracking.

Operations

• Always re-run npm run lint, npm test, and npm run build:app after touching affiliate code—the build uses dynamic = "force-dynamic" pages and will fail if cookies/search params are accessed outside Suspense boundaries.
• Keep AffiliateTracker in sync with any new campaign parameters (e.g., additional query params). Expose helpers in src/app/lib/affiliates/link.ts for utility usage.
• When seeding or modifying demo data, ensure the rollback script drops any added functions/tables so CI can reset cleanly.

Document updates here whenever the affiliate experience changes (pricing, payout logic, dashboard metrics, analytics schema, etc.).