ClickStudio Bots

Next.js app (Bun runtime) with Better Auth and Drizzle on Postgres (Neon).

Use Bun 1.4.4, matching package.json. CI reads that version from the manifest, restores Bun's dependency cache, and installs with the frozen lockfile.

Setup

Voice transcription is deferred from the MVP. See the voice-note scope decision for unsupported-media handling and the requirements to revisit it in the future.

bun install

Create .env with:

• DATABASE_URL: Neon pooled connection string of the dev branch. Production's URL lives only in Vercel's environment variables, never in .env. The app keeps one global pg pool and registers it with attachDatabasePool. Use sslmode=verify-full in both pooled and direct connection strings to preserve certificate and hostname verification and avoid the pg warning about changing SSL mode semantics.
• BETTER_AUTH_SECRET
• APP_URL: e.g. http://localhost:3000
• RESEND_API_KEY: Resend API key used for invitation emails.
• EMAIL_FROM: verified Resend sender, e.g. ClickStudio Bots <[email protected]>.

Apply migrations, optionally seed the demo Tenant, then start the dev server:

bun run db:migrate
bun run db:seed
bun run dev

Neon recommends the direct (unpooled) connection string for migrations. Never migrate production by hand: CI applies production migrations on merge to main (see Database migrations).

See ADR 0003 for why the app connects this way.

To enable owner-managed WhatsApp Channels, follow WhatsApp Channel setup for the Meta v4 configuration, encrypted-token keys and live validation steps.

To enable live inbox updates, set the server-only ABLY_API_KEY as described in Realtime inbox setup.

See Phone inbox for responsive layouts and browser checks.

To configure the Bot, start with Behaviour settings and Testar Bot setup and code entry points. The sandbox guide explains provider keys, model access, daily limits and production isolation. Set the server-only AI_MODEL_ID to choose a different model per environment (for example, google/gemini-2.5-flash-lite for local Gateway testing). Capturing Contact details covers the capture capability.

Before testing in a browser, run bun run doctor. It checks local readiness without applying migrations, seeding data or calling a Model. See Local readiness and branch protection for JSON output and the optional provider probe.

For personal-data incidents, follow the incident runbook, which is pending legal review before go-live.

Scripts

Script	What it does
bun run dev	Next.js dev server
bun run doctor	Read-only local readiness report (guide)
bun run lint	ESLint
bun run format	Format code and configuration with Bun, including Tailwind class order
bun run format:check	Check formatting without changing files
bun run typecheck	Generate Next.js route types, then check with native TypeScript 7
bun run typecheck:fast	Generate Next.js route types, then check with Bun
bun run test	Bun test runner (PGlite suites included)
bun run evaluate:provider --help	Manual provider evaluation and offline human scoring (guide)
bun run db:generate	Generate a migration in drizzle/ from db/schema
bun run db:migrate	Apply pending migrations to DATABASE_URL
bun run admin:create	Create a platform administrator (see below)
bun run sweep:schedule	Create or update the QStash schedule for the sweep (guide)
bun run db:seed	Recreate the demo Tenant on the dev database (see below)

TypeScript and formatting

The @typescript/native dependency aliases stable TypeScript 7 and provides tsc for bun run typecheck. The typescript dependency aliases Microsoft's TypeScript 6 compatibility package so ESLint and other tools can still import the JavaScript compiler API. Keep both dependencies: replacing the compatibility alias with TypeScript 7 would break those tools. See Microsoft's compatibility setup.

Next.js 16.4.2 resolves the typescript package directly, so its build check uses compatibility TypeScript 6. Run bun run typecheck to validate with TypeScript 7; CI runs this command. bun run typecheck:fast is an additional local check using Bun's bundled checker. Both commands generate Next route types first.

Editor TypeScript support is configured separately. Use the editor's native TypeScript 7 language server for native diagnostics; the compatibility package is retained for tools and the existing Next.js language-service plugin.

Formatting options live in bunfig.toml. Run bun run format before committing; CI enforces bun run format:check. Generated migrations and Markdown documents are excluded. Import order is preserved, and Tailwind classes are sorted using app/globals.css.

Platform administrators and Tenants

Public sign-up is disabled. Create the first platform administrator from the CLI:

ADMIN_PASSWORD="<at least 8 characters>" bun run admin:create [email protected] "Nome do Admin"

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗