TesterKit docs

Internal documentation for the monorepo foundation. Product flows and data behavior are owned by downstream agents; this page covers repository structure and deployment wiring.

Monorepo layout

testerkit/
  apps/
    dashboard/   # Next.js — UI + /docs + API routes (shared deploy)
    api/         # Next.js — headless route handlers (optional separate Vercel project)
  packages/
    sdk/         # Browser SDK (@alphatrait/sdk)

Scripts

• pnpm dev — runs Turborepo dev for all workspaces (dashboard on port 3000, API on 3001).
• pnpm build — production builds via Turborepo.
• pnpm lint — ESLint across workspaces that define a lint script.

Supabase (managed database)

Project ref ulyvrvsofzdaodnvzjet — open this ID in the Supabase dashboard. API URL: https://ulyvrvsofzdaodnvzjet.supabase.co.

Deployment environment variables NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, and SUPABASE_SERVICE_ROLE_KEY are provisioned by the platform. Do not replace them in the repo unless you are rotating credentials on purpose.

See the repository file infra/VERCEL_SUPABASE.md (or the same path in your checkout) for the Vercel + Supabase integration checklist, env var table, and initial admin bootstrap notes.

Vercel + GitHub

1. Connect the GitHub repository to Vercel (import project). Enable preview deployments for pull requests if you want branch previews.
2. Create one Vercel project with root directory apps/dashboard for the primary site.
3. Optionally create a second Vercel project with root directory apps/api if you want the headless API deployed on its own hostname.
4. Install the Supabase integration (or set env vars in the Vercel dashboard) so server routes can reach Postgres securely.

Floating bug reporter

A draggable floating control is mounted from the root layout: bug → play → action rail (submit, pause/resume capture, screenshot with review modal, text sheet). It initializes global capture (including URL + click streams), uploads screenshots to Supabase Storage, then calls POST /api/bug-report with merged metadata.

SDK package

Import from @alphatrait/sdk. The dashboard workspace already depends on it via workspace:* so features can dogfood the package without publishing to npm.

API surface: BugKit.init(options?), BugKit.report(options?), BugKit.addBreadcrumb(...), BugKit.pauseCapture() / resumeCapture(), peekCapture(), and BugKit.shutdown() (alias TesterKit.*). The SDK batches console, fetch, global errors, breadcrumbs, navigation, and interaction rows to POST /api/bug-report with no framework dependencies.

End-to-end integration

Follow the Integration Tester checklist in the repository file INTEGRATION-E2E.md (repo root). It covers the SDK demos on / and /docs, the POST /api/bug-report contract, Supabase persistence in bug_reports, and the /reports operational view.