Development Guide

Prerequisites: Bun 1.0+, Node.js 18+, Git

Quick Start (local)

git clone https://github.com/praveenjuge/teak.git
cd teak
bun install
bun run predev

Access Points

Web App: http://localhost:3000
Admin: http://localhost:3000/admin
Convex Dashboard: opens after bun run predev
Mobile: Expo Go or simulator
Extension: Chrome dev mode
Docs: http://localhost:3001

Project Layout

teak/
├── src/          # Next.js frontend
├── public/       # Web static assets
├── convex/       # Database, functions, workflows, shared utilities
│   ├── ai/       # AI metadata helpers
│   ├── card/     # Card mutations/queries
│   └── workflows/# AI pipeline orchestration
├── mobile/       # Expo React Native
├── extension/    # Chrome extension (Wxt)
├── docs/         # Documentation site
└── package.json  # Root package + scripts

Tech Stack

Backend: Convex (real-time DB + serverless)
Web: Next.js, React, TypeScript, TailwindCSS
Mobile: Expo React Native
Extension: Wxt framework
Auth: Better Auth
UI: shadcn/ui + Radix
AI: Groq API
Screenshots: Kernel
Billing: Polar
Testing: Playwright

Core Commands

# All services
bun run dev

# Individual services
bun run dev:backend       # Convex
bun run dev:frontend      # Next.js web
bun run dev:mobile        # Expo mobile
bun run dev:extension     # Browser extension
bun run dev:docs          # Documentation

# Build
bun run build             # Web production
bun run build:extension   # Extension build
bun run package:extension # Extension package

# Test
bun run test              # E2E tests

Setup Checklist

Convex + Better Auth

bun run predev  # Creates Convex deployment
npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
npx convex env set SITE_URL http://localhost:3000

BETTER_AUTH_SECRET signs Better Auth sessions—set it once per environment.
SITE_URL must match your Next.js origin locally and inside Convex.
CONVEX_SITE_URL is the .site domain Convex assigns; copy it from the dashboard after bun run predev.

Environment Variables

See Self-Hosting → Environment settings for every env var required across web, mobile, extension, and the Convex backend.

Development Guide

On this page