Development Guide

Quick Start

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

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

Project Structure

teak/
├── apps/
│   ├── web/          # Next.js 16 frontend
│   ├── mobile/       # Expo React Native
│   ├── extension/    # Chrome extension (Wxt)
│   └── docs/         # Documentation site
├── backend/
│   ├── convex/       # Database & functions
│   │   ├── tasks/    # Background processing
│   │   └── workflows/# AI pipeline orchestration
│   └── shared/       # Shared utilities
└── package.json

Tech Stack

Backend: Convex (real-time DB + serverless)
Web: Next.js 16, React 19, TypeScript, TailwindCSS
Mobile: Expo React Native
Extension: Wxt framework
Auth: Clerk with JWT
UI: shadcn/ui + Radix
AI: OpenAI API
Screenshots: Cloudflare Browser Rendering
Billing: Polar
Testing: Playwright

Development 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

Access Points

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

Setup

1. Convex & Clerk

bun run predev  # Creates Convex deployment

Create Clerk app at clerk.com
Get keys: pk_test_... (frontend), sk_test_... (backend)
Configure Clerk in Convex dashboard → Settings → Authentication

2. Environment Variables

Backend (backend/.env.local):

CONVEX_DEPLOYMENT=dev:name-123
CLERK_SECRET_KEY=sk_test_...

Web (apps/web/.env.local):

NEXT_PUBLIC_CONVEX_URL=https://deployment.convex.cloud
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

Mobile (apps/mobile/.env.local):

EXPO_PUBLIC_CONVEX_URL=https://deployment.convex.cloud
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

Card Processing Pipeline

Cards flow through 4 AI-powered stages:

Classification - Content type detection & color extraction
Categorization - Link enrichment & provider metadata
Metadata - AI tags, summaries, transcripts
Renderables - Thumbnails & visual assets

Key Files:

backend/convex/workflows/cardProcessing.ts - Main orchestrator
backend/convex/workflows/steps/ - Individual stage logic
backend/convex/tasks/ai/ - Background AI processing

Extension Development

# Development
bun run dev:extension

# Build
bun run build:extension

# Chrome: Load unpacked from apps/extension/build/chrome-mv3-dev
# Firefox: bun run dev:firefox

Convex Functions

Real-time queries with built-in auth:

export const getCards = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) return [];

    return await ctx.db
      .query("cards")
      .filter((q) => q.eq(q.field("userId"), identity.subject))
      .collect();
  },
});

Development Guide

On this page