Skip to content

Getting Started

Repository

Source of truth: EuVinicios/mypaidtraffic (private). Application host: Vercel project mypaidtraffic (brandvelia.com, app.brandvelia.com). Database host: Supabase project panoptes.

Tech stack

Layer Technology
Monorepo / build pnpm workspaces + Turborepo
Language / typing TypeScript (strict)
Web app Next.js (App Router, src/, Tailwind CSS v4)
Database / auth Supabase (Postgres, Row-Level Security, Edge Functions, APIs)
AI OpenRouter (via an internal gateway), schema-constrained
Affiliate network ClickBank (LinkBuilder, INS) — first integrated network
UI kit shadcn/ui + Lucide icons

Requirements

  • Node.js 20+
  • pnpm (recommended version managed by the repo's .npmrc)
  • The docs build uses Python 3 + Material for MkDocs in the isolated .venv-docs (see Operations).

Commands (run from the repo root)

pnpm install      # install all workspace dependencies
pnpm build        # production build (Turborepo → Next.js app)
pnpm lint         # ESLint
pnpm typecheck    # tsc --noEmit across packages

The three workspace packages are:

  • packages/types — shared domain TypeScript + Zod schemas (nominal IDs, enums).
  • packages/ai — the internal OpenRouter gateway.
  • packages/integrations — network adapters (ClickBank: LinkBuilder, INS decrypt/normalize, QuickStats, Opportunity Score, Marketplace feed).

Project layout

mypaidtraffic/
├── apps/web/                      # Next.js app (root directory for Vercel)
│   ├── app/                       #   App Router routes (server & api route handlers)
│   └── components/                #   shadcn/ui components + admin shell/layout
├── packages/
│   ├── types/                     #   @brandvelia/types   (shared domain + zod)
│   ├── ai/                        #   @brandvelia/ai       (OpenRouter gateway)
│   └── integrations/              #   @brandvelia/integrations (ClickBank adapters)
├── supabase/migrations/           #   versioned SQL migrations (apply with `supabase db push`)
├── docs/                          #   ⬅ this documentation site (Material for MkDocs)
└── .claude/skills/vibeharness/    #   local AI production harness

The web app's route tree under apps/web/src/app/ follows the main $(admin)/app scaffold, organized by feature: dashboard, radar, offers, campaigns, creatives, landing-pages, copilot, leads, experiments, finance, integrations, and a built-in /app/manual (affiliate manual) and /app/login.

Configuration & environment

Configuration lives in environment variables. The server side holds the sensitive keys:

  • SUPABASE_SERVICE_ROLE_KEY / SUPABASE_URL — for authenticated server-side DB access (API routes, middleware).
  • SUPABASE_ANON_KEY / SUPABASE_URL — for the public Next.js SDK (auth/session handling).
  • OPENROUTER_API_KEY — gateway key for AI features (server only).
  • CLICKBANK_* (vendored credentials) — ClickBank adapter configuration.

See Operations for the full required variable table and the Security & Rules page for how each is handled.

Browser automation note

Some integrations use a local Playwright/@playwright/test headless browser to exercise ClickBank UI flows. Run it from the root with:

npx playwright test  # launches once, collects browsers, then exits

Verifying a local change

pnpm install
pnpm typecheck
pnpm lint
pnpm build

All three gates — pnpm lint && pnpm typecheck && pnpm build — must pass before a change is considered complete.