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.

Historical snapshot — superseded for agent navigation (2026-09-25). This document can describe retired architecture, old database/payment models, or primary-checkout paths. Do not use it as current implementation policy. Start with the project router, resolve the owning Treehouse lease, then load its repository skill/source index. The original text below is retained for historical reasoning.

Backend Deep Dive ​

Startup and composition ​

  • src/index.ts is the Discord bot entrypoint. It initializes Discord.js, loads only the enabled command names (announce, embed, panel, privacy, setup), registers handlers, sends welcome DMs, and logs in.
  • src/api/server.ts is the API entrypoint. It creates a smaller Discord client for API-side publishing, calls startApiServer(), and asks resumeStuckPayouts() to recover REQUESTED/SCRAPING payouts.
  • src/api/index.ts builds Express, applies cross-cutting middleware, mounts all routers, starts HTTP or certificate-backed HTTPS, then starts the payment and PV tracker schedulers.
  • src/scheduler.ts defines campaign-expiry and accepted-submission tracking timers, but neither TypeScript entrypoint calls startScheduler. This is a material startup gap, not an inferred framework behavior.

Cross-cutting behavior ​

src/api/index.ts owns Helmet, CORS, body limits, cookie parsing, referral/device cookies, rate limiting, health/Roblox routes, and router mounting. src/api/middleware/auth.ts validates the JWT cookie and revocation version and checks bans. adminAuth.ts enforces admin allowlists. totpAuth.ts adds a second factor to sensitive payment/tax actions. Errors are largely handled inside routers and logged with console; there is no centralized observability SDK or uniform application error type.

Campaigns and submissions ​

Purpose. Configure paid content campaigns, accept creator links, moderate them, track platform metrics, and cap spend.

  • Primary models: Campaign, Submission, ViewSnapshot, LinkedSocialAccount.
  • Main routes: src/api/routes/campaigns.ts, submissions.ts, and campaign/submission sections in admin.ts.
  • Main services: src/utils/calculateSubmissionEarnings.ts, campaignBudget.ts, tracking/runTrackingTick.ts, social scrapers, and discordPublish.ts.
  • External dependencies: YouTube Data API, Apify TikTok/Instagram actors, Discord announcement messages.
  • Frontend consumers: app/dashboard/campaigns, submit, history, admin campaign detail/manage, and admin submissions.

Submission creation scrapes the source, identifies platform/video type, checks campaign/platform constraints, and requires ownership through LinkedSocialAccount. A missing proof produces the verification workflow rather than silently attaching the account. Admin acceptance records acceptedAt and tracking state and can freeze/close a campaign based on budget. Accepted-view polling should update metrics and snapshots until the campaign tracking duration, but its scheduler is currently unwired.

Important invariant: payable views may be constrained by manual views, frozen views, custom/campaign caps, and previously paid views. Rate can be submission-custom or campaign short/long rate. Fee/budget burn is not merely the displayed clipper payout.

Creator identity, onboarding, and moderation ​

Purpose. Establish provider-neutral website identities while retaining Discord-era identifiers.

  • Models: WebUser, AuthAccount, Ban, IdentityBlacklist, verification tables.
  • Routes: auth.ts, onboarding.ts, users.ts, verifications.ts, gdpr.ts.
  • Services: profile normalization in src/api/utils/profile.ts, moderation helpers, token encryption, referral attribution.

OAuth accounts map to WebUser. Google’s verified email may merge into an existing verified-email identity. Onboarding collects handle/name/phone/country/experience, finalizes referral attribution, and sets onboardingCompletedAt. Bans are checked on authenticated requests and blacklisted identifiers can block future identity reuse.

Payouts and payment methods ​

Purpose. Let creators request delta payouts, allow admins to review per-submission evidence, and explicitly send approved funds.

  • Models: Payout, PayoutItem, StripeAccount, PayPalAccount, UsdtPayoutMethod, PaymentSystemConfig.
  • Routes: payouts.ts, adminPayoutReview.ts, adminPaypal.ts, stripe.ts, paypal.ts, usdt.ts, and payment webhook routers.
  • Services: src/utils/payouts/processRequest.ts, rescrape.ts, payments/preflight.ts, rails/dispatcher.ts, fee and rail guards.
  • External dependencies: Stripe Connect, PayPal Payouts, NowPayments.

A creator request creates a durable payout row, then an in-process worker rescrapes eligible submissions and creates PayoutItem deltas. Admin decisions lead to AWAITING_SEND; an explicit TOTP-protected send dispatches the chosen rail. Startup resumes payout rows stranded before review, but the worker itself is not a durable queue.

Legacy admin-initiated payout endpoints and Submission.paidOut remain alongside this current flow. Changing payout logic requires tracing both models and deciding which consumers are still supported.

Tax compliance ​

Purpose. Collect W-9/W-8BEN forms, verify TINs, retain immutable submissions/PDFs, gate payouts, and export year-end data.

  • Models: TaxForm, TaxFormSubmission, TaxFormStateTransition, FtinCountryConfig; payout rows snapshot the applicable submission.
  • Routes: taxForms.ts, adminTaxForms.ts, adminFtinConfig.ts, adminYearEnd.ts.
  • Services: src/utils/tax/, tax1099/, storage/, and export/yearEnd1099.ts.
  • External dependencies: Tax1099, R2/local storage, Resend.

Sensitive identifiers are encrypted, only last-four display fields are retained in plain form, generated PDFs are hashed, and an in-process job checks tampering. User profile changes can invalidate/recollect a current form. W-8BEN expiry reminders and TIN match draining also run in the API scheduler.

Referrals and affiliates ​

Purpose. Attribute a referred user once at onboarding and accrue a percentage of qualifying referred-user payouts.

  • Models: Referral, ReferralLinkAlias, ReferralCommission, plus WebUser.referralCode/referredById.
  • Routes: top-level /r/:code, referrals.ts, admin affiliate routes in admin.ts.
  • Services: src/utils/referrals/{attribution,policy,accrual,sweep,balance,...}.ts.

The short-link rewrite lets the backend set first-party referral cookies on the frontend origin. Attribution records device/fingerprint/IP evidence and is immutable after onboarding. Commission creation is idempotent through unique sourcePayoutId; pending commissions are swept into a referrer’s later payout.

Although the schema supports FLAT_RATE and source comments mention runtime flags, currentReferralProgramMode() currently returns REVENUE_SHARE and the pause helper returns false unconditionally.

Notifications and support ​

  • Announcement, UserNotification, and NotificationPreferences back in-app/email notifications.
  • WhopIdentity maps a WebUser to a Whop connected-account owner. supportChat.ts uses Whop Support Channels and account-scoped tokens; Whop owns messages, realtime, and support-feed state.
  • Discord tickets (Ticket) are a distinct older support concept owned by bot handlers.
  • AdminAuditLog is legacy admin-action logging; AuditLog is the newer payment/tax/compliance ledger.

Marketing operations and ancillary domains ​

  • FeaturedGame and FeaturedService are backend-managed public content, separate from hardcoded frontend case studies.
  • BookingRequest and BookingAvailabilityConfig support Google Calendar/Meet booking and admin management, although the current public page embeds Calendly instead.
  • Contact handling verifies Turnstile, stores hashed attempt evidence, throttles abuse, and sends via Resend. The active public frontend instead uses a parallel Next route.
  • ExternalLeaderboardPayment imports off-platform payment history into leaderboard/stat views.
  • The PV tracker in src/utils/pvTracker.ts is an admin analytics subsystem backed by assets/pv-tracker-state.json, not Prisma.

Route organization ​

There is no API version prefix. Public routes include health, authentication initiation/callbacks, campaigns reads, public games/services, contact/booking, Roblox proxies, Whop count, referral redirects, webhooks, and signed local storage. Most creator routes use requireAuth; all admin router families use both requireAuth and requireAdmin. Consult frontend/backend integration for consumer mapping.