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/     # Tauri v2 desktop app (Rust + React)
│   ├── extension/   # Chrome extension (Wxt)
│   ├── raycast/     # Raycast extension
│   └── docs/        # Documentation site + desktop updater metadata host (teakvault.com/updates)
├── packages/
│   ├── config/      # Shared config helpers (dev URLs, env resolution)
│   ├── 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      # Tauri 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).

Automated Workflows

The repository uses agentic GitHub Actions workflows for continuous maintenance. These run automatically on a schedule and may open PRs or issues.

Workflow	Trigger	Purpose
Daily Documentation Updater	Daily + push to main	Reviews merged PRs and updates documentation to match code changes
Update Docs	Every push to main	Analyzes diffs and creates draft PRs to keep docs in sync
Documentation Unbloat	Daily + `/unbloat` slash command	Reduces verbosity in docs while preserving clarity
Documentation Noob Tester	Daily	Tests getting-started guides as a first-time user would
Code Simplifier	Daily	Identifies overly complex code and opens PRs with clarifications
Duplicate Code Detector	Daily + manual	Finds duplicate patterns and suggests refactoring
Repository Quality Improver	Weekdays at 1 PM UTC	Audits repository health and opens improvement PRs
Workflow Health Manager	Daily	Monitors the health of all other automation workflows
Security Compliance Campaign	Manual	Scans for vulnerabilities and tracks fixes toward an audit deadline

These workflows are powered by GitHub Copilot agentic workflows. Each has a corresponding .md definition file in .github/workflows/ that can be customized.

Development Guide

On this page