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 Principles (

references/architectural-principles.md

)

Load when:

• Making architectural decisions
• Understanding design philosophy
• Implementing progressive enhancement
• Following streaming-first patterns
• Ensuring defensive programming
• Understanding DRY principle application

Extension Points (

references/extension-points.md

)

Load when:

• Extending the chatbot with custom features
• Adding new tool types
• Customizing existing behavior
• Understanding plugin architecture
• Integrating external services

UX Patterns (

references/ux-patterns.md

)

Load when:

• Implementing @mention functionality
• Understanding UX patterns
• Working with multi-model support
• Designing interaction flows
• Building chat UI components

Templates (

references/templates.md

)

Load when:

• Adding new routes, tools, or components
• Following code templates
• Understanding complete implementation examples
• Starting new features from scratch
• Implementing standard patterns

Server Actions (

references/server-actions.md

)

Load when:

• Implementing server actions
• Understanding action validators
• Following server-side validation patterns
• Troubleshooting server action issues
• Working with FormData

Common Errors (

references/common-errors.md

)

Load when:

• Debugging issues beyond the top 5 errors
• Encountering specific error messages
• Understanding error patterns
• Looking for solutions to common problems
• Preventing known issues

Repository Guidelines (

references/AGENTS.md

)

Load when:

• Understanding project structure
• Following coding conventions
• Setting up development environment
• Running tests or builds
• Understanding commit/PR guidelines

Contributing (

references/CONTRIBUTING.md

)

Load when:

• Preparing to contribute
• Understanding PR process
• Following commit message conventions
• Submitting pull requests
• Adding visual documentation

---

Using Bundled Resources

This skill includes 12 reference files:

Technical References (10 files):

• api-architecture.md

  - API patterns and route handlers

• tool-system.md

  - Three-tier tool architecture

• component-patterns.md

  - UI component design

• database-patterns.md

  - Repository pattern and Drizzle ORM

• architectural-principles.md

  - Design philosophy

• extension-points.md

  - How to extend the system

• ux-patterns.md

  - UX patterns and @mentions

• templates.md

  - Code templates for routes/tools/components

• server-actions.md

  - Server action validators

• common-errors.md

  - Complete error catalog

Repository References (2 files):

• AGENTS.md

  - Repository structure and development commands

• CONTRIBUTING.md

  - Contribution workflow and PR guidelines

Load references on-demand when specific knowledge is needed. See "When to Load References" section for triggers.

---

Dependencies

Core:

• Next.js 15+ (App Router)
• Vercel AI SDK 5+
• Better Auth 1.3+
• Drizzle ORM 0.40+
• PostgreSQL

Testing:

• Vitest (unit tests)
• Playwright (E2E tests)

Tools:

• TypeScript 5+
• Biome (formatting + linting)
• pnpm 8+

---

Official Documentation

• Repository: https://github.com/cgoinglove/better-chatbot
• Vercel AI SDK: https://sdk.vercel.ai/docs
• Better Auth: https://www.better-auth.com/docs
• Drizzle ORM: https://orm.drizzle.team/docs/overview
• MCP Spec: https://modelcontextprotocol.io/introduction

---

Production Example

This skill is based on the production better-chatbot repository with 48 E2E tests covering core functionality, active development, and growing community contributions.

---

Last verified: 2025-12-17 | Version: 3.0.0