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.

Repository Inventory

Detection method and scope

The parent contains two Git repositories. Their responsibilities were identified from executable entrypoints, routes, package manifests, and data access—not directory names alone.

Role	Detected path	Evidence
Frontend	../BloxClips-frontend	Next.js App Router pages, layouts, route handlers, dashboard UI, and browser API calls
Backend	../Bloxclips-backend	Express API, Discord bot entrypoint, Prisma PostgreSQL schema, integrations, and scheduled work

No third application repository was found. The new docs/ directory is intentionally outside both Git repositories.

Frontend repository

Purpose. Serves the public BloxClips marketing/case-study site and the authenticated creator/admin web UI. It also owns a small number of Next.js server routes for contact mail, a public Whop member-count statistic, and Roblox proxying.

Concern	Implementation
Languages	TypeScript, TSX, CSS
Runtime/framework	Next.js ^16.2.4, React/React DOM 19.2.1, App Router
Runtime version	No engines, .nvmrc, or .node-version; @types/node is ^20 but is not a runtime declaration
Package manager	npm (package-lock.json)
Styling/build	Tailwind CSS 4 via PostCSS; Next/Turbopack configuration
UI dependencies	Framer Motion, Lucide, @dnd-kit, clsx, tailwind-merge
Data/state	Native fetch, React state/effects/context; no React Query, Redux, or generated API client
Authentication	Browser cookie session obtained from backend OAuth; dashboard calls /api/auth/me with credentials
Validation	Page-local/manual validation; Turnstile on contact form; no shared schema library
Tests	No test framework, test files, or test script found
Linting	ESLint 9 and eslint-config-next; several React/TypeScript rules disabled in eslint.config.mjs
Observability	Vercel Analytics and Speed Insights in app/layout.tsx
Deployment	vercel.json declares Next.js; no containers or CI workflow found
Environment files	README documents public variables; source references additional server-only variables; no committed example file
Entrypoints	app/layout.tsx, app/page.tsx, app/dashboard/layout.tsx, and Next route handlers under app/api/
Scripts	npm run dev, build, start, lint; launch.bat installs and starts development on Windows

Meaningful tree:

BloxClips-frontend/
├── app/
│   ├── api/                    # Next server routes: contact, Whop count, Roblox proxies
│   ├── campaigns/              # Public static case studies, not operational campaigns
│   ├── creator-guides/         # Public guide content
│   ├── dashboard/              # Authenticated creator and admin UI
│   │   ├── admin/              # Operations pages and shared admin components
│   │   └── payouts/            # Payment-method and tax onboarding
│   ├── components/             # Shared public/dashboard components
│   └── lib/                    # Admin fetch retry wrapper and shared utilities
├── public/                     # Marketing/case-study assets
├── next.config.ts              # backend referral rewrite and dev-origin setting
├── eslint.config.mjs
├── postcss.config.mjs
├── tsconfig.json
└── vercel.json

Important generated/local output: .next/ and next-env.d.ts are ignored/generated. node_modules/ is local. Public case-study data in app/campaigns/campaignData.ts is maintained source, not backend-generated data.

Backend repository

Purpose. Provides the REST API and business logic, persists application state in PostgreSQL, integrates external payment/social/messaging services, hosts a Discord bot, and starts several in-process schedulers.

Concern	Implementation
Languages	TypeScript; generated JavaScript/declaration/source-map artifacts are also checked into parts of src/
Runtime/framework	Node.js, Express 5.2.1, CommonJS output
Runtime version	No engine/version file. DEPLOYMENT.md specifies Node 20 on Ubuntu 24.04; the audit build also passed on installed Node v22.19.0
Package manager	npm (package-lock.json)
Database/ORM	PostgreSQL via Prisma 5.22.0; migrations under prisma/migrations/
API/validation	Express routers, Zod schemas, Axios and native/SDK clients
Authentication	Discord OAuth, Google OAuth, JWT cookie, encrypted provider tokens
Jobs/queues	In-process setTimeout/setInterval and setImmediate; no Redis, Bull, or durable queue
Cache/rate limit	Process-memory TTL caches and express-rate-limit; no shared cache
Payments	Stripe Connect, PayPal Payouts, NowPayments USDT/TRC-20, Tax1099
Social data	YouTube Data API and Apify TikTok/Instagram actors
Messaging	Discord.js, Resend, Twilio; Google Calendar/Meet booking
Storage	Cloudflare R2-compatible S3 SDK, with local disk fallback outside production
Security	Helmet, strict CORS/origin checks, JWT revocation version, TOTP, audit logs, encryption/HMAC
Tests	Four Node test files for referral utilities; no test script or broad application suite
Lint/format	No lint or formatter script/config found
Deployment	DEPLOYMENT.md describes PM2/DigitalOcean/Cloudflare; certificate-aware API startup. No PM2 config, container config, or CI workflow found
Entrypoints	src/index.ts (bot), src/api/server.ts (API Discord client), src/api/index.ts (Express composition/start)
Scripts	build/start/start:api/dev/dev:bot/dev:api/deploy/postinstall Prisma generation

Meaningful tree:

Bloxclips-backend/
├── prisma/
│   ├── schema.prisma            # PostgreSQL application schema
│   └── migrations/              # schema evolution and DB-level constraints
├── scripts/                     # operational/backfill/diagnostic scripts
├── src/
│   ├── api/
│   │   ├── middleware/          # auth, admin, rate limiting, referral/device cookies
│   │   ├── routes/              # REST domains and payment webhooks
│   │   ├── utils/               # profile/API helpers
│   │   └── validation/          # Zod request schemas
│   ├── commands/                # Discord slash commands
│   ├── handlers/                # Discord interactions/events
│   ├── utils/
│   │   ├── payouts/             # payout request worker and rescrape
│   │   ├── referrals/           # attribution and commission ledgers
│   │   ├── storage/             # R2/local storage and tamper checks
│   │   ├── tax/                 # forms, PDFs, validation, reminders
│   │   ├── tracking/            # accepted-submission polling
│   │   └── rails/               # payout dispatch/circuit controls
│   ├── index.ts                 # Discord bot process
│   ├── scheduler.ts             # tracking/expiry scheduler (not wired by TS entrypoints)
│   └── api/server.ts            # API process entrypoint
├── assets/                      # PV tracker seed/state assets
├── storage/                     # local tax-form storage fallback
├── package.json
├── tsconfig.json
└── .env.template

The backend’s checked-in .env is ignored and contains local secrets/configuration; it was treated as sensitive and no values are documented. Its keys show local configuration beyond the template. Generated .js, .d.ts, and .map siblings inside src/ appear to be historical compiler output; TypeScript files remain the build source because tsconfig.json includes src/**/* and outputs to dist/.

Existing documentation and mismatches

• Frontend README.md is largely the default Next.js README but correctly names its two public environment variables.
• Backend README.md and STRUCTURE.md mention SQLite/WAL, but prisma/schema.prisma declares PostgreSQL and the current Prisma helper contains no SQLite configuration.
• Backend DEPLOYMENT.md is useful for the previous single-host topology but should not be treated as proof of current production infrastructure.
• Backend PAYMENTS_SETUP_GUIDE.md, PAYMENT_SYSTEM_PLAN.md, and security notes contain design context; current routes, schema, and startup wiring are the authoritative behavior.