better-chatbot

What this skill does

# better-chatbot Contribution & Standards Skill

**Status**: Production Ready
**Version**: 3.0.0 (Optimized with progressive disclosure)
**Last Updated**: 2025-12-17
**Dependencies**: None (references better-chatbot project)
**Latest Versions**: Next.js 16.0.3, Vercel AI SDK 5.0.98, Better Auth 1.3.34, Drizzle ORM 0.41.0

---

## Overview

**better-chatbot** is an open-source AI chatbot platform for individuals and teams, built with Next.js 15 and Vercel AI SDK v5. It combines multi-model AI support (OpenAI, Anthropic, Google, xAI, Ollama, OpenRouter) with advanced features like MCP (Model Context Protocol) tool integration, visual workflow builder, realtime voice assistant, and team collaboration.

**This skill teaches Claude the project-specific conventions and patterns** used in better-chatbot to ensure contributions follow established standards and avoid common pitfalls.

---

## Quick Start

### Setup Development Environment

```bash
# Clone and install
git clone https://github.com/cgoinglove/better-chatbot.git
cd better-chatbot
pnpm install

# Configure environment
cp .env.example .env
# Add your API keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
# Add database URL: DATABASE_URL="postgresql://..."
# Add auth secret: BETTER_AUTH_SECRET="your-secret"

# Run development server
pnpm dev
```

### Core Commands

- `pnpm dev` - Start development server
- `pnpm build` - Production build
- `pnpm test` - Run unit tests
- `pnpm test:e2e` - Run E2E tests (requires DB + API keys)
- `pnpm check` - Lint + type check + tests (run before PR)

### Repository Structure

```
better-chatbot/
├── src/
│   ├── app/                # Next.js routes + API
│   ├── components/         # UI components by domain
│   ├── lib/               # Core logic (ai, db, validations)
│   ├── hooks/             # React hooks
│   └── types/             # TypeScript types
├── tests/                 # E2E Playwright tests
└── drizzle/              # Database migrations
```

---

## Core Architecture

### Three-Tier Tool System

Better-chatbot uses a three-tier tool architecture for AI capabilities:

1. **MCP Tools** - External tools via Model Context Protocol
2. **Workflow Tools** - Visual DAG-based workflows
3. **Default Tools** - Built-in app tools (web search, image generation, etc.)

**For details**: Load `references/tool-system.md` when implementing tools or understanding tool execution.

### API Patterns

Routes follow RESTful conventions with streaming-first architecture and defensive programming using `safe()` wrapper.

**For details**: Load `references/api-architecture.md` when building API routes or implementing streaming.

### Component Philosophy

Components organized by feature using compound component pattern. Tools execution separated from rendering.

**For details**: Load `references/component-patterns.md` when building UI components.

### Database & Repository Pattern

All database access abstracted through repository classes using Drizzle ORM.

**For details**: Load `references/database-patterns.md` when implementing database queries.

---

## Top 5 Errors (Must Know)

### Error #1: Forgetting Auth Checks in Server Actions

**Error**: Unauthorized users accessing protected actions
**Why**: Manual auth implementation is inconsistent
**Prevention**: Use `validatedActionWithUser` or `validatedActionWithAdminPermission`

```typescript
// ❌ BAD: Manual auth check
export async function updateProfile(data: ProfileData) {
  const session = await getSession()
  if (!session) throw new Error("Unauthorized")
  // ... rest of logic
}

// ✅ GOOD: Use validator
export const updateProfile = validatedActionWithUser(
  profileSchema,
  async (data, formData, user) => {
    // user is guaranteed to exist, auto-error handling
  }
)
```

### Error #2: Tool Type Mismatches

**Error**: Runtime type errors when executing tools
**Why**: Not checking tool type before execution
**Prevention**: Use branded type tags for runtime narrowing

```typescript
// ❌ BAD: Assuming tool type
const result = await executeMcpTool(tool)

// ✅ GOOD: Check tool type
if (VercelAIMcpToolTag.isMaybe(tool)) {
  const result = await executeMcpTool(tool)
} else if (VercelAIWorkflowToolTag.isMaybe(tool)) {
  const result = await executeWorkflowTool(tool)
}
```

### Error #3: FormData Parsing Errors

**Error**: Inconsistent error handling for form submissions
**Why**: Manual FormData parsing with ad-hoc validation
**Prevention**: Validators handle parsing automatically

```typescript
// ❌ BAD: Manual parsing
const name = formData.get("name") as string
if (!name) throw new Error("Name required")

// ✅ GOOD: Validator with Zod
const schema = z.object({ name: z.string().min(1) })
export const action = validatedAction(schema, async (data) => {
  // data.name is validated and typed
})
```

### Error #4: Cross-Field Validation Issues

**Error**: Password mismatch validation not working
**Why**: Separate validation for related fields
**Prevention**: Use Zod `superRefine`

```typescript
// ❌ BAD: Separate checks
if (data.password !== data.confirmPassword) { /* error */ }

// ✅ GOOD: Zod superRefine
const schema = z.object({
  password: z.string(),
  confirmPassword: z.string()
}).superRefine((data, ctx) => {
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "Passwords don't match",
      path: ["confirmPassword"]
    })
  }
})
```

### Error #5: Zustand State Mutation

**Error**: State updates not triggering re-renders
**Why**: Mutating state directly instead of creating new objects
**Prevention**: Use shallow updates with spread operator

```typescript
// ❌ BAD: Direct mutation
set((state) => {
  state.user.name = "New Name" // Mutation!
})

// ✅ GOOD: Shallow update
set((state) => ({
  user: { ...state.user, name: "New Name" }
}))
```

**For all errors**: Load `references/common-errors.md` when debugging issues beyond the top 5.

---

## Critical Rules

### Always Do

✅ Use `validatedActionWithUser` or `validatedActionWithAdminPermission` for server actions
✅ Check tool types with branded type tags before execution
✅ Use Zod `superRefine` for cross-field validation
✅ Add unit tests (happy path + one failure mode)
✅ Run `pnpm check` before PR submission
✅ Include visual documentation for UI changes
✅ Use Conventional Commit format for PR titles
✅ Run E2E tests when touching critical flows

### Never Do

❌ Implement server actions without auth validators
❌ Assume tool type without runtime check
❌ Parse FormData manually (use validators)
❌ Mutate Zustand state directly (use shallow updates)
❌ Skip first-user tests on clean database
❌ Commit without running `pnpm check`
❌ Submit PR without visual docs (if UI change)
❌ Use non-conventional commit format

---

## When to Load References

Load reference files when working on specific aspects of better-chatbot:

### API Architecture (`references/api-architecture.md`)
Load when:
- Implementing new API routes or endpoints
- Understanding route handler patterns
- Working with streaming responses
- Implementing defensive programming with safe()
- Troubleshooting API-related issues
- Building shared business logic

### Tool System (`references/tool-system.md`)
Load when:
- Adding new MCP tools
- Creating workflow tools
- Understanding tool lifecycle
- Debugging tool execution
- Implementing tool filtering or mentions
- Working with the three-tier tool architecture

### Component Patterns (`references/component-patterns.md`)
Load when:
- Building new UI components
- Understanding compound component pattern
- Implementing state management
- Working with Zustand stores
- Designing component APIs
- Separating tool execution from rendering

### Database Patterns (`references/database-patterns.md`)
Load when:
- Creating new repository classes
- Writing complex database queries
- Implementing transactions
- Understanding the repository pattern
- Troubleshooting database issues
- Working with Drizzle ORM

### Architectural Principl