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

Access Points

• Web App: http://app.teak.localhost:1355
• Admin: http://app.teak.localhost:1355/admin
• API Gateway: http://api.teak.localhost:1355
• MCP Endpoint: http://api.teak.localhost:1355/mcp
• Convex Dashboard: opens after bunx convex dev
• Mobile: Expo Go or simulator
• Extension: Chrome dev mode
• Docs: http://docs.teak.localhost:1355

Project Layout

teak/
├── apps/
│   ├── web/         # Next.js frontend (app router, shadcn/ui)
│   ├── api/         # Hono API gateway (public API proxy)
│   ├── mobile/      # Expo React Native
│   ├── desktop/     # Electron desktop app (React)
│   ├── extension/   # Chrome extension (Wxt)
│   ├── raycast/     # Raycast extension
│   └── docs/        # Documentation site (Astro + Starlight)
├── packages/
│   ├── convex/      # Convex backend
│   │   ├── ai/      # AI metadata helpers
│   │   ├── card/    # Card mutations/queries
│   │   └── workflows/ # AI pipeline orchestration
│   └── ui/          # Shared UI components and hooks
├── turbo.json       # Turborepo pipeline config
└── package.json     # Root package + workspaces

Tech Stack

Layer	Technology
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
Billing	Polar
Testing	Bun (unit), Playwright (E2E)
Monorepo	Turborepo

Core Commands

bun run dev              # Web + Convex backend
bun run dev:all          # All services

bun run dev:convex       # Convex backend only
bun run dev:web          # Next.js web
bun run dev:api          # API gateway (Hono)
bun run dev:mobile       # Expo mobile
bun run dev:desktop      # Electron desktop
bun run dev:extension    # Chrome extension
bun run dev:raycast      # Raycast extension
bun run dev:docs         # Docs site

bun run build            # Production build (all)
bun run build:extension  # Package Chrome extension
bun run build:raycast    # Build Raycast extension

bun run lint && bun run typecheck
bun run test             # Unit tests

bun run check            # Quality report (Ultracite)
bun run fix              # Auto-fix issues

bun run pre-commit       # Pre-commit checks
bun run publish:raycast  # Publish to Raycast store
bun run clean            # Clear Turborepo caches

Setup Checklist

Convex + Better Auth

bunx convex dev  # Creates Convex deployment
bunx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
bunx convex env set SITE_URL http://app.teak.localhost:1355

BETTER_AUTH_SECRET signs sessions (set once per environment). SITE_URL must match your Next.js origin. CONVEX_SITE_URL is the .site domain assigned by Convex—copy it from the dashboard.

API Gateway

Set CONVEX_HTTP_BASE_URL for apps/api before running bun run dev:api.

Example:

echo "CONVEX_HTTP_BASE_URL=https://<your-deployment>.convex.site" > apps/api/.env

The same service exposes the REST API at /v1 and MCP endpoint at /mcp.

Environment Variables

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

Optional local overrides: TEAK_DEV_APP_URL (default: http://app.teak.localhost:1355), TEAK_DEV_API_URL (default: http://api.teak.localhost:1355), TEAK_DEV_DOCS_URL (default: http://docs.teak.localhost:1355).