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.

Developer Onboarding

What this system is

BloxClips connects paid promotional campaigns with creators who submit social videos. The frontend contains a public marketing site and creator/admin dashboards. The backend owns identity, operational campaigns, submissions, metric collection, payout/tax/referral workflows, Discord operations, and external integrations.

The two most important orientation facts are:

1. Public /campaigns are static case studies; dashboard campaigns are database-backed paid campaigns.
2. The code carries both Discord-era and provider-neutral identity/payout concepts, so IDs and historical fields must be traced rather than inferred from names.

Recommended reading path

1. Repository inventory — identify boundaries, stacks, and entrypoints.
2. Local development — understand required processes and missing access.
3. Terminology — learn the project’s overloaded and drifted vocabulary.
4. Feature map — connect product areas to both repositories.
5. Architecture — understand processes, database, services, and request lifecycle.
6. Data model — learn core relationships and status lifecycles.
7. Frontend and Backend — inspect each implementation in depth.
8. Frontend/backend integration — see the manually maintained API contract.
9. Authentication and authorization — distinguish identity, UI visibility, and backend enforcement.
10. Whop integration, Background jobs, and External services.
11. Request and data flows — rehearse the major workflows end to end.
12. Risks and unknowns before planning any change.

Suggested first day

Morning: build the map

• Clone/open both repositories side by side and confirm clean working trees before touching files.
• Read the repository inventory, terminology, and architecture documents.
• Open the three backend entrypoints (src/index.ts, src/api/server.ts, src/api/index.ts) and both frontend root/dashboard layouts.
• Follow one simple call: dashboard auth /api/auth/me from component to router to Prisma.

Midday: run locally

• Use Node 20 unless the team standard says otherwise.
• Run clean npm ci in each repository.
• Create backend .env from .env.template with development credentials supplied through the team’s secret manager.
• Apply Prisma migrations to a dedicated development PostgreSQL database.
• Run API, bot (when needed), and frontend as separate processes.
• Verify health, OAuth callback, and current user. Do not run backfill scripts against shared data merely to populate local state.

Afternoon: trace a product flow

Trace submission end to end: operational campaign list → submit modal → source scrape → linked-account verification → submission row → admin review → metric tracking. Then trace payout request → item review → tax/method gates → explicit send. These two flows expose most important coupling.

Finish by reading risks/unknowns and identifying which questions need answers from the previous team before accepting production responsibility.

Safe working habits in this codebase

• Search exact API paths/status strings across both repositories before changing them.
• Check migrations as well as Prisma schema for constraints.
• Treat creator UI eligibility as display logic; verify backend enforcement.
• Account for both webUserId and legacy Discord userId.
• For campaign/payout math, trace views, caps, minimums, fees, budget burn, prior-paid totals, and legacy rows together.
• Establish scheduler entrypoint and deployment multiplicity before changing background work.
• Never log/decrypt full TINs, OAuth tokens, payment destinations, or secrets.
• Document a suspected dead path before removing it; static searches cannot prove production reachability.

Before your first change

Use Codebase navigation to select starting files, reproduce current behavior, write down the cross-repository contract, and check Risks and unknowns for the domain. This audit intentionally made no application changes, dependency updates, or schema modifications.