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.

MVP Readiness Report ​

The application has useful product foundations, and the latest merges materially improve authentication, staff boundaries, and consistent scraper routing. The private MVP still cannot safely run today. The missing center is financial: campaigns are launched from editable display-string budgets without verified Whop funding, finance authority is not expressed as customizable permissions, earnings are recomputed rather than journaled, and creator transfers use legacy rails rather than Whop.

Campaign Lifecycle ​

Status: PARTIAL
Priority: P0
Confidence: HIGH

Already working ​

Draft creation, one-time launch, pause/resume, soft end/delete, deadline processing, and campaign-specific group archival exist.

Missing / blocker ​

Lifecycle actions use requireAdmin, not finance permissions. Launch does not require verified funding. The generic update route can change budget, rate, active, and paused, including after launch, without an explicit transition policy.

Evidence ​

  • Bloxclips-backend/src/api/routes/admin.ts: campaign create/launch/update/delete routes
  • Bloxclips-backend/src/utils/clipperGroups/campaignLifecycle.ts
  • BloxClips-frontend/features/admin/campaign-management/hooks/useAdminCampaignManagement.ts

Proposed work ​

Campaign Funding & Whop Financial Integration ​

Status: MISSING
Priority: P0
Confidence: HIGH

Already working ​

The Whop SDK, signed webhook helper, company identity mapping, and a raw-body Whop webhook mount exist for Support Chat.

Missing / blocker ​

No client, invoice, invoice-payment, funding, or funding-event model exists. There is no invoice creation UI/API, invoice.paid handler, reconciliation, currency-safe amount representation, or funding-to-launch gate. The current Whop webhook handles chat activity only.

Evidence ​

Proposed work ​

Creator Access ​

Status: PARTIAL
Priority: P0
Confidence: HIGH

Already working ​

Google, Discord, and Whop authentication, stable WebUser identity, onboarding, ban enforcement, campaign pages, and submission ownership checks work in code. Whop OAuth uses backend-owned PKCE/OIDC validation, encrypted provider tokens, verified-email linking rules, and logout/revoke handling. The dashboard outer layout permits clippers.

Missing / blocker ​

Every authenticated creator can still list every launched campaign and submit if campaign state permits; no private-cohort or campaign grant is enforced.

Evidence ​

  • Bloxclips-backend/src/api/routes/auth.ts
  • Bloxclips-backend/src/utils/whopOAuth.ts
  • Bloxclips-backend/src/utils/whopOAuth.test.ts
  • Bloxclips-backend/src/api/routes/campaigns.ts
  • Bloxclips-backend/src/api/routes/submissions.ts
  • BloxClips-frontend/surfaces/content-rewards/screens/auth/components/LoginCard.tsx

Proposed work ​

Submissions ​

Status: MOSTLY COMPLETE
Priority: P1
Confidence: HIGH

Already working ​

The frontend-to-backend-to-database path supports YouTube, TikTok, and Instagram Reels; validates lifecycle/platform/type; verifies creator-account ownership; stores initial metrics; and has a database unique key on campaign/platform/video ID.

Missing ​

Raw-URL duplicates are checked non-canonically before scraping, while canonical uniqueness is authoritative afterward. Resubmission policy after denial is implicit (the unique key blocks it). Initial snapshot creation is best-effort rather than atomic. Private campaign access is absent.

Evidence ​

  • BloxClips-frontend/features/submissions/components/SubmitVideoModal.tsx
  • Bloxclips-backend/src/api/routes/submissions.ts
  • Bloxclips-backend/prisma/schema.prisma: Submission

Proposed work ​

  • Access and moderation issues cover the MVP boundary; resubmission wording is an owner/product follow-up unless required.

Submission Review ​

Status: PARTIAL
Priority: P0
Confidence: HIGH

Already working ​

The cross-campaign queue has server pagination, campaign/status filters, FIFO queue order, preview metrics, lazy snapshot graphs, approve/deny/flag controls, and audit writes. Whop-confirmed STAFF users can now access the review/user surfaces, while role hierarchy checks prevent them from moderating staff or administrators.

Missing / blocker ​

Moderation is a non-atomic read/check/update sequence: concurrent reviewers can both act, repeated acceptance can duplicate side effects, and budget checks race. Reviewer/reason/history are stored only in hard-to-query audit JSON and are not returned in review rows. Views/earnings sorts load and sort the entire result set in application memory; review has no server search.

Evidence ​

  • Bloxclips-backend/src/api/routes/admin.ts: review list and status update
  • BloxClips-frontend/features/admin/submissions/hooks/useAdminSubmissions.ts

Proposed work ​

Continuous Tracking ​

Status: BROKEN
Priority: P0
Confidence: HIGH

Already working ​

nextPollAt, durable ScrapeJob, partial-unique coalescing, worker leases/reclaim, CAS completion, three-platform scrapers, result validation, transactional apply, snapshots, and retry/backoff exist. The API starts scheduler and reconciliation loops. The merged cutover removes the separate YouTube execution path: TikTok, Instagram, and YouTube recurring metrics now all enqueue durable jobs for the scraper worker.

Missing / blocker ​

dueTrackingSubmissionWhere deliberately selects all moderation statuses, which matches the business policy: pending metrics inform approval, while denied/flagged metrics support compliance review. The remaining mismatch is that moderation transitions stop/restart tracking and cadence/expiry use acceptedAt; tracking should instead continue independently of status and expire from submission creation after the campaign-configured duration (default 30 days), or earlier when the campaign finishes. Null schedule and queued-result lifecycle behavior need explicit tests. The separate worker has no committed deployment/process definition; a five-minute lease is not renewed, and retryability differs between worker and backend.

Evidence ​

  • Bloxclips-backend/src/utils/tracking/scrapeJobs.ts
  • Bloxclips-backend/src/utils/tracking/scheduler.ts
  • metric-scraper/src/worker/job-repository.ts
  • metric-scraper/src/worker/worker.ts
  • Bloxclips-backend/src/utils/tracking/scrapeJobs.test.ts

Proposed work ​

Metric History ​

Status: PARTIAL
Priority: P1
Confidence: HIGH

Already working ​

Per-poll views/likes/comments and timestamps are stored; applied jobs cannot create a second snapshot; charts calculate nonnegative daily deltas.

Missing ​

The normalized scraper also returns shares, saves, and follower count, but reconciliation discards them. There is no explicit duplicate observation key, regression/correction provenance, or reliable atomic initial snapshot. Daily maps collapse multiple same-day observations to the last row.

Evidence ​

  • Bloxclips-backend/prisma/schema.prisma: ViewSnapshot
  • Bloxclips-backend/src/utils/viewSnapshots.ts
  • metric-scraper/src/results/normalize.ts

Proposed work ​

CPM, RPM, Earnings & Budget ​

Status: BROKEN
Priority: P0
Confidence: HIGH

Already working ​

Campaign payout acts as RPM, submission customRate overrides it, and platformFeeRate accelerates budget burn. Caps, minimums, frozen views, and delta payout snapshots exist.

Missing / blocker ​

There is no explicit CPM field or immutable rate version. Currency is parsed from strings and money/rates use Float. Earnings and budget are repeatedly recomputed from mutable totals/config, so edits rewrite history. Approval and payout rescrapes have campaign concurrency gaps. calculateMaxTotalViews ignores the burn multiplier. No append-only money-in -> budget -> earning -> paid attribution exists.

Evidence ​

  • Bloxclips-backend/prisma/schema.prisma: Campaign, Submission, Payout, PayoutItem
  • Bloxclips-backend/src/utils/calculateSubmissionEarnings.ts
  • Bloxclips-backend/src/utils/campaignBudget.ts
  • Bloxclips-backend/src/utils/payout.ts

Proposed work ​

Clipper Groups ​

Status: PARTIAL
Priority: P0
Confidence: HIGH

Already working ​

Campaign-specific ownership, create/rename/archive, membership intervals, rejoin history, campaign terminal auto-archive, transactional audit, API, UI, and strong domain tests exist.

Missing / blocker ​

Groups have no RPM field, are not consulted by earnings, allow overlapping memberships without a rate conflict rule, and have no group/member performance analytics.

Evidence ​

  • Bloxclips-backend/prisma/schema.prisma: ClipperGroup, ClipperGroupMembership
  • Bloxclips-backend/src/utils/clipperGroups/domain.ts
  • Bloxclips-backend/src/api/routes/adminClipperGroups.ts
  • BloxClips-frontend/surfaces/content-rewards/screens/admin/clipper-groups/

Proposed work ​

Creator Earnings & Payouts ​

Status: BROKEN
Priority: P0
Confidence: HIGH

Already working ​

Creators can request payout, a delta PayoutItem flow rescrapes and snapshots rates/views, staff can review items, approval and send are separate, TOTP protects send, and creator/admin history UIs exist.

Missing / blocker ​

The only transfer dispatcher targets Stripe, PayPal, or USDT, not Whop. The send claim is a non-conditional read then update; concurrent sends can both dispatch. Stripe has remote idempotency, but PayPal includes Date.now() in its batch key and USDT has no proved idempotency. A timeout returns to retryable without first proving whether money moved. Paid totals are advanced at approval before provider confirmation and later reversed. Payout rows do not own an authoritative earning allocation/operation record.

Evidence ​

  • Bloxclips-backend/src/api/routes/adminPayoutReview.ts
  • Bloxclips-backend/src/utils/rails/dispatcher.ts
  • Bloxclips-backend/src/utils/paypal.ts
  • Bloxclips-backend/src/utils/nowpayments/client.ts
  • Whop Create transfer

Proposed work ​

Roles & Permissions ​

Status: PARTIAL
Priority: P0
Confidence: HIGH

Already working ​

The new STAFF tier is derived only from a Whop OAuth identity with confirmed company-team access. Privileged requests re-read the database role and revalidate Whop membership; confirmed removal demotes staff, outages fail closed with 503, and staff cannot moderate other staff/admins. Backend and frontend restrict STAFF to submission review, creator moderation, snapshots/alerts, and Support Chat; campaign and payout routes remain ADMIN-only. The bounded admin bootstrap still exists.

Missing / blocker ​

Roles are fixed to CLIPPER, Whop-derived STAFF, and ADMIN. The merge correctly prevents ordinary staff from performing campaign and payout actions, but owners still cannot create roles, choose permissions, or add/remove VAs inside BloxClips. There is no distinct finance permission within ADMIN; every admin can still perform every campaign-finance and payout action. Other sensitive capabilities also remain fixed by role rather than configurable.

Evidence ​

  • Bloxclips-backend/prisma/schema.prisma: UserRole, WebUser.role
  • Bloxclips-backend/src/api/middleware/adminAuth.ts
  • Bloxclips-backend/src/utils/staffAccess.ts
  • Bloxclips-backend/src/api/routes/staffBoundaries.test.ts
  • Bloxclips-backend/src/scripts/bootstrapAdminRoles.ts
  • BloxClips-frontend/surfaces/content-rewards/lib/dashboardAccess.ts
  • BloxClips-frontend/surfaces/content-rewards/types/dashboard.ts

Proposed work ​

Audit Logs ​

Status: PARTIAL
Priority: P0
Confidence: HIGH

Already working ​

Legacy AdminAuditLog and generic AuditLog tables exist. Clipper Group mutations write audit facts transactionally; payout/tax code records many events.

Missing / blocker ​

Legacy middleware writes asynchronously after the response and swallows failures, stores broad request/response JSON, lacks before/after state, and may duplicate explicit moderation logs. Financial and RBAC invariants need mandatory same-transaction audit records. No query/API UI exists, but the UI itself is not automatically blocking.

Evidence ​

  • Bloxclips-backend/src/api/middleware/audit.ts
  • Bloxclips-backend/src/utils/audit/log.ts
  • Bloxclips-backend/prisma/schema.prisma: AdminAuditLog, AuditLog

Proposed work ​

Fraud Detection ​

Status: PARTIAL
Priority: P0
Confidence: HIGH

Already working ​

Payout items compute low-like, low-comment, and view-spike badges; staff can flag/reject individual items and see graphs/unavailable-video states.

Missing / blocker ​

Signals exist only at payout request time, are plain comma-separated strings, do not create a durable risk state or hold, and approve-unflagged explicitly ignores auto-badges. There is no override/release reason trail or finality policy.

Evidence ​

  • Bloxclips-backend/src/utils/payouts/badges.ts
  • Bloxclips-backend/src/utils/payouts/processRequest.ts
  • Bloxclips-backend/src/api/routes/adminPayoutReview.ts

Proposed work ​

Analytics ​

Status: BROKEN
Priority: P1
Confidence: HIGH

Already working ​

Creator overview/history, admin overview/chart, campaign detail, platform/status filtering, leaderboards, snapshot graphs, and payout pages exist.

Missing ​

Creator overview uses legacy paidOut and ignores delta paid views; per-campaign creator earnings are added twice in stats.ts; many pages recompute from mutable rates. Required CPM spend, RPM expense, remaining funded budget, paid/owed attribution, group performance, review activity, and durable fraud analytics are incomplete. Client analytics scope is unresolved.

Evidence ​

  • Bloxclips-backend/src/api/routes/stats.ts
  • Bloxclips-backend/src/api/routes/admin.ts
  • BloxClips-frontend/surfaces/content-rewards/screens/overview/
  • BloxClips-frontend/surfaces/content-rewards/screens/admin/

Proposed work ​

Support Chat ​

Status: MOSTLY COMPLETE
Priority: P1
Confidence: MEDIUM

Already working ​

Authenticated identity provisioning, creator channel resolution, account-scoped tokens, staff list/selection authorization, official ChatElement rendering, and signed webhook invalidation are implemented and unit-tested.

Remaining verification ​

Production readiness depends on valid Whop scopes, configured company/webhook IDs, and native staff Support access. No source-code blocker was found.

Evidence ​

  • Bloxclips-backend/src/lib/whopSupportChat.ts
  • Bloxclips-backend/src/api/routes/supportChat.ts
  • BloxClips-frontend/surfaces/content-rewards/screens/support/SupportScreen.tsx
  • Bloxclips-backend/src/lib/whopSupportChat.test.ts