letsbe-hub/CLAUDE.md

# CLAUDE.md — LetsBe Hub

## Purpose

You are the engineering assistant for the LetsBe Hub Dashboard.
This is the admin dashboard and API for managing the LetsBe Cloud platform.

The Hub provides:

- **Admin Dashboard**: Next.js admin UI for platform management
- **Customer Management**: Create/manage customers and subscriptions
- **Order Management**: Process and track provisioning orders
- **Server Monitoring**: View and manage tenant servers
- **Token Usage Tracking**: Monitor AI token consumption

## Tech Stack

- **Next.js 15** (App Router)
- **TypeScript** (strict mode)
- **Prisma** (PostgreSQL ORM)
- **TanStack Query** (React Query v5)
- **Tailwind CSS** + shadcn/ui components
- **NextAuth.js** (authentication)

## Project Structure

```
src/
├── app/                    # Next.js App Router
│   ├── admin/             # Admin dashboard pages
│   │   ├── customers/     # Customer management
│   │   ├── orders/        # Order management
│   │   ├── servers/       # Server monitoring
│   │   └── layout.tsx     # Admin layout with sidebar
│   ├── api/v1/            # API routes
│   │   ├── admin/         # Admin API endpoints
│   │   └── public/        # Public API endpoints
│   └── (auth)/            # Authentication pages
├── components/
│   ├── admin/             # Admin-specific components
│   └── ui/                # Reusable UI components
├── hooks/                 # React Query hooks
├── lib/                   # Utilities and shared code
│   └── prisma.ts          # Prisma client singleton
└── types/                 # TypeScript type definitions
```

## API Routes

### Admin Endpoints (authenticated)

```
# Customers
GET    /api/v1/admin/customers         # List customers
GET    /api/v1/admin/customers/[id]    # Get customer detail
PATCH  /api/v1/admin/customers/[id]    # Update customer

# Orders
GET    /api/v1/admin/orders            # List orders
POST   /api/v1/admin/orders            # Create order
GET    /api/v1/admin/orders/[id]       # Get order detail
PATCH  /api/v1/admin/orders/[id]       # Update order
GET    /api/v1/admin/orders/[id]/logs  # Get provisioning logs (SSE)

# Servers
GET    /api/v1/admin/servers           # List servers (derived from orders)

# Dashboard
GET    /api/v1/admin/dashboard/stats   # Dashboard statistics
```

## Development Commands

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Run database migrations
npx prisma migrate dev

# Generate Prisma client
npx prisma generate

# Seed database
npm run db:seed

# Type checking
npm run typecheck

# Build for production
npm run build

# App available at http://localhost:3000
```

## Key Patterns

### React Query Hooks

All data fetching uses React Query hooks in `src/hooks/`:
- `useCustomers()`, `useCustomer(id)` - Customer data
- `useOrders()`, `useOrder(id)` - Order data
- `useServers()` - Server list
- `useDashboardStats()` - Dashboard metrics

Mutations follow the pattern:
- `useCreateOrder()`, `useUpdateOrder()`
- Automatic cache invalidation via `queryClient.invalidateQueries()`

### API Route Pattern

```typescript
export async function GET(request: NextRequest) {
  // Parse query params
  const searchParams = request.nextUrl.searchParams

  // Database query with Prisma
  const data = await prisma.model.findMany({...})

  // Return JSON response
  return NextResponse.json(data)
}
```

### Component Pattern

```typescript
'use client'

export function MyComponent() {
  const { data, isLoading, error } = useMyData()

  if (isLoading) return <Skeleton />
  if (error) return <ErrorMessage error={error} />

  return <div>...</div>
}
```

## Coding Conventions

- Use `'use client'` directive for client components
- All API routes return `NextResponse.json()`
- Use Prisma for all database operations
- Follow existing shadcn/ui component patterns
- Use React Query for server state management
- TypeScript strict mode - no `any` types