Build a Complete Affiliate System (90-Day Cookie, Monthly Payouts)

Scan my entire Base44 app before making changes.

I want you to add a complete affiliate system to this existing app. Do not rebuild the app. Do not break existing user flows, auth, dashboards, checkout, subscriptions, payments, or admin areas. First understand the current app structure, routes, entities, user roles, backend functions, payment flow, and existing admin dashboard.

After scanning, build a fully functioning affiliate system with: Affiliate signup, USA and Canada only eligibility, 90-day cookie tracking, affiliate link/URL tracking, referral attribution, conversion tracking, affiliate dashboard, admin affiliate dashboard, monthly payout tracking, end-of-month payout calculations, fraud-prevention checks, admin approval workflow, secure permissions, and a clean UI that matches the existing app.

CORE GOAL: Create a complete affiliate program where approved affiliates can share tracking links, receive credit for referred users/customers, view clicks, conversions, commissions, and payout status, while admins review affiliates, monitor performance, approve payouts, and manage the program.

IMPORTANT RULES:
1. Scan the existing app first.
2. Reuse existing design patterns, components, and admin structure.
3. Do not duplicate existing user/account/customer/payment entities unless necessary.
4. Do not expose affiliate earnings or private data to other users.
5. Affiliates cannot edit their own commission amounts, payout records, conversion records, or approval status.
6. All sensitive actions must happen through backend functions.
7. Admin-only data must be protected by role checks.
8. Affiliate tracking must work even if the user is not logged in.
9. Referral cookies last 90 days.
10. Only US and Canada users can apply right now.

BUILD IN PHASES:
Phase 1 — App Scan: report existing roles, auth, admin routes, checkout/payment/subscription flow, user/customer entities, dashboards, backend functions, permissions, and the best place to add affiliate signup, dashboard, and admin management.

Phase 2 — Entities (create if missing): Affiliate, AffiliateClick, AffiliateReferral, AffiliateConversion, AffiliatePayout, AffiliateSettings. Affiliate code unique; status defaults to pending; only admins approve/reject/suspend/modify commission; affiliates edit safe fields only.

Phase 3 — Affiliate Signup (/affiliate, /affiliate/signup): program overview, commission + 90-day cookie + end-of-month payout explanation, US/Canada notice, application form (name, email, country dropdown US/Canada only, state/province, phone, website, social links, audience, promotion methods, payout method/email, terms checkbox). On submit: create Affiliate with pending status, generate unique code, confirmation message, notify admin.

Phase 4 — Links & Tracking: on ?ref=CODE validate + confirm approved, create/update visitor ID, store 90-day cookie, create AffiliateClick, create/update AffiliateReferral, preserve UTMs, continue navigation. Last-click attribution; do not overwrite a converted referral; do not attribute suspended/rejected affiliates or expired cookies.

Phase 5 — Conversion Tracking: on signup/purchase/subscription/upgrade check cookie, validate affiliate, find/create referral, create conversion, calculate commission on the backend (percentage = amount × rate; fixed = flat), mark pending/approved per settings, update totals, link to order/customer/subscription. Self-referral → disqualified with reason.

Phase 6 — Affiliate Dashboard (/affiliate/dashboard): pending/rejected/suspended states; approved overview cards (clicks, unique visitors, conversions, pending/approved/paid commissions, lifetime earnings, next payout date, current month), referral link with copy + UTM builder, performance charts, conversion + payout tables, editable safe profile fields only.

Phase 7 — Admin Dashboard (/admin/affiliates): program overview cards, affiliate management table with actions (view, approve, reject, suspend, reactivate, edit commission, add notes), and affiliate detail page with full history, fraud flags, and commission settings.

Phase 8 — Monthly Payouts (/admin/affiliates/payouts): backend functions generateMonthlyAffiliatePayouts, markAffiliatePayoutPaid, holdAffiliatePayout, recalculateAffiliateTotals. Payouts calculated end of month from approved unpaid conversions; mark conversions paid only when payout is paid.

Phase 9 — Admin Settings (/admin/affiliates/settings): enable program, default commission type/rate, cookie days (90), minimum payout, auto-approve toggles, allowed countries, self-referral allowed, terms URL, support email. Admin-only.

Phase 10 — Security: strict per-user and admin permission checks; backend functions verify admin role; never rely only on frontend route hiding.

Phase 11 — Fraud Prevention: flag self-referrals, matching emails, high clicks/no conversions, duplicate IP hashes, multiple accounts on one cookie. Mark for admin review, do not auto-delete.

Phase 12 — UI: cards, tables, status badges, modals, copy buttons, date/month filters, search, status filters, empty/loading/error states, responsive layouts.

Phase 13 — Required Backend Functions: trackAffiliateClick, registerAffiliateConversion, generateMonthlyAffiliatePayouts, markAffiliatePayoutPaid, holdAffiliatePayout, approveAffiliate, rejectAffiliate, suspendAffiliate, updateAffiliateSettings, recalculateAffiliateTotals — all admin actions verify permissions.

Phase 14 — Payment Flow Integration: hook conversion tracking into the existing checkout/subscription/order success event. Do not create fake payment logic; if none exists, leave clear integration hooks.

Phase 15 — QA: test valid/invalid/suspended links, cookie save + 90-day expiry, signup/purchase conversions, commission accuracy, dashboard access control, admin approve/reject/suspend, payout generation/mark paid, self-referral, US/Canada restriction, mobile, route protection, backend permission checks.

Phase 16 — Final Output: summarize new pages, entities, functions, modified files, how tracking/conversions/payouts/approvals work, assumptions, and remaining setup. Do not stop after planning — build the full system.