BloxClips docs

Appearance

Historical snapshot archived 2026-09-25. This records an earlier review or plan, not current implementation or live ticket state. For current work, follow root AGENTS.md, the relevant BloxClips skill, and owning repository source/tests. Preserve approved decisions as evidence; verify their present authority before acting.

Terminology Audit ​

Product and identity terms ​

Clipper / creator ​

The UI uses both for a person who creates social videos for campaigns. The persisted identity is WebUser; “clipper” appears more often in payout/fee/copy terminology, while “creator” appears in marketing, stats, and PV tracker language. There is no separate Clipper or Creator model.

Representation: prisma.schema WebUser, frontend auth/profile types, AuthAccount, submission username, and many utility names. Important relationships are submissions, payment methods/payouts, tax form, social accounts, support, notifications, and referrals. Changing identity fields can invalidate tax forms, affect uniqueness/blacklisting, JWT context, and attribution.

Web user / Discord user ​

WebUser.id is the provider-neutral primary identity. Older userId columns often hold a Discord snowflake; newer webUserId columns point to WebUser. AuthAccount is the provider link. These are easily confused and coexist in submissions, payouts, notifications, and payment methods.

Where to start: backend prisma/schema.prisma, src/api/routes/auth.ts, src/api/middleware/auth.ts; frontend app/dashboard/layout.tsx.

Admin / manager / staff ​

Website “admin” means a user allowed by ADMIN_DISCORD_IDS or verified ADMIN_EMAILS and checked by requireAdmin. Discord “manager” is a guild role from GuildConfig.managerRole and bot permission utilities. Support messages call the operator ADMIN; marketing booking copy may say team/staff. These are separate authorization systems.

Campaign and content terms ​

Campaign ​

An operational database campaign pays creators for platform views. It is Campaign in Prisma, REST responses from /api/campaigns, dashboard campaign UI, Discord announcements, submission rules, budget calculation, and tracking.

Important fields: budget, short/long payout, platformFeeRate, caps/minimums, allowed platforms, active, acceptingSubmissions, paused, isDeleted, viewsFrozen, deadline, and tracking duration. It owns many submissions. Creation/publishing sends notifications/Discord content; status/budget changes alter submission eligibility and tracking.

Easily confused: frontend public /campaigns means static case studies in app/campaigns/campaignData.ts. It is not populated from the Campaign model.

Submission / clip / video ​

A Submission is a platform video link entered against one operational campaign. UI copy may call it a video or clip. platform is YouTube/TikTok/Instagram and videoType is short or long. The creator’s original post is not stored as a separate Clip model.

Important fields: campaign/user identifiers, URL/title/preview, initial/current/manual/frozen views, rate/cap overrides, platform metrics, polling state, and legacy/current payout accumulators.

Lifecycle: PENDING → ACCEPTED | DENIED | FLAGGED. Polling starts from submission and continues independently of moderation status until lifecycle expiry or campaign completion, with less frequent polling as the clip ages. Tracking failures can still produce operational flags; views and snapshots inform review, compliance, budget, and future payouts.

View, payable view, paid view, snapshot ​

  • currentViews: latest collected metric.
  • manualViewCount: admin override.
  • frozenViewCount: locked value when campaign budget is exhausted.
  • payableViews: payout-time clamp across available counts/caps.
  • paidViewsTotal: cumulative views already cashed out in the delta flow.
  • ViewSnapshot: metric observation at a timestamp.

These terms are tightly coupled across campaignBudget.ts, calculateSubmissionEarnings.ts, tracking, stats, and payout rescrape. Changing precedence in only one location creates inconsistent spend and earnings displays.

Rate / RPM / payout ​

Campaign payout/payoutLong are string-form rates per 1,000 views. Submission.customRate is a numeric per-1,000 override. UI/admin logging sometimes labels or formats these as “per million,” so verify units at each boundary. “Payout” can mean the campaign rate, an actual Payout transfer workflow, or historical paid amount.

Budget burn / platform fee / clipper fee / rail surcharge ​

  • platformFeeRate accelerates campaign budget consumption; it is not deducted at creator cashout.
  • CLIPPER_CASHOUT_FEE (7% in src/utils/fees.ts) reduces creator payout net.
  • Stripe may add STRIPE_PAYOUT_SURCHARGE_BPS on top.

These are distinct. Campaign spend and creator net are intentionally not the same value.

Payout and tax terms ​

Payout request / payout / payout item ​

Payout is the request/review/send aggregate. PayoutItem is one submission’s delta calculation and admin decision. “Pending payouts” in admin may mean AWAITING_SEND, while older admin code uses PENDING for legacy transfers.

Current lifecycle: REQUESTED → SCRAPING → READY_FOR_REVIEW → AWAITING_SEND → PROCESSING → COMPLETED, with BELOW_THRESHOLD, REJECTED, and FAILED exits. Item lifecycle: PENDING → APPROVED | REJECTED | FLAGGED.

Changing payout status affects creator history, open-payout uniqueness, startup recovery, admin queues, commission accounting, and rail dispatch.

Gross / net / amount / referral bonus ​

Current payout rows separate grossAmount, feeAmount, optional Stripe surcharge, amount (net rail amount), and referralBonusAmount. Legacy rows may have only amount, with different semantics. A payout’s actual dispatch can include the referral bonus in addition to amount.

Payment method / rail ​

Both refer to Stripe, PayPal, or USDT. “Rail” is used by backend dispatch/preflight code; “method” is used in API/UI and preferredPaymentMethod. USDT is hard-locked to TRC-20. PayPal “account” currently centers on email verification despite OAuth-shaped legacy fields.

Tax form / tax-form submission ​

TaxForm is the mutable current rollup. TaxFormSubmission is the immutable signed form, encrypted identifiers, verification response, PDF/hash, and payout snapshot. W-9 is for US persons and normally uses Tax1099 matching; W-8BEN is for non-US persons and has expiry behavior.

Accepted states are verified and manually_verified; other actual states are listed in Data model. Profile changes can invalidate a current form and require recollection.

TIN / FTIN / TIN match ​

TIN covers SSN/EIN/ITIN data on W-9. FTIN is a foreign tax identifier on W-8BEN. Tax1099 “TIN match” verifies W-9 identity. FtinCountryConfig only guides whether/how countries issue FTINs; it is not a verification service.

Attribution and communication terms ​

  • Every user has a canonical eight-character referralCode.
  • ReferralLinkAlias is an admin-managed vanity slug resolving to that owner.
  • Referral is immutable attribution finalized during onboarding.
  • ReferralCommission is a 5% revenue-share ledger entry caused by a qualifying referred-user payout and later swept into the referrer’s payout.

The schema also names FLAT_RATE, but runtime mode selection currently always returns revenue share. Environment names suggesting a switch are not active implementation.

Notification / announcement ​

Announcement is admin-authored global content. UserNotification is a per-user inbox item, potentially linked to an announcement or campaign. Email preferences live in NotificationPreferences; sends are not backed by a queue.

Support conversation / ticket ​

WhopIdentity maps a BloxClips user to a Whop connected-account owner for embedded support chat. Whop owns support feeds and messages. Ticket is a separate Discord channel workflow used by bot-era handlers.

Booking / contact ​

A BookingRequest is a scheduled Google Calendar/Meet lead and BookingAvailabilityConfig controls backend slots. The active frontend booking page instead uses Calendly. A contact attempt is anti-abuse evidence; frontend and backend each contain contact implementations.

Analytics and integration terms ​

PV tracker ​

An admin-only, file-backed performance/video tracker in src/utils/pvTracker.ts. It maintains creator-like records, social accounts, videos, snapshots, sync runs, and insights separately from Prisma WebUser, Submission, and ViewSnapshot. Its whop_username is merely an annotation.

Whop company / clipper count ​

The Whop company record supplies member_count for marketing. It does not establish BloxClips identity or authorization. “Clipper count” is therefore a remote company statistic, not a count query over WebUser.

FeaturedGame is admin-managed public content; Campaign.game describes the target game/site of an operational campaign; public case studies have static game metadata. Similar cards may pull from three different representations.