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.

BloxClips documentation entry point

For current development, use the workspace router or go directly to the relevant tracked repository skill in your Treehouse lease. Backend/frontend integrate on dev; metric-scraper integrates on main. Mandatory execution policy is AGENTS.md.

The outer architecture/navigation collection below is a historical snapshot. It has not been revalidated as a whole. In particular, two-repository maps, multiple payment rails, SQLite, retired tracking and old payout descriptions must not drive implementation. Current skills point to owning source, tests and reviewed commits; load only the references needed for the task.

---

Historical documentation index (retained)

BloxClips Developer Documentation

System overview

BloxClips is a creator-campaign platform with a public marketing site, an authenticated clipper dashboard, an administrative operations UI, a REST API, a Discord bot, and in-process background work. Creators submit YouTube, TikTok, or Instagram videos to campaigns; administrators review submissions and payout requests; the backend tracks views, computes campaign spend, and dispatches payouts through configured payment rails.

The code is split into two independent npm repositories. There is no shared package or generated API client between them.

Repository map

BloxClips/
├── BloxClips-frontend/   # Next.js public site and dashboard
├── Bloxclips-backend/    # Express API, Discord bot, Prisma schema, jobs
└── docs/                 # Cross-repository documentation (this directory)

Detected frontend: ../BloxClips-frontend

Detected backend: ../Bloxclips-backend

Start here

1. Onboarding guide
2. Local development
3. Terminology
4. Feature map
5. Architecture
6. Risks and unknowns

Quick navigation

• Repository inventory — technologies, entrypoints, scripts, and directory maps
• Architecture — deployment units, internal components, and request lifecycle
• Frontend — routes, pages, state, and API callers
• Backend — API and bot domains, services, and invariants
• Frontend/backend integration — transport, endpoint map, and fragile contracts
• Data model — core Prisma entities, relationships, and state fields
• Authentication and authorization — OAuth, JWT cookie, admin checks, and disabled gates
• Whop integration — the narrowly scoped Whop usage actually present
• Background jobs — timers, workers, recovery, and the dormant tracking scheduler
• External services — payment, social, storage, messaging, and analytics integrations
• Environment and configuration — environment-variable inventory without secret values
• Local development — confirmed setup, likely setup, and missing access
• Feature map — “where do I start?” by product feature
• Request and data flows — major end-to-end workflows
• Data-fetching and cache policy — when no-store is required vs safe to cache, TanStack rules, new-feature checklist
• Codebase navigation — task-oriented source guide
• Operational & Financial Analytics project brain — current #63 issue/dependency inventory, financial contracts, reviewable PR sequence, and orchestration handoff
• Risks and unknowns — coupling, ambiguity, legacy paths, and questions for the prior team

Important unknowns

The largest operational unknowns are which process manager starts each backend entrypoint in production, whether the view-tracking scheduler is intentionally disabled, which of the legacy and current payout paths remains supported, and whether ordinary clippers are meant to enter the currently admin-gated dashboard. See Risks and unknowns for evidence and questions.