knowhere-pitchpilot

Knowhere PitchPilot is a Bun-based monorepo for an authenticated web application with AI chat, typed APIs, and a shared UI package.

What It Includes

• Next.js 16 app in apps/web
• Session-based authentication and protected routes
• Streaming AI chat endpoint powered by the Vercel AI SDK
• Typed API layer with oRPC
• PostgreSQL persistence with Drizzle
• Shared UI primitives in packages/ui
• Turborepo workspace tooling

Workspace Layout

knowhere-pitchpilot/
├── apps/
│   └── web/         # Main web application
├── packages/
│   ├── api/         # API procedures and server context
│   ├── auth/        # Authentication setup
│   ├── db/          # Database schema and database tooling
│   ├── env/         # Runtime environment validation
│   ├── ui/          # Shared UI components and styles
│   └── config/      # Shared TypeScript and tooling config

Local Development

Install dependencies from the repository root:

bun install

Use Bun >=1.3.0. This workspace relies on Bun catalogs defined in the root package.json.

Create or update apps/web/.env with the required values:

DATABASE_URL=
BETTER_AUTH_SECRET=
BETTER_AUTH_URL=http://localhost:3002
CORS_ORIGIN=http://localhost:3002
BLOB_READ_WRITE_TOKEN=
NEXT_PUBLIC_GAMMA_ENABLED=false
NEXT_PUBLIC_DEFAULT_RENDER_ENGINE=pptxgenjs

PitchPilot stores source uploads, generated images, and PPTX artifacts in a private Vercel Blob store. Pull BLOB_READ_WRITE_TOKEN from Vercel before running the app locally.

To enable the Gamma renderer, add these variables as well:

GAMMA_API_KEY=
GAMMA_THEME_ID=
GAMMA_FOLDER_IDS=
NEXT_PUBLIC_GAMMA_ENABLED=true
NEXT_PUBLIC_DEFAULT_RENDER_ENGINE=gamma

GAMMA_API_KEY comes from Gamma Settings > API Keys. GAMMA_THEME_ID is optional and can be discovered from GET /v1.0/themes. GAMMA_FOLDER_IDS is optional, comma-separated, and can be copied from the Gamma app or fetched from GET /v1.0/folders.

PitchPilot does not read AI_GATEWAY_API_KEY. Vercel AI Gateway auth is expected to come from Vercel platform auth in deployments and from Vercel OIDC in local development.

Apply the database schema:

bun run db:push

Start the app:

bun run dev

The web app runs at http://localhost:3002.

Common Commands

• bun run dev - start the workspace in development mode
• bun run dev:web - run only the web app
• bun run build - build the workspace
• bun run check-types - run TypeScript checks
• bun run db:push - sync schema directly to the database during rapid prototyping
• bun run db:generate - generate database artifacts
• bun run db:migrate - run migrations
• bun run db:studio - open the database studio
• bun run check - run Ultracite checks
• bun run fix - apply Ultracite fixes

UI Notes

Shared components live in packages/ui. Update tokens and base styles in packages/ui/src/styles/globals.css, and add new primitives to the shared package when they are meant to be reused across apps.