Partner Program Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Partner Program is a low-cost customer acquisition (low-CAC) referral system within Comply-Quick. It allows users to become partners, generate unique referral links, and earn a recurring 30% commission on every subscription payment made by customers they refer. The system utilizes a first-touch attribution model and manages payouts through Stripe Connect.
Sources: supabase/migrations/0012_partner_program.sql:1-10, src/lib/partners/service.ts:1-10
System Architecture
The integration consists of a React-based frontend dashboard, a server-side service layer for business logic, and a PostgreSQL database schema managed via Supabase. Payouts are handled via the Stripe Connect Express model, similar to the project's marketplace creator system.
Core Components
| Component | Responsibility |
|---|---|
| PartnerView | Client-side React component for displaying stats, referral links, and commission history. |
| Partner Service | Server-side logic for generating referral codes, attaching referrals, and recording commissions. |
| Database Schema | Three primary tables: partners, partner_referrals, and partner_commissions. |
| Stripe Connect | Third-party integration for managing partner identities and processing payouts. |
Sources: src/app/dashboard/partners/PartnerView.tsx:20-25, src/lib/partners/service.ts:15-30, supabase/migrations/0012_partner_program.sql:15-55
Data Model
The database schema is designed to ensure idempotency during webhook processing and maintain strict attribution.
The ER diagram shows the relationships between partners, their attributed referrals, and the resulting commission ledger entries.
Sources: supabase/migrations/0012_partner_program.sql:24-60
Referral Workflow
The referral process follows a "first-touch" strategy. When a user visits the site via a referral link (e.g., /?ref=code), the system attempts to associate their account with the corresponding partner.
Attribution Logic
- Code Validation: The system verifies if the
referral_codeexists in thepartnerstable. - Self-Referral Check: Users are prevented from referring themselves.
- First-Touch Protection: The
partner_referralstable uses a unique constraint onreferred_user_id. If the user is already associated with a partner, the new referral attempt is ignored.
Sources: src/lib/partners/service.ts:102-120, supabase/migrations/0012_partner_program.sql:41-45
Commission Accrual Sequence
The sequence diagram illustrates how payments triggered by Stripe are converted into partner commissions while ensuring idempotency.
Sources: src/lib/partners/service.ts:133-155, supabase/migrations/0012_partner_program.sql:53-55
Partner Dashboard and UI
The PartnerView component provides the user interface for the program. It calculates earnings in real-time based on the commission ledger.
Key Metrics
- Total Earned: Lifetime commission (accrued + paid).
- Pending Payout: Commissions marked as
accruedbut not yet transferred. - Paid Out: Commissions successfully transferred via Stripe Connect.
- Referred Customers: A count of unique users successfully attributed via first-touch.
Sources: src/app/dashboard/partners/PartnerView.tsx:103-108, src/lib/partners/service.ts:187-200
API Integration
The frontend interacts with several internal endpoints:
POST /api/partners/join: Creates a new partner record and generates a referral code.POST /api/partners/connect: Initiates the Stripe Connect onboarding flow.
Sources: src/app/dashboard/partners/PartnerView.tsx:40-60
Security and Permissions
Row Level Security (RLS) is used to protect partner data.
- Partners: Users can only read and update their own partner profile.
- Referrals/Commissions: Partners have read-only access to their own ledger.
- System Writes: Insertions into referral and commission tables are restricted to the
service-roleclient to prevent forgery.
Sources: supabase/migrations/0012_partner_program.sql:71-100
Summary
The Partner Program Integration provides a robust, automated referral loop. By leveraging Stripe Connect for payouts and implementing idempotent database operations for commission tracking, Comply-Quick ensures that partners are accurately credited and paid for customer referrals without significant manual overhead.