Development

Development

Prerequisites

• Node.js 20+
• pnpm
• bun
• PostgreSQL (for database features)

Setup

# Install dependencies
pnpm install

# Start dev server (port 3010)
bun run dev

# Start desktop renderer (port 3015)
bun run dev:desktop

Background conversation generation starts a Graphile worker against DATABASE_URL. Tests and local production-like builds set DISABLE_CONVERSATION_WORKER=1 or NODE_ENV=test so the worker does not run. See Background Conversation Generation.

Commands

# Build
bun run build           # Production build
bun run build:docker    # Docker build

# Type checking
bun run type-check      # Uses tsgo (fast)
bun run type-check:tsc  # Uses tsc (strict)

# Linting
bun run lint            # ts + style + type-check + circular deps
bun run lint:ts         # ESLint only
bun run lint:style      # Stylelint only

# Database
bun run db:generate     # Generate Drizzle migrations
bun run db:migrate      # Run migrations
bun run db:studio       # Open Drizzle Studio

Testing

# Run specific test file (RECOMMENDED)
bunx vitest run --silent='passed-only' 'path/to/test'

# Package tests
cd packages/database && bunx vitest run --silent='passed-only' '[file]'

# NEVER run `bun run test` — runs the full suite, ~10 min

Project Structure

src/
├── app/          # Next.js App Router
├── features/     # Large self-contained UI feature areas
├── store/        # Zustand stores (one per domain)
├── services/     # Client-side service layer (calls tRPC/API)
├── server/
│   ├── routers/  # tRPC routers
│   └── services/ # Server-side service implementations
├── locales/      # i18n (TypeScript source of truth)
└── libs/         # Shared utilities and abstractions

packages/
├── database/     # Drizzle schemas, models, repositories
├── model-bank/   # Model definitions and capabilities
├── model-runtime/# LLM provider adapters
└── types/        # Shared TypeScript types