Claude Code Templates

project-template/
├── CLAUDE.md              # Główny plik konfiguracyjny dla Claude
├── .cursor/
│   └── rules.md           # Cursor-specific rules (krótsze)
├── src/
│   ├── components/        # React components
│   ├── hooks/             # Custom hooks
│   ├── lib/               # Utilities i konfiguracje
│   ├── types/             # TypeScript types
│   └── app/               # Next.js App Router pages
├── docs/
│   ├── ARCHITECTURE.md    # Szczegółowy opis architektury
│   └── API.md             # Dokumentacja API
├── scripts/
│   └── setup.sh           # Setup script dla nowych devów
├── .env.example           # Template zmiennych środowiskowych
└── package.json

# Project: [Nazwa Projektu]

## Overview
[Nazwa] to [krótki opis - 1-2 zdania]. Aplikacja służy do [główny cel].

## Tech Stack
- **Framework**: Next.js 15 (App Router)
- **Language**: TypeScript 5.x (strict mode)
- **Database**: PostgreSQL + Prisma ORM
- **Auth**: NextAuth.js v5 (Auth.js)
- **Styling**: Tailwind CSS + shadcn/ui
- **State**: React Query (TanStack Query) + Zustand
- **Testing**: Vitest + Testing Library
- **Deployment**: Vercel

## Directory Structure
\`\`\`
src/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Auth group (login, register)
│   ├── (dashboard)/       # Protected dashboard pages
│   ├── api/               # API routes
│   │   ├── auth/         # NextAuth endpoints
│   │   └── trpc/         # tRPC router (jeśli używany)
│   └── layout.tsx         # Root layout
├── components/
│   ├── ui/                # shadcn/ui components
│   ├── forms/             # Form components
│   └── [feature]/         # Feature-specific components
├── hooks/                  # Custom React hooks
├── lib/
│   ├── prisma.ts          # Prisma client singleton
│   ├── auth.ts            # Auth configuration
│   └── utils.ts           # Utility functions
├── types/                  # TypeScript type definitions
└── server/                 # Server-side code
    ├── actions/           # Server Actions
    └── db/                # Database queries
\`\`\`

## Commands
\`\`\`bash
npm run dev          # Start dev server (port 3000)
npm run build        # Production build
npm run test         # Run tests with Vitest
npm run lint         # ESLint check
npm run db:push      # Push Prisma schema to DB
npm run db:studio    # Open Prisma Studio
npm run db:seed      # Seed database
\`\`\`

## Conventions

### Naming
- **Components**: PascalCase (UserProfile.tsx)
- **Hooks**: camelCase with "use" prefix (useAuth.ts)
- **Utils**: camelCase (formatDate.ts)
- **Types**: PascalCase with "I" prefix for interfaces (IUser)
- **Constants**: SCREAMING_SNAKE_CASE

### Components
- Use functional components with TypeScript
- Prefer Server Components where possible
- Keep components under 150 lines
- Extract logic to custom hooks
- Use composition over props drilling

### Imports
- Use absolute imports with @/ alias
- Group imports: react → next → external → internal → types
- Prefer named exports over default exports

### Error Handling
- Use Result pattern for expected errors
- Throw only for unexpected errors
- Always handle loading and error states in UI
- Use error boundaries for component errors

### Database
- Use Prisma transactions for multi-step operations
- Soft delete where appropriate (deletedAt column)
- Index foreign keys and commonly queried fields

## Common Tasks

### Adding a new page
1. Create file in `src/app/(group)/page-name/page.tsx`
2. Add metadata export for SEO
3. Create Server Component, fetch data at top level
4. Use Client Components only for interactivity

### Adding a new API endpoint
1. Create `src/app/api/[endpoint]/route.ts`
2. Export named functions (GET, POST, PUT, DELETE)
3. Use Zod for request validation
4. Return NextResponse.json() with proper status codes

### Adding a Server Action
1. Create in `src/server/actions/[feature].ts`
2. Add "use server" directive at top
3. Use revalidatePath/revalidateTag for cache invalidation
4. Return { success: boolean, data?: T, error?: string }

### Creating a form
1. Use react-hook-form + zod for validation
2. Create schema in `src/lib/validations/[feature].ts`
3. Use Server Action for submission
4. Show loading state during submission
5. Display validation errors inline

### Database changes
1. Update `prisma/schema.prisma`
2. Run `npm run db:push` (dev) or create migration
3. Update related TypeScript types
4. Update affected components

## Architecture Decisions

### Why App Router over Pages Router?
- Better DX with Server Components
- Built-in layouts and loading states
- Improved data fetching patterns
- Future-proof architecture

### Why Prisma over raw SQL?
- Type-safe queries
- Auto-generated types
- Easy migrations
- Great DX with Prisma Studio

### Why Zustand over Redux?
- Simpler API for this project size
- Less boilerplate
- Works well with Server Components
- TypeScript support out of the box

## Environment Variables
Required variables (see .env.example):
- DATABASE_URL - PostgreSQL connection string
- NEXTAUTH_SECRET - Auth.js secret
- NEXTAUTH_URL - Base URL for auth callbacks

## Notes for AI
- Always use TypeScript strict mode
- Prefer async/await over .then()
- Use early returns for guard clauses
- Add JSDoc comments for exported functions
- Consider mobile responsiveness
- Follow accessibility best practices (ARIA, semantic HTML)

# Project: [API Name]

## Overview
[Nazwa] API to backend service dla [opis]. Obsługuje [główne funkcjonalności].

## Tech Stack
- **Framework**: NestJS 10.x
- **Language**: TypeScript 5.x (strict)
- **Database**: PostgreSQL + TypeORM
- **Cache**: Redis
- **Queue**: Bull (Redis-based)
- **Auth**: JWT + Passport
- **Docs**: Swagger/OpenAPI
- **Testing**: Jest + Supertest

## Directory Structure
\`\`\`
src/
├── modules/               # Feature modules
│   ├── auth/
│   │   ├── auth.module.ts
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   ├── strategies/    # Passport strategies
│   │   ├── guards/        # Auth guards
│   │   └── dto/           # Data Transfer Objects
│   ├── users/
│   └── [feature]/
├── common/
│   ├── decorators/        # Custom decorators
│   ├── filters/           # Exception filters
│   ├── guards/            # Global guards
│   ├── interceptors/      # Interceptors
│   └── pipes/             # Validation pipes
├── config/                # Configuration modules
├── database/
│   ├── entities/          # TypeORM entities
│   ├── migrations/        # Database migrations
│   └── seeds/             # Seed data
└── main.ts
\`\`\`

## Commands
\`\`\`bash
yarn start:dev       # Start with hot reload
yarn build           # Production build
yarn start:prod      # Start production server
yarn test            # Run unit tests
yarn test:e2e        # Run E2E tests
yarn migration:run   # Run pending migrations
yarn migration:create # Create new migration
\`\`\`

## Conventions

### Module Structure
Każdy feature module zawiera:
- `.module.ts` - Module definition
- `.controller.ts` - HTTP endpoints
- `.service.ts` - Business logic
- `/dto` - Request/Response DTOs
- `/entities` - TypeORM entities (jeśli potrzebne)

### Naming
- **Modules**: singular (user.module.ts, not users)
- **Controllers**: plural endpoints (/users, not /user)
- **Services**: singular (UserService)
- **Entities**: singular, PascalCase (User)
- **DTOs**: CreateUserDto, UpdateUserDto, UserResponseDto

### Error Handling
- Throw NestJS HttpExceptions
- Use global exception filter for consistency
- Log errors with correlation ID
- Return standardized error response:
\`\`\`json
{ "statusCode": 400, "message": "...", "error": "Bad Request" }
\`\`\`

### Validation
- Use class-validator on all DTOs
- Use class-transformer for type conversion
- Enable whitelist to strip unknown properties
- Use custom validation decorators when needed

## API Response Format
\`\`\`typescript
// Success
{
  "data": T,
  "meta": { "page": 1, "total": 100 }
}

// Error
{
  "statusCode": number,
  "message": string,
  "error": string,
  "timestamp": string,
  "path": string
}
\`\`\`

## Common Tasks

### Adding a new module
\`\`\`bash
nest g module modules/[name]
nest g controller modules/[name]
nest g service modules/[name]
\`\`\`

### Adding a new endpoint
1. Add method to controller with decorators
2. Create DTO in `/dto` folder
3. Implement logic in service
4. Add Swagger decorators for docs
5. Write tests

### Database migration
1. Make changes to entity
2. Run `yarn migration:generate src/database/migrations/[name]`
3. Review generated SQL
4. Run `yarn migration:run`

## Environment Variables
- DATABASE_URL
- JWT_SECRET
- JWT_EXPIRES_IN
- REDIS_URL
- CORS_ORIGINS

# Project: [Nazwa Monorepo]

## Overview
Monorepo zawierające frontend (Next.js), backend (NestJS) i shared packages.

## Tech Stack
- **Monorepo**: Turborepo + pnpm workspaces
- **Frontend**: Next.js 15, TypeScript, Tailwind
- **Backend**: NestJS 10, TypeScript, PostgreSQL
- **Shared**: TypeScript types, validation schemas
- **API**: REST + tRPC (optional)

## Workspace Structure
\`\`\`
/
├── apps/
│   ├── web/               # Next.js frontend
│   │   ├── src/
│   │   └── package.json
│   └── api/               # NestJS backend
│       ├── src/
│       └── package.json
├── packages/
│   ├── ui/                # Shared React components
│   │   ├── src/
│   │   └── package.json
│   ├── db/                # Database client (Prisma)
│   │   ├── prisma/
│   │   └── package.json
│   ├── types/             # Shared TypeScript types
│   │   ├── src/
│   │   └── package.json
│   └── config/            # Shared configs (ESLint, TSConfig)
│       ├── eslint/
│       └── typescript/
├── turbo.json             # Turborepo config
├── pnpm-workspace.yaml    # Workspace definition
└── package.json           # Root package.json
\`\`\`

## Commands (root level)
\`\`\`bash
pnpm install         # Install all dependencies
pnpm dev             # Start all apps in dev mode
pnpm build           # Build all packages and apps
pnpm lint            # Lint everything
pnpm test            # Run all tests
pnpm db:push         # Push Prisma schema
pnpm db:generate     # Generate Prisma client
\`\`\`

## Workspace-specific commands
\`\`\`bash
# Run command in specific workspace
pnpm --filter web dev
pnpm --filter api test
pnpm --filter @repo/ui build
\`\`\`

## Inter-package imports
\`\`\`typescript
// In apps/web
import { Button } from "@repo/ui"
import { User } from "@repo/types"
import { prisma } from "@repo/db"
\`\`\`

## Conventions

### Package naming
- Apps: web, api, admin, mobile
- Packages: @repo/[name] (ui, types, db, config)

### Shared code rules
- Types that both frontend and backend use → @repo/types
- Validation schemas (Zod) → @repo/types
- React components → @repo/ui
- Database client → @repo/db

### Dependency management
- Shared deps in root package.json
- App-specific deps in app's package.json
- Use workspace:* for internal packages

## Notes for AI
- Check which workspace you're in before making changes
- Use correct package names in imports
- Consider if code should be shared or app-specific
- Run commands from root with --filter for specific apps

# Project Rules

Tech: Next.js 15 App Router, TypeScript strict, Tailwind, shadcn/ui, Prisma

## Structure
- src/app/ - pages and layouts
- src/components/ - React components (prefer Server Components)
- src/lib/ - utilities and configs
- src/server/actions/ - Server Actions

## Conventions
- TypeScript strict, no any
- Named exports, absolute imports (@/)
- Components < 150 lines
- Error handling with Result pattern
- Mobile-first, accessible

## Commands
- npm run dev (port 3000)
- npm run db:push (Prisma)

## When creating components
1. Check if similar exists in src/components/ui
2. Use shadcn/ui patterns
3. Add proper TypeScript types
4. Consider Server vs Client Component

## Environment Setup

### Development
\`\`\`bash
cp .env.example .env.local
# Edit .env.local with your values
\`\`\`

### Required Variables
| Variable | Description | Example |
|----------|-------------|---------|
| DATABASE_URL | PostgreSQL connection | postgresql://... |
| NEXTAUTH_SECRET | Auth secret (32+ chars) | openssl rand -base64 32 |
| NEXTAUTH_URL | App URL | http://localhost:3000 |
| STRIPE_SECRET_KEY | Stripe API key | sk_test_... |

### Optional Variables
| Variable | Description | Default |
|----------|-------------|---------|
| LOG_LEVEL | Logging verbosity | info |
| ENABLE_ANALYTICS | Enable tracking | false |

### Generating secrets
\`\`\`bash
# Generate NEXTAUTH_SECRET
openssl rand -base64 32

# Generate API key
openssl rand -hex 24
\`\`\`

## Testing

### File naming
- Unit tests: `[name].test.ts`
- Integration tests: `[name].integration.test.ts`
- E2E tests: `[name].e2e.ts`

### Test structure
\`\`\`typescript
describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid data', async () => {
      // Arrange
      const input = { email: 'test@test.com', name: 'Test' }

      // Act
      const result = await userService.createUser(input)

      // Assert
      expect(result).toMatchObject(input)
    })

    it('should throw on duplicate email', async () => {
      // ...
    })
  })
})
\`\`\`

### Mocking
- Use Vitest's vi.mock() for modules
- Create fixtures in `__fixtures__/`
- Use factories for test data

### Coverage requirements
- Minimum 80% coverage for new code
- 100% coverage for critical paths (auth, payments)

## CI/CD Pipeline

### GitHub Actions Workflow
\`\`\`yaml
# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
      - run: pnpm install
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build
\`\`\`

### Deployment
- **Production**: main branch → Vercel
- **Preview**: PR branches → Vercel Preview

### Pre-commit hooks (Husky)
- Lint staged files
- Run affected tests
- Type check

### Branch naming
- feature/[ticket]-description
- fix/[ticket]-description
- chore/description

## Checklist do CLAUDE.md

### Podstawowe
- [ ] Nazwa i opis projektu
- [ ] Główny tech stack z wersjami
- [ ] Struktura folderów
- [ ] Podstawowe komendy

### Konwencje
- [ ] Styl nazewnictwa (camelCase, PascalCase, etc.)
- [ ] Preferowane wzorce (hooks vs HOC, etc.)
- [ ] Import conventions
- [ ] Error handling approach

### Specyficzne dla projektu
- [ ] Niestandardowe abstrakcje
- [ ] Utility functions do reuse
- [ ] Common gotchas
- [ ] Performance considerations

# Project Name

## Stack
Next.js 15, TypeScript, Prisma, Tailwind

## Structure
- src/app - pages
- src/components - components
- src/lib - utilities

## Commands
npm run dev
npm run build

## Rules
- TypeScript strict mode
- Server Components preferred
- Tailwind for styling

## Learned rules
- Always use `prisma` singleton from `src/lib/prisma.ts`
- Forms use react-hook-form + zod, not native forms
- Images use next/image, not img tag
- Links use next/link, not anchor tags

project-template/
├── CLAUDE.md              # Main configuration file for Claude
├── .cursor/
│   └── rules.md           # Cursor-specific rules (shorter)
├── src/
│   ├── components/        # React components
│   ├── hooks/             # Custom hooks
│   ├── lib/               # Utilities and configurations
│   ├── types/             # TypeScript types
│   └── app/               # Next.js App Router pages
├── docs/
│   ├── ARCHITECTURE.md    # Detailed architecture description
│   └── API.md             # API documentation
├── scripts/
│   └── setup.sh           # Setup script for new devs
├── .env.example           # Environment variables template
└── package.json

# Project: [Project Name]

## Overview
[Name] is [short description - 1-2 sentences]. The application serves [main purpose].

## Tech Stack
- **Framework**: Next.js 15 (App Router)
- **Language**: TypeScript 5.x (strict mode)
- **Database**: PostgreSQL + Prisma ORM
- **Auth**: NextAuth.js v5 (Auth.js)
- **Styling**: Tailwind CSS + shadcn/ui
- **State**: React Query (TanStack Query) + Zustand
- **Testing**: Vitest + Testing Library
- **Deployment**: Vercel

## Directory Structure
\`\`\`
src/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Auth group (login, register)
│   ├── (dashboard)/       # Protected dashboard pages
│   ├── api/               # API routes
│   │   ├── auth/         # NextAuth endpoints
│   │   └── trpc/         # tRPC router (if used)
│   └── layout.tsx         # Root layout
├── components/
│   ├── ui/                # shadcn/ui components
│   ├── forms/             # Form components
│   └── [feature]/         # Feature-specific components
├── hooks/                  # Custom React hooks
├── lib/
│   ├── prisma.ts          # Prisma client singleton
│   ├── auth.ts            # Auth configuration
│   └── utils.ts           # Utility functions
├── types/                  # TypeScript type definitions
└── server/                 # Server-side code
    ├── actions/           # Server Actions
    └── db/                # Database queries
\`\`\`

## Commands
\`\`\`bash
npm run dev          # Start dev server (port 3000)
npm run build        # Production build
npm run test         # Run tests with Vitest
npm run lint         # ESLint check
npm run db:push      # Push Prisma schema to DB
npm run db:studio    # Open Prisma Studio
npm run db:seed      # Seed database
\`\`\`

## Conventions

### Naming
- **Components**: PascalCase (UserProfile.tsx)
- **Hooks**: camelCase with "use" prefix (useAuth.ts)
- **Utils**: camelCase (formatDate.ts)
- **Types**: PascalCase with "I" prefix for interfaces (IUser)
- **Constants**: SCREAMING_SNAKE_CASE

### Components
- Use functional components with TypeScript
- Prefer Server Components where possible
- Keep components under 150 lines
- Extract logic to custom hooks
- Use composition over props drilling

### Imports
- Use absolute imports with @/ alias
- Group imports: react → next → external → internal → types
- Prefer named exports over default exports

### Error Handling
- Use Result pattern for expected errors
- Throw only for unexpected errors
- Always handle loading and error states in UI
- Use error boundaries for component errors

### Database
- Use Prisma transactions for multi-step operations
- Soft delete where appropriate (deletedAt column)
- Index foreign keys and commonly queried fields

## Common Tasks

### Adding a new page
1. Create file in `src/app/(group)/page-name/page.tsx`
2. Add metadata export for SEO
3. Create Server Component, fetch data at top level
4. Use Client Components only for interactivity

### Adding a new API endpoint
1. Create `src/app/api/[endpoint]/route.ts`
2. Export named functions (GET, POST, PUT, DELETE)
3. Use Zod for request validation
4. Return NextResponse.json() with proper status codes

### Adding a Server Action
1. Create in `src/server/actions/[feature].ts`
2. Add "use server" directive at top
3. Use revalidatePath/revalidateTag for cache invalidation
4. Return { success: boolean, data?: T, error?: string }

### Creating a form
1. Use react-hook-form + zod for validation
2. Create schema in `src/lib/validations/[feature].ts`
3. Use Server Action for submission
4. Show loading state during submission
5. Display validation errors inline

### Database changes
1. Update `prisma/schema.prisma`
2. Run `npm run db:push` (dev) or create migration
3. Update related TypeScript types
4. Update affected components

## Architecture Decisions

### Why App Router over Pages Router?
- Better DX with Server Components
- Built-in layouts and loading states
- Improved data fetching patterns
- Future-proof architecture

### Why Prisma over raw SQL?
- Type-safe queries
- Auto-generated types
- Easy migrations
- Great DX with Prisma Studio

### Why Zustand over Redux?
- Simpler API for this project size
- Less boilerplate
- Works well with Server Components
- TypeScript support out of the box

## Environment Variables
Required variables (see .env.example):
- DATABASE_URL - PostgreSQL connection string
- NEXTAUTH_SECRET - Auth.js secret
- NEXTAUTH_URL - Base URL for auth callbacks

## Notes for AI
- Always use TypeScript strict mode
- Prefer async/await over .then()
- Use early returns for guard clauses
- Add JSDoc comments for exported functions
- Consider mobile responsiveness
- Follow accessibility best practices (ARIA, semantic HTML)

# Project: [API Name]

## Overview
[Name] API is a backend service for [description]. It handles [main functionalities].

## Tech Stack
- **Framework**: NestJS 10.x
- **Language**: TypeScript 5.x (strict)
- **Database**: PostgreSQL + TypeORM
- **Cache**: Redis
- **Queue**: Bull (Redis-based)
- **Auth**: JWT + Passport
- **Docs**: Swagger/OpenAPI
- **Testing**: Jest + Supertest

## Directory Structure
\`\`\`
src/
├── modules/               # Feature modules
│   ├── auth/
│   │   ├── auth.module.ts
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   ├── strategies/    # Passport strategies
│   │   ├── guards/        # Auth guards
│   │   └── dto/           # Data Transfer Objects
│   ├── users/
│   └── [feature]/
├── common/
│   ├── decorators/        # Custom decorators
│   ├── filters/           # Exception filters
│   ├── guards/            # Global guards
│   ├── interceptors/      # Interceptors
│   └── pipes/             # Validation pipes
├── config/                # Configuration modules
├── database/
│   ├── entities/          # TypeORM entities
│   ├── migrations/        # Database migrations
│   └── seeds/             # Seed data
└── main.ts
\`\`\`

## Commands
\`\`\`bash
yarn start:dev       # Start with hot reload
yarn build           # Production build
yarn start:prod      # Start production server
yarn test            # Run unit tests
yarn test:e2e        # Run E2E tests
yarn migration:run   # Run pending migrations
yarn migration:create # Create new migration
\`\`\`

## Conventions

### Module Structure
Each feature module contains:
- `.module.ts` - Module definition
- `.controller.ts` - HTTP endpoints
- `.service.ts` - Business logic
- `/dto` - Request/Response DTOs
- `/entities` - TypeORM entities (if needed)

### Naming
- **Modules**: singular (user.module.ts, not users)
- **Controllers**: plural endpoints (/users, not /user)
- **Services**: singular (UserService)
- **Entities**: singular, PascalCase (User)
- **DTOs**: CreateUserDto, UpdateUserDto, UserResponseDto

### Error Handling
- Throw NestJS HttpExceptions
- Use global exception filter for consistency
- Log errors with correlation ID
- Return standardized error response:
\`\`\`json
{ "statusCode": 400, "message": "...", "error": "Bad Request" }
\`\`\`

### Validation
- Use class-validator on all DTOs
- Use class-transformer for type conversion
- Enable whitelist to strip unknown properties
- Use custom validation decorators when needed

## API Response Format
\`\`\`typescript
// Success
{
  "data": T,
  "meta": { "page": 1, "total": 100 }
}

// Error
{
  "statusCode": number,
  "message": string,
  "error": string,
  "timestamp": string,
  "path": string
}
\`\`\`

## Common Tasks

### Adding a new module
\`\`\`bash
nest g module modules/[name]
nest g controller modules/[name]
nest g service modules/[name]
\`\`\`

### Adding a new endpoint
1. Add method to controller with decorators
2. Create DTO in `/dto` folder
3. Implement logic in service
4. Add Swagger decorators for docs
5. Write tests

### Database migration
1. Make changes to entity
2. Run `yarn migration:generate src/database/migrations/[name]`
3. Review generated SQL
4. Run `yarn migration:run`

## Environment Variables
- DATABASE_URL
- JWT_SECRET
- JWT_EXPIRES_IN
- REDIS_URL
- CORS_ORIGINS

# Project: [Monorepo Name]

## Overview
A monorepo containing a frontend (Next.js), backend (NestJS), and shared packages.

## Tech Stack
- **Monorepo**: Turborepo + pnpm workspaces
- **Frontend**: Next.js 15, TypeScript, Tailwind
- **Backend**: NestJS 10, TypeScript, PostgreSQL
- **Shared**: TypeScript types, validation schemas
- **API**: REST + tRPC (optional)

## Workspace Structure
\`\`\`
/
├── apps/
│   ├── web/               # Next.js frontend
│   │   ├── src/
│   │   └── package.json
│   └── api/               # NestJS backend
│       ├── src/
│       └── package.json
├── packages/
│   ├── ui/                # Shared React components
│   │   ├── src/
│   │   └── package.json
│   ├── db/                # Database client (Prisma)
│   │   ├── prisma/
│   │   └── package.json
│   ├── types/             # Shared TypeScript types
│   │   ├── src/
│   │   └── package.json
│   └── config/            # Shared configs (ESLint, TSConfig)
│       ├── eslint/
│       └── typescript/
├── turbo.json             # Turborepo config
├── pnpm-workspace.yaml    # Workspace definition
└── package.json           # Root package.json
\`\`\`

## Commands (root level)
\`\`\`bash
pnpm install         # Install all dependencies
pnpm dev             # Start all apps in dev mode
pnpm build           # Build all packages and apps
pnpm lint            # Lint everything
pnpm test            # Run all tests
pnpm db:push         # Push Prisma schema
pnpm db:generate     # Generate Prisma client
\`\`\`

## Workspace-specific commands
\`\`\`bash
# Run command in specific workspace
pnpm --filter web dev
pnpm --filter api test
pnpm --filter @repo/ui build
\`\`\`

## Inter-package imports
\`\`\`typescript
// In apps/web
import { Button } from "@repo/ui"
import { User } from "@repo/types"
import { prisma } from "@repo/db"
\`\`\`

## Conventions

### Package naming
- Apps: web, api, admin, mobile
- Packages: @repo/[name] (ui, types, db, config)

### Shared code rules
- Types that both frontend and backend use → @repo/types
- Validation schemas (Zod) → @repo/types
- React components → @repo/ui
- Database client → @repo/db

### Dependency management
- Shared deps in root package.json
- App-specific deps in app's package.json
- Use workspace:* for internal packages

## Notes for AI
- Check which workspace you're in before making changes
- Use correct package names in imports
- Consider if code should be shared or app-specific
- Run commands from root with --filter for specific apps

# Project Rules

Tech: Next.js 15 App Router, TypeScript strict, Tailwind, shadcn/ui, Prisma

## Structure
- src/app/ - pages and layouts
- src/components/ - React components (prefer Server Components)
- src/lib/ - utilities and configs
- src/server/actions/ - Server Actions

## Conventions
- TypeScript strict, no any
- Named exports, absolute imports (@/)
- Components < 150 lines
- Error handling with Result pattern
- Mobile-first, accessible

## Commands
- npm run dev (port 3000)
- npm run db:push (Prisma)

## When creating components
1. Check if similar exists in src/components/ui
2. Use shadcn/ui patterns
3. Add proper TypeScript types
4. Consider Server vs Client Component

## Environment Setup

### Development
\`\`\`bash
cp .env.example .env.local
# Edit .env.local with your values
\`\`\`

### Required Variables
| Variable | Description | Example |
|----------|-------------|---------|
| DATABASE_URL | PostgreSQL connection | postgresql://... |
| NEXTAUTH_SECRET | Auth secret (32+ chars) | openssl rand -base64 32 |
| NEXTAUTH_URL | App URL | http://localhost:3000 |
| STRIPE_SECRET_KEY | Stripe API key | sk_test_... |

### Optional Variables
| Variable | Description | Default |
|----------|-------------|---------|
| LOG_LEVEL | Logging verbosity | info |
| ENABLE_ANALYTICS | Enable tracking | false |

### Generating secrets
\`\`\`bash
# Generate NEXTAUTH_SECRET
openssl rand -base64 32

# Generate API key
openssl rand -hex 24
\`\`\`

## Testing

### File naming
- Unit tests: `[name].test.ts`
- Integration tests: `[name].integration.test.ts`
- E2E tests: `[name].e2e.ts`

### Test structure
\`\`\`typescript
describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid data', async () => {
      // Arrange
      const input = { email: 'test@test.com', name: 'Test' }

      // Act
      const result = await userService.createUser(input)

      // Assert
      expect(result).toMatchObject(input)
    })

    it('should throw on duplicate email', async () => {
      // ...
    })
  })
})
\`\`\`

### Mocking
- Use Vitest's vi.mock() for modules
- Create fixtures in `__fixtures__/`
- Use factories for test data

### Coverage requirements
- Minimum 80% coverage for new code
- 100% coverage for critical paths (auth, payments)

## CI/CD Pipeline

### GitHub Actions Workflow
\`\`\`yaml
# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
      - run: pnpm install
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build
\`\`\`

### Deployment
- **Production**: main branch → Vercel
- **Preview**: PR branches → Vercel Preview

### Pre-commit hooks (Husky)
- Lint staged files
- Run affected tests
- Type check

### Branch naming
- feature/[ticket]-description
- fix/[ticket]-description
- chore/description

## CLAUDE.md Checklist

### Basics
- [ ] Project name and description
- [ ] Main tech stack with versions
- [ ] Folder structure
- [ ] Basic commands

### Conventions
- [ ] Naming style (camelCase, PascalCase, etc.)
- [ ] Preferred patterns (hooks vs HOC, etc.)
- [ ] Import conventions
- [ ] Error handling approach

### Project-specific
- [ ] Custom abstractions
- [ ] Utility functions to reuse
- [ ] Common gotchas
- [ ] Performance considerations

# Project Name

## Stack
Next.js 15, TypeScript, Prisma, Tailwind

## Structure
- src/app - pages
- src/components - components
- src/lib - utilities

## Commands
npm run dev
npm run build

## Rules
- TypeScript strict mode
- Server Components preferred
- Tailwind for styling

## Learned rules
- Always use `prisma` singleton from `src/lib/prisma.ts`
- Forms use react-hook-form + zod, not native forms
- Images use next/image, not img tag
- Links use next/link, not anchor tags