---
name: zai-tooling-reference
description: "Complete z.ai tooling reference - Next.js 15/16, React 19, shadcn/ui, Prisma, WebSocket. AUTO-TRIGGERS when: Next.js setup, shadcn/ui components, Prisma schema, SQLite, WebSocket/Socket.io, Zustand state, TanStack Query, NextAuth, Tailwind CSS 4, Bun, full-stack development."
priority: 100
autoTrigger: true
triggers:
  - "Next.js"
  - "nextjs"
  - "shadcn"
  - "shadcn/ui"
  - "Prisma"
  - "SQLite"
  - "WebSocket"
  - "socket.io"
  - "real-time"
  - "Zustand"
  - "TanStack Query"
  - "react-query"
  - "NextAuth"
  - "authentication"
  - "Tailwind"
  - "Tailwind CSS 4"
  - "Bun"
  - "React 19"
  - "full-stack"
  - "frontend component"
  - "UI component"
  - "database schema"
---

# Z.AI Tooling Reference

Complete technical reference for the z.ai tooling codebase - a production-ready Next.js 15 application with AI capabilities.

**Codebase Location**: `~/reference-codebases/z-ai-tooling/`

---

## Tech Stack

| Category | Technology | Version |
|----------|------------|---------|
| Framework | Next.js | 16.1.1 |
| React | React | 19.0.0 |
| Language | TypeScript | 5.x |
| Styling | Tailwind CSS | 4.x |
| UI Components | shadcn/ui (Radix) | Latest |
| Database | Prisma + SQLite | 6.11.1 |
| State | Zustand | 5.0.6 |
| Data Fetching | TanStack Query | 5.82.0 |
| AI SDK | z-ai-web-dev-sdk | 0.0.16 |
| Auth | NextAuth | 4.24.11 |
| Package Manager | Bun | 1.3.4+ |

---

## Project Structure

```
z-ai-tooling/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/route.ts        # API endpoints
│   │   ├── page.tsx            # Main page
│   │   ├── layout.tsx          # Root layout
│   │   └── globals.css         # Global styles
│   ├── components/
│   │   └── ui/                 # shadcn/ui components (50+)
│   ├── hooks/
│   │   ├── use-mobile.ts       # Mobile detection
│   │   └── use-toast.ts        # Toast notifications
│   └── lib/
│       ├── db.ts               # Prisma client singleton
│       └── utils.ts            # Utility functions (cn, etc.)
├── prisma/
│   └── schema.prisma           # Database schema
├── examples/
│   └── websocket/              # WebSocket implementation
├── db/
│   └── custom.db               # SQLite database
├── download/                   # Output directory for generated files
└── .zscripts/                  # Build and start scripts
```

---

## Database Patterns

### Prisma Schema

```prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}
```

### Database Client Singleton

```typescript
// src/lib/db.ts
import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const db =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: ['query'],
  })

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = db
```

### Database Commands

```bash
bun run db:push      # Push schema changes
bun run db:generate  # Generate Prisma client
bun run db:migrate   # Create migration
bun run db:reset     # Reset database
```

---

## WebSocket Integration

### Server (Socket.io)

```typescript
// examples/websocket/server.ts
import { createServer } from 'http'
import { Server } from 'socket.io'

const httpServer = createServer()
const io = new Server(httpServer, {
  path: '/',
  cors: { origin: "*", methods: ["GET", "POST"] },
  pingTimeout: 60000,
  pingInterval: 25000,
})

interface User { id: string; username: string }
interface Message {
  id: string
  username: string
  content: string
  timestamp: Date
  type: 'user' | 'system'
}

const users = new Map<string, User>()

io.on('connection', (socket) => {
  socket.on('join', (data: { username: string }) => {
    const user: User = { id: socket.id, username: data.username }
    users.set(socket.id, user)
    io.emit('user-joined', { user, message: createSystemMessage(`${data.username} joined`) })
    socket.emit('users-list', { users: Array.from(users.values()) })
  })

  socket.on('message', (data: { content: string; username: string }) => {
    const message = createUserMessage(data.username, data.content)
    io.emit('message', message)
  })

  socket.on('disconnect', () => {
    const user = users.get(socket.id)
    if (user) {
      users.delete(socket.id)
      io.emit('user-left', { user, message: createSystemMessage(`${user.username} left`) })
    }
  })
})

httpServer.listen(3003)
```

### Client (React)

```typescript
// examples/websocket/frontend.tsx
'use client';

import { useEffect, useState } from 'react';
import { io } from 'socket.io-client';

export default function SocketDemo() {
  const [socket, setSocket] = useState<any>(null);
  const [isConnected, setIsConnected] = useState(false);

  useEffect(() => {
    // Use XTransformPort instead of direct port
    const socketInstance = io('/?XTransformPort=3003', {
      transports: ['websocket', 'polling'],
      reconnection: true,
      reconnectionAttempts: 5,
      reconnectionDelay: 1000,
    });

    setSocket(socketInstance);

    socketInstance.on('connect', () => setIsConnected(true));
    socketInstance.on('disconnect', () => setIsConnected(false));
    socketInstance.on('message', (msg) => { /* handle message */ });

    return () => socketInstance.disconnect();
  }, []);

  return ( /* JSX */ );
}
```

---

## Available UI Components (shadcn/ui)

50+ components available in `src/components/ui/`:

| Component | File | Purpose |
|-----------|------|---------|
| Button | button.tsx | Primary actions |
| Input | input.tsx | Text input |
| Card | card.tsx | Container |
| Dialog | dialog.tsx | Modal |
| Sheet | sheet.tsx | Side panel |
| Toast | toast.tsx | Notifications |
| Select | select.tsx | Dropdown |
| Table | table.tsx | Data tables |
| Tabs | tabs.tsx | Tab navigation |
| Form | form.tsx | Form handling |
| Chart | chart.tsx | Charts (Recharts) |
| Calendar | calendar.tsx | Date picker |
| Command | command.tsx | Command palette |
| Drawer | drawer.tsx | Mobile drawer |
| Sidebar | sidebar.tsx | Navigation sidebar |
| Carousel | carousel.tsx | Image carousel |
| Accordion | accordion.tsx | Collapsible content |
| Avatar | avatar.tsx | User avatars |
| Badge | badge.tsx | Status indicators |
| Checkbox | checkbox.tsx | Boolean input |
| Slider | slider.tsx | Range input |
| Switch | switch.tsx | Toggle |
| Tooltip | tooltip.tsx | Hover info |
| Progress | progress.tsx | Loading indicator |
| Skeleton | skeleton.tsx | Loading placeholder |
| ScrollArea | scroll-area.tsx | Scrollable container |

---

## Dependencies Overview

### Core Dependencies

```json
{
  "next": "^16.1.1",
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "z-ai-web-dev-sdk": "^0.0.16",
  "prisma": "^6.11.1",
  "@prisma/client": "^6.11.1"
}
```

### UI Dependencies

```json
{
  "@radix-ui/react-*": "latest",  // All Radix primitives
  "lucide-react": "^0.525.0",     // Icons
  "framer-motion": "^12.23.2",    // Animations
  "class-variance-authority": "^0.7.1",
  "clsx": "^2.1.1",
  "tailwind-merge": "^3.3.1"
}
```

### State & Data

```json
{
  "zustand": "^5.0.6",
  "@tanstack/react-query": "^5.82.0",
  "@tanstack/react-table": "^8.21.3",
  "zod": "^4.0.2",
  "react-hook-form": "^7.60.0"
}
```

### Special Features

```json
{
  "next-auth": "^4.24.11",       // Authentication
  "next-intl": "^4.3.4",         // Internationalization
  "next-themes": "^0.4.6",       // Dark mode
  "recharts": "^2.15.4",         // Charts
  "@mdxeditor/editor": "^3.39.1", // MDX editing
  "sharp": "^0.34.3"             // Image optimization
}
```

---

## Scripts

```bash
# Development
bun run dev       # Start on port 3000 with logging

# Production
bun run build     # Build with standalone output
bun run start     # Run production server

# Database
bun run db:push      # Push schema
bun run db:generate  # Generate client
bun run db:migrate   # Create migration
bun run db:reset     # Reset database

# Quality
bun run lint      # ESLint check
```

---

## File Output Pattern

Generated files are saved to:
```
/home/z/my-project/download/
```

Or in this reference codebase:
```
~/reference-codebases/z-ai-tooling/download/
```

---

## Key Patterns

### 1. Prisma Singleton
Prevents multiple PrismaClient instances in development.

### 2. WebSocket Port Transformation
Use `XTransformPort` query param instead of direct port numbers.

### 3. Component Structure
All UI components use:
- `cva` (class-variance-authority) for variants
- `cn` utility for class merging
- Radix primitives for accessibility

### 4. API Routes
```typescript
// src/app/api/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "Hello, world!" });
}
```

### 5. Backend-Only SDK Usage
`z-ai-web-dev-sdk` MUST only be used in:
- API routes (`src/app/api/`)
- Server components
- Server actions

---

## When to Use This Reference

1. **Building Next.js 15 apps**: Project structure and patterns
2. **shadcn/ui implementation**: Component usage examples
3. **WebSocket integration**: Real-time features
4. **Prisma + SQLite**: Database patterns
5. **AI SDK integration**: z-ai-web-dev-sdk patterns
6. **Production deployment**: Build and start scripts

---

## Quick Commands

```bash
# Navigate to reference codebase
cd ~/reference-codebases/z-ai-tooling

# Install dependencies
bun install

# Start development
bun run dev

# Check components
ls src/components/ui/
```

---

*Reference codebase copied from: C:\Users\admin\Documents\trae_projects\Skills and Agents\z.ai tooling*