better-chatbot-patterns

# better-chatbot-patterns

**Status**: Production Ready
**Last Updated**: 2025-11-21
**Dependencies**: None
**Latest Versions**: next@16.0.3, ai@5.0.98, zod@3.24.2, zustand@5.0.8

---

## Overview

This skill extracts reusable patterns from the better-chatbot project for use in custom AI chatbot implementations. Unlike the `better-chatbot` skill (which teaches project conventions), this skill provides **portable templates** you can adapt to any project.

**Patterns included**:
1. Server action validators (auth, validation, FormData)
2. Tool abstraction system (multi-type tool handling)
3. Multi-AI provider setup
4. Workflow execution patterns
5. State management conventions

---

## Pattern 1: Server Action Validators

**For complete implementation**: Load `references/server-action-patterns.md` when implementing server action validators, auth validation, or FormData parsing.

**What it solves**: Inconsistent auth checks, repeated FormData parsing boilerplate, non-standard error handling, and type safety issues in server actions.

**Three validator patterns**:
1. `validatedAction` - Simple validation (no auth)
2. `validatedActionWithUser` - With user context (auth required)
3. `validatedActionWithPermission` - With permission checks (role-based)

**Quick example**:
```typescript
// Server action with automatic auth + validation
export const updateProfile = validatedActionWithUser(
  z.object({ name: z.string(), email: z.string().email() }),
  async (data, formData, user) => {
    // user is authenticated, data is validated
    await db.update(users).set(data).where(eq(users.id, user.id))
    return { success: true }
  }
)
```

**Adapt to your auth**: Better Auth, Clerk, Auth.js, or custom auth system.

---

## Pattern 2: Tool Abstraction System

**For complete implementation**: Load `references/tool-abstraction-patterns.md` when building multi-type tool systems, MCP integration, or extensible tool architectures.

**What it solves**: Type mismatches at runtime, repeat