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

On stk, a draggable floating control is mounted from the root layout via @alphatrait/react: bug → play → action rail (submit, pause/resume, screenshot with review modal, text sheet, timeline). Customer sites use the same package — see docs/CUSTOMER-INTEGRATION.md or copy the integration guide from /admin after generating a key.

SDK package

@alphatrait/sdk handles capture; @alphatrait/react renders the UI. BugKit.init() alone does not show a bug icon — mount TesterKitReporter on customer apps.

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.

{
  "sessionId": "",
  "projectId": "docs-smoke",
  "userId": null,
  "logs": [],
  "network": [],
  "errors": [],
  "breadcrumbs": [],
  "navigation": [],
  "interactions": [],
  "metadata": {
    "preview": "live_buffer",
    "variant": "docs"
  },
  "timestamp": "2026-07-24T16:24:08.388Z"
}

Site reviews (Code Agent)

Admin users run per-site repo audits from /reports?tab=reviews. Each review launches a Cursor agent against the site's github_repo_url (set in /admin). The agent returns JSON listing open PRs and unmerged branches; rows land in agent_review_items with optional links to bug_reports.

• CURSOR_API_KEY and TESTERKIT_DASHBOARD_URL (optional) on stk.
• One in_progress review per site at a time.
• Mark review done → linked draft bugs become testing.
• Bugs list shows an In review badge when linked on an active review.

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.