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.

Submission System Documentation

Entry point for understanding how submissions work in BloxClips.

This documentation describes the current implementation as it exists in the codebase today — not what it should do. Every claim references actual source code so developers can verify and navigate to the implementation.

---

What Is a Submission?

A Submission represents a clipper's video entry into a campaign. It links:

• A clipper (WebUser)
• A campaign (Campaign)
• A video URL (YouTube, TikTok, or Instagram)
• Metadata: views, status, earnings, tracking state

Source: prisma/schema.prisma lines 316-382 (Submission model)

---

End-to-End Flow (High Level)

flowchart TD
    A[Clipper clicks Submit] --> B[POST /api/submissions]
    B --> C[Validate URL & Campaign]
    C --> D[Scrape video metadata]
    D --> E{Account verified?}
    E -- No --> F[Return 412: ACCOUNT_VERIFICATION_REQUIRED]
    E -- Yes --> G[Create Submission: PENDING]
    G --> H[Write initial ViewSnapshot]
    H --> I[Admin reviews in dashboard]
    I --> J{Approve/Deny/Flag}
    J -- ACCEPTED --> K[Set acceptedAt, nextPollAt=now]
    J -- DENIED --> L[Status=DENIED]
    J -- FLAGGED --> M[Status=FLAGGED, trackingStopped]
    K --> N[Tracking tick polls every 12h/24h]
    N --> O[Update views, write ViewSnapshot]
    O --> P{Budget exhausted?}
    P -- Yes --> Q[Freeze campaign, clamp views]
    N --> R{30 days elapsed?}
    R -- Yes --> S[trackingStoppedAt]
    K --> T[Clipper requests payout]
    T --> U[Payout rescrape + budget clamp]
    U --> V[Admin reviews payout items]
    V --> W[Approve items → AWAITING_SEND]
    W --> X[Admin clicks Send → COMPLETED]

---

Quick Navigation

Document	Purpose
architecture.md	System components, data flow, major services
lifecycle.md	Submission creation → review → tracking → payout
data-model.md	Prisma models, fields, relationships, indexes
frontend.md	Clipper & admin UI routes, components, hooks
backend.md	API endpoints, validation, side effects
review-flow.md	Staff review actions, status transitions, side effects
metrics-and-tracking.md	View polling, Apify/YouTube API, budget clamping
payouts-and-dependencies.md	How submissions feed payouts, delta math, statuses
permissions-and-actors.md	Who can do what (clipper, admin, system)
integrations.md	Discord, Apify, YouTube Data API, Stripe, PayPal, NowPayments
terminology.md	Canonical terms, ambiguities, cross-system mappings
known-issues.md	Discrepancies, duplicated logic, missing auth, coupling
investigation-notes.md	Confirmed / suspected / unknown / questions for team

---

Key Statuses

Status	Meaning	Who Sets It
PENDING	Submitted, awaiting review	System (on create)
ACCEPTED	Approved, tracking active	Admin (dashboard)
DENIED	Rejected	Admin (dashboard)
FLAGGED	Suspicious, tracking stopped	Admin or auto (3 scrape failures)

Source: prisma/schema.prisma:331 (status default PENDING), src/api/routes/admin.ts:1459-1627 (status update endpoint)

---

Critical Code Locations

Area	File	Lines
Submission creation	src/api/routes/submissions.ts	237-539
Admin status update	src/api/routes/admin.ts	1459-1627
Tracking tick (polling)	src/utils/tracking/runTrackingTick.ts	1-305
Budget clamping	src/utils/campaignBudget.ts	130-225
Payout rescrape	src/utils/payouts/rescrape.ts	1-292
Payout processing	src/utils/payouts/processRequest.ts	1-243
Frontend submit modal	features/submissions/components/SubmitVideoModal.tsx	1-449
Admin review queue	features/admin/submissions/hooks/useAdminSubmissions.ts	1-189

---

Known Coupling Points

1. Campaign → Submission: acceptingSubmissions, viewsFrozen, budget threshold (95%)
2. Submission → Tracking: acceptedAt, nextPollAt, trackingStoppedAt, consecutiveScrapeFailures
3. Submission → Payout: paidOut, paidViewsTotal, paidAmountTotal, PayoutItem rows
4. LinkedSocialAccount: Must verify account ownership before first submission per platform
5. Discord: Legacy approval queue removed; in-app notifications only (userNotification)

---

Where to Start

• New to the codebase? Read architecture.md then lifecycle.md
• Debugging a submission? Check backend.md for the endpoint, then review-flow.md for status transitions
• Understanding payouts? Start with payouts-and-dependencies.md
• Frontend work? See frontend.md for routes and component hierarchy