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.

Request and Data Flows

1. Login and onboarding

sequenceDiagram
    actor C as Creator
    participant UI as Next login/onboarding
    participant Auth as Express auth/onboarding
    participant OAuth as Discord/Google
    participant DB as PostgreSQL
    C->>UI: choose provider
    UI->>Auth: begin OAuth
    Auth->>OAuth: authorize/exchange/profile
    Auth->>DB: upsert AuthAccount and WebUser
    Auth-->>UI: JWT cookie + redirect
    UI->>Auth: GET onboarding status
    C->>UI: profile/country/referral data
    UI->>Auth: POST onboarding
    Auth->>DB: validate uniqueness, finalize referral, set completedAt
    Auth-->>UI: completed user

After onboarding the frontend directs toward /dashboard; the current dashboard layout then additionally requires admin, which is an unresolved behavior mismatch.

2. Browse an operational campaign

Creator opens /dashboard/campaigns
→ page fetches GET /api/campaigns?status=active
→ campaigns router queries non-deleted campaigns/submissions
→ budget/earnings utilities compute spent/progress and canSubmit
→ JSON campaign cards
→ frontend filters/displays actions

This is unrelated to public /campaigns, whose case-study records never enter the backend.

3. Submit and prove account ownership

sequenceDiagram
    actor C as Creator
    participant M as SubmitVideoModal
    participant S as POST /api/submissions
    participant X as YouTube / Apify
    participant V as Verification routes
    participant D as PostgreSQL
    C->>M: choose campaign and paste URL
    M->>S: campaignId + videoLink
    S->>X: fetch source metadata/author
    S->>D: find LinkedSocialAccount
    alt already linked
      S->>D: create PENDING Submission + ViewSnapshot
      S-->>M: submission
    else ownership missing
      S-->>M: 412 verification-required metadata
      M->>V: start challenge
      V->>D: upsert PendingVerification
      C->>X: put code in profile bio
      M->>V: check challenge
      V->>X: scrape bio
      V->>D: create LinkedSocialAccount; delete challenge
      M->>S: retry original submission
    end

The modal can submit up to four URLs but does so sequentially, preserving individual outcomes.

4. Review and track a submission

Admin opens submission review UI
→ admin API lists PENDING/filtered submissions
→ admin changes status
→ admin router enforces requireAdmin
→ ACCEPTED sets acceptedAt/nextPollAt and evaluates campaign budget
→ notification/audit and optional Discord sync
→ intended tracking scheduler selects due ACCEPTED rows
→ source metrics update Submission + ViewSnapshot + budget state

The last two arrows depend on startScheduler, which has no caller in visible entrypoints. Manual admin view edits and payout-time rescrapes are separate mutation paths.

5. Creator payout

sequenceDiagram
    actor C as Creator
    participant UI as Payout UI
    participant API as Payout routes/services
    participant DB as PostgreSQL
    participant Social as YouTube/Apify
    participant A as Admin UI/API
    participant Rail as Stripe/PayPal/NowPayments
    UI->>API: GET balance/method/tax eligibility
    API->>DB: calculate unpaid deltas and gates
    C->>UI: request payout
    UI->>API: POST request
    API->>DB: create REQUESTED
    API->>Social: async rescrape
    API->>DB: PayoutItems + READY_FOR_REVIEW
    A->>API: decide items and approve
    API->>DB: cumulative paid accounting + AWAITING_SEND
    A->>API: send with TOTP
    API->>Rail: dispatch
    API->>DB: COMPLETED or FAILED/reversal
    UI->>API: refetch status

Tax eligibility is based on projected taxable gross and a verified form when the threshold applies. Payment method validity is rechecked before dispatch. Referral commissions caused by a referred creator’s completed payout are accrued idempotently, while pending commissions belonging to the recipient can be swept into their transfer.

6. Support chat

An authenticated BloxClips user is automatically mapped to one Whop connected-account owner in WhopIdentity. A clipper creates/resolves only their own global Whop support feed. Authorized staff list BloxClips support feeds and select one. Both render the selected feed_... with Whop ChatElement; Whop owns messages, media, real-time updates, and composer behavior.

7. Contact and booking leads

Active contact flow:

/contact BookCallForm
→ Next POST /api/contact
→ Cloudflare Turnstile verification
→ Resend email
→ success/error UI

Parallel Express contact logic stores hashed ContactAttempt records and applies different abuse checks, but the active component does not call it.

Active booking flow:

/book-call
→ embedded Calendly scheduler
→ Calendly-owned outcome

The backend also supports availability → Google Calendar/Meet event → BookingRequest → Resend/Twilio alerts, and admin booking management; its frontend BookCallScheduler caller appears unused.