Development Guide

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

Quick Start (local)

Clone the repository:

git clone https://github.com/praveenjuge/teak.git

Move into the project:
Terminal window
```
cd teak
```
Install dependencies with Bun:
Terminal window
```
bun install
```
Start the stack (web + Convex backend):
Terminal window
```
bun run dev
```

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

Directoryteak/
- Directoryapps/
  - Directoryweb/ Next.js frontend (app router, shadcn/ui)
    …
  - Directoryapi/ Hono API gateway (public API proxy)
    …
  - Directorymobile/ Expo React Native
    …
  - Directorydesktop/ Electron desktop app (React)
    …
  - Directoryextension/ Chrome extension (Wxt)
    …
  - Directoryraycast/ Raycast extension
    …
  - Directorydocs/ Documentation site (Astro + Starlight)
    …
- Directorypackages/
  - Directoryconvex/ Convex backend
    Directoryai/ AI metadata helpers
    …
    Directorycard/ Card mutations/queries
    …
    Directoryworkflows/ AI pipeline orchestration
    …
  - Directoryui/ 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

Start a Convex dev deployment:
Terminal window
```
bunx convex dev
```

Generate and set the Better Auth signing secret:

bunx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)

Point Convex at your local Next.js origin:

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).