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.

Historical snapshot — superseded for agent navigation (2026-09-25). This document can describe retired architecture, old database/payment models, or primary-checkout paths. Do not use it as current implementation policy. Start with the project router, resolve the owning Treehouse lease, then load its repository skill/source index. The original text below is retained for historical reasoning.

Codebase Navigation Guide

Paths below are relative to the parent directory.

I need to change a frontend page

Start with the route’s page.tsx under BloxClips-frontend/app/, then check its nearest layout.tsx, imports from app/components/, and every fetch URL. Dashboard-wide behavior is in app/dashboard/layout.tsx; public-wide behavior is in app/layout.tsx. Do not assume public /campaigns and dashboard campaigns share data.

I need to add or change an API endpoint

Start at Bloxclips-backend/src/api/index.ts to see mount prefix and global middleware, then the appropriate file in src/api/routes/. Check route-local middleware, validation in src/api/validation/schemas.ts, Prisma mutations, audit/notification side effects, and the exact frontend callers with rg '/api/your-path' BloxClips-frontend.

I need to understand campaigns

Read, in order:

1. Bloxclips-backend/prisma/schema.prisma (Campaign, Submission).
2. src/api/routes/campaigns.ts for creator-visible JSON and canSubmit.
3. Campaign sections of src/api/routes/admin.ts for mutation/publishing.
4. src/utils/campaignBudget.ts, calculateSubmissionEarnings.ts, and fees.ts.
5. Frontend app/dashboard/campaigns/ and app/dashboard/admin/campaigns/.

Public case studies instead begin at BloxClips-frontend/app/campaigns/campaignData.ts.

I need to understand submissions or scraping

Start with src/api/routes/submissions.ts, src/api/validation/schemas.ts, src/utils/platforms.ts, youtube.ts, and src/utils/scrapers/apify.ts. Ownership proof is in src/api/routes/verifications.ts and src/utils/profileBio.ts. Periodic tracking is src/utils/tracking/runTrackingTick.ts and src/scheduler.ts; remember that scheduler is not currently wired.

Frontend entry is app/components/SubmitVideoModal.tsx; verification is AccountVerificationModal.tsx; history/review are dashboard history and admin submission pages.

I need to modify authentication

Trace src/api/routes/auth.ts → src/api/middleware/auth.ts → WebUser/AuthAccount in Prisma → frontend login and app/dashboard/layout.tsx. Also inspect src/utils/encryption.ts, production config validation, cookie/CORS/origin setup in src/api/index.ts, and moderation checks. OAuth changes can affect account merging and admin identity.

I need to modify permissions

Website admin rules are in src/api/middleware/adminAuth.ts and environment allowlists. TOTP is in totpAuth.ts. Resource ownership is embedded in each router query rather than a policy layer. Discord bot manager rules are separate (GuildConfig.managerRole and bot auth helpers). Verify both UI visibility and backend enforcement.

I need to change database behavior

Read prisma/schema.prisma, then all relevant migrations—not only Prisma fields—because partial indexes, normalized uniqueness, and RLS are migration-level. Search every mutation of the entity and its callbacks-by-convention (notifications, audit calls, jobs). No database trigger definitions were found; side effects are application code.

I need to modify a background worker

• Payout worker: src/utils/payouts/processRequest.ts and rescrape.ts.
• Payment/tax timers: src/utils/payments/scheduler.ts and called tick modules.
• View tracking/campaign expiry: src/scheduler.ts, src/utils/tracking/.
• PV sync: src/utils/pvTracker.ts and admin route.

First establish which entrypoint calls it, how it survives restart, and whether multiple API instances could duplicate it.

I need to modify payouts

Begin with src/api/routes/payouts.ts, adminPayoutReview.ts, src/utils/payouts/, src/utils/payments/preflight.ts, src/utils/rails/dispatcher.ts, src/utils/fees.ts, and the Payout/PayoutItem models plus payout migrations. Then inspect legacy payout sections in admin.ts and src/utils/paypal.ts. Frontend entrypoints are dashboard payout/method/tax and admin payout list/detail.

I need to modify tax behavior

Start with tax models and src/api/routes/taxForms.ts; then src/utils/tax/taxForm.ts, validators, PDF generator, TIN encryption, Tax1099 drain/client, storage abstraction, admin tax routes, and year-end export. Profile mutation can invalidate tax state, and payout preflight consumes eligibility.

I need to modify Whop integration

Read both BloxClips-frontend/app/api/live/clipper-count/route.ts and backend src/api/routes/live.ts, then their consumers. Do not look for Whop authentication or payout models; none exist here. PV whop_username is unrelated free text.

I need to trace a frontend request into the backend

1. Search the exact URL string in BloxClips-frontend/app.
2. Resolve NEXT_PUBLIC_API_URL versus a same-origin Next /api route.
3. Search the path in backend src/api/index.ts and src/api/routes.
4. Account for the router mount prefix plus route-local path.
5. Follow Prisma calls and imported utilities, then search the response property names back in the component.

For admin calls, also check whether adminFetch or direct fetch is used. For /r/:code, account for the Next rewrite. For contact/Whop/Roblox, verify which duplicate server implementation the component selects.

I need to understand side effects

Search the mutation method/class plus createUserNotification, audit, publishCampaignToDiscord, updateCampaignAnnouncement, payout commission helpers, tax transition helpers, and scheduler selectors. Prisma model callbacks are not used; side effects are explicit service/router calls but can be fire-and-forget.