better-chatbot

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

# 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

// ❌ 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

// ❌ 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

// ❌ 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

// ❌ 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

// ❌ 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