BloxClips docs

Appearance

Architecture overview: the system in one page ​

Guide · last verified 2026-09-27 against the three codebases. Anything historical (Stripe/PayPal/NowPayments rails, PV Tracker, SQLite-era guides) lives in the archive and is not current.

The shape of the system ​

text
Creators / staff / sponsors
        │
        ▼
BloxClips-frontend (Next.js + Whop embed, origin/dev)
  auth shell, RBAC, staff inbox, campaign UI
        │  API calls (backend is the authorization authority)
        ▼
Bloxclips-backend (API + Prisma, origin/dev)
  auth · campaigns · funding ledger · payouts · scheduling
        │  enqueues ScrapeJobs           │  Whop-only money
        ▼                               ▼
metric-scraper (Crawlee worker,    Whop business balance
  origin/main)                       in / creator credits out
  platform extraction
        │
        ▼
submission_metrics (business observations)

Who owns what ​

  • Frontend owns presentation, Whop-embedded UI, and client access states. It never authorizes — every permission decision is rechecked by the backend.
  • Backend owns auth authority, the data model (Prisma), the funding ledger, payout journaling, and scheduling. It decides when and why to scrape.
  • Scraper owns how scraping executes: platform implementation, Crawlee concurrency, retries, sessions, proxies, statistics. Retries are telemetry (scrape_attempts), not extra scheduled polls; observed metrics are business data (submission_metrics).

Money in one paragraph ​

Campaign funding is Whop-only and flows CampaignInvoice → CampaignFundingReceipt → CampaignFundingAllocation → exactly-once bridge → CampaignFinanceAccount/payout journal. Invoice fee policy is explicit (ABSORB / CHARGE_BUYER). Client budgets deplete by CPM; creators earn by RPM with versioned rates pinned to earning periods. Creator payouts credit Whop balances from the BloxClips business balance. Pending work at budget exhaustion and paused views are not paid.

What this system is not (anymore) ​

  • Not Stripe/PayPal/NowPayments — those diagrams in the archive are history.
  • Not PV Tracker for submissions — the tracker is retired; submission metrics come from the scraper contract only.
  • Not one big deploy — three repos, three gates, dev/dev/main. Changes land per repo and link across PRs.

For process and branch rules, see the project map and GitHub conventions.