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.

Local Development

Confirmed setup

Prerequisites

• npm is the package manager for both repositories.
• PostgreSQL is required by the backend (provider = "postgresql" in prisma/schema.prisma).
• Node 20 is the only documented runtime recommendation (Bloxclips-backend/DEPLOYMENT.md); neither package enforces a version. The backend build was also verified on Node 22.19.0 during this audit.
• Redis, a message broker, and Docker are not required by the implementation. No client libraries or container definitions exist.

Backend API

cd Bloxclips-backend
npm ci
cp .env.template .env
# Fill required local values; never commit .env.
npx prisma generate
npx prisma migrate deploy
npm run dev:api

The API listens on API_PORT or 3001. In development it uses HTTP unless both certs/origin.pem and certs/origin-key.pem exist; when both exist, startup uses HTTPS on port 443. /api/health is the basic health endpoint.

API startup also creates a lightweight Discord client, resumes stuck payout requests, starts the payment-system timers, and starts PV tracker autosync. Consequently a “web only” API process can still perform background work and contact Discord/external services.

Discord bot

Run this separately from the API:

cd Bloxclips-backend
npm run dev:bot

The bot logs in with DISCORD_TOKEN and loads the currently enabled commands in src/index.ts. Deploy slash-command definitions with npm run deploy after confirming the target application and guild variables.

Frontend

cd BloxClips-frontend
npm ci
export NEXT_PUBLIC_API_URL=http://localhost:3001
export NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-development-site-key
npm run dev

The frontend defaults the backend origin to http://localhost:3001 in most callers and next.config.ts. Open http://localhost:3000. OAuth redirect URIs must match the provider configuration and backend variables; the provider callback then redirects to the frontend.

Database lifecycle

• Generate client: npx prisma generate (also runs on postinstall).
• Apply existing production-style migrations: npx prisma migrate deploy.
• For creating a migration during future schema work: use Prisma’s normal migrate dev workflow only after coordinating database ownership; this audit did not execute it.
• No canonical seed command is declared. Specific backfill/seed scripts exist under scripts/ and should not be run indiscriminately.

Verification commands

Repository	Command	Audit result
Backend	npm run build	Passed with TypeScript compiler under Node 22.19.0
Backend	tests	No npm test script; four referral node:test files exist but no repository-wide runner is configured
Backend	lint	No lint script/config found
Frontend	npm run lint	Source command is configured; audit workspace could not execute it because the pre-existing node_modules installation lacked an executable ESLint
Frontend	npm run build	Audit workspace could not execute it because its pre-existing install reported invalid/missing executable Next; run npm ci in a clean environment before judging source health
Frontend	tests	No test framework or test script found

No dependencies were installed or changed during the audit.

The three database-free referral tests can be run with the command verified during this audit:

node --require ts-node/register --test \
  src/utils/referrals/code.test.ts \
  src/utils/referrals/fingerprint.test.ts \
  src/utils/referrals/policy.test.ts

All three passed under Node 22.19.0. integration.test.ts requires a dedicated test PostgreSQL database and deletes/recreates marker test records during setup/cleanup. Its analogous command is:

DATABASE_URL=your_dedicated_test_database \
  node --require ts-node/register --test src/utils/referrals/integration.test.ts

This integration command was not run because no isolated test database was provided. Test-file comments use --import ts-node/register; that form failed to register TypeScript correctly in the audited Node 22/CommonJS environment, while --require succeeded.

Likely setup

• A local developer needs valid Discord and at least one OAuth provider to exercise sign-in. The API can compile without these, but the corresponding flow cannot work.
• Social submission flows require YouTube and/or Apify access depending on platform.
• Full payout/tax flows can boot in documented mock modes for PayPal, NowPayments, and Tax1099. Stripe has no equivalent application-level mock mode; use Stripe test credentials.
• Local tax PDFs use storage/tax-forms/ when R2 variables are absent. Production deliberately refuses the local fallback.
• The prior deployment likely ran API and bot as separate PM2 processes behind Cloudflare, but no committed process-manager file proves the active topology.

Missing information

• Access to the real PostgreSQL database or a sanitized development dump.
• OAuth application credentials and the exact registered callback origins.
• Discord application/guild/channel IDs and whether the bot is required for ordinary API work.
• Cloudflare R2, Turnstile, origin-certificate, and DNS configuration.
• Payment provider sandbox/test accounts and webhook forwarding instructions.
• Apify actors/quotas and YouTube API quota ownership.
• Google Calendar account/refresh token, Resend domain verification, and Twilio sender access.
• Whether PV tracker state should be copied from production; it is file-backed rather than database-backed.
• A supported seed order for GuildConfig, PaymentSystemConfig, FTIN countries, admins, and test users.

Processes and scheduled work

For a complete development environment, run frontend, API, and bot in separate terminals. No standalone worker command exists. Payment/tax/PV timers run inside the API process. src/scheduler.ts, which would run campaign expiry and submission view tracking, is not invoked by either current TypeScript entrypoint; do not assume those tasks run locally or in production without confirming an external launcher.