bootstrap/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template

# ${PROJECT_NAME} — Claude Code Instructions

> **${PROJECT_DESCRIPTION}**

## Conditional Documentation Loading

| When working on... | Load this guide |
|---|---|
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |

## Technology Stack

| Layer | Technology |
|-------|------------|
| **Frontend** | Next.js + React + TailwindCSS + Shadcn/ui |
| **Backend** | NestJS + Prisma ORM |
| **Database** | PostgreSQL |
| **Testing** | Vitest + Playwright |
| **Monorepo** | pnpm workspaces + TurboRepo |
| **Deployment** | Docker + docker-compose |

## Repository Structure

```
${PROJECT_DIR}/
├── CLAUDE.md              # This file
├── AGENTS.md              # Agent-specific patterns and gotchas
├── apps/
│   ├── api/               # NestJS backend
│   │   ├── src/
│   │   ├── prisma/
│   │   │   └── schema.prisma
│   │   └── Dockerfile
│   └── web/               # Next.js frontend
│       ├── app/
│       ├── components/
│       └── Dockerfile
├── packages/
│   ├── shared/            # Shared types, utilities
│   ├── ui/                # Shared UI components
│   └── config/            # Shared configuration
├── docs/
│   ├── scratchpads/       # Per-issue working documents
│   └── templates/         # Project templates
├── tests/                 # Integration/E2E tests
├── docker/                # Docker configuration
├── .env.example
├── turbo.json
├── pnpm-workspace.yaml
└── README.md
```

## Development Workflow

### Branch Strategy
- `main` — Stable releases only
- `develop` — Active development (default working branch)
- `feature/*` — Feature branches from develop
- `fix/*` — Bug fix branches

### Starting Work
```bash
git checkout develop
git pull --rebase
pnpm install
```

### Building
```bash
pnpm build                    # Build all packages
pnpm --filter api build       # Build API only
pnpm --filter web build       # Build web only
```

### Testing
```bash
pnpm test                     # Run all tests
pnpm test:unit                # Unit tests (Vitest)
pnpm test:e2e                 # E2E tests (Playwright)
pnpm test:coverage            # Coverage report
```

### Linting & Type Checking
```bash
pnpm lint                     # ESLint
pnpm typecheck                # TypeScript type checking
pnpm format                   # Prettier formatting
```

## Quality Gates

**All must pass before committing:**

```bash
pnpm typecheck && pnpm lint && pnpm test
```

## API Conventions

### NestJS Patterns
- Controllers handle HTTP, Services handle business logic
- Use DTOs with `class-validator` for request validation
- Use Guards for authentication/authorization
- Use Interceptors for response transformation
- Use Prisma for database access (no raw SQL)

### REST API Standards
- `GET /resource` — List (with pagination)
- `GET /resource/:id` — Get single
- `POST /resource` — Create
- `PATCH /resource/:id` — Update
- `DELETE /resource/:id` — Delete
- Return proper HTTP status codes (201 Created, 204 No Content, etc.)

## Frontend Conventions

### Next.js Patterns
- Use App Router (`app/` directory)
- Server Components by default, `'use client'` only when needed
- Use Shadcn/ui components — don't create custom UI primitives
- Use TailwindCSS for styling — no CSS modules or styled-components

### Component Structure
```
components/
├── ui/          # Shadcn/ui components (auto-generated)
├── layout/      # Layout components (header, sidebar, etc.)
├── forms/       # Form components
└── features/    # Feature-specific components
```

## Database

### Prisma Workflow
```bash
# Generate client after schema changes
pnpm --filter api prisma generate

# Create migration
pnpm --filter api prisma migrate dev --name description

# Apply migrations
pnpm --filter api prisma migrate deploy

# Reset database (dev only)
pnpm --filter api prisma migrate reset
```

### Rules
- Always create migrations for schema changes
- Include migrations in commits
- Never use raw SQL — use Prisma client
- Use transactions for multi-table operations

## Code Review

### Independent Review (Automated)
After completing code changes, run independent reviews:

```bash
# Code quality review (Codex)
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted

# Security review (Codex)
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```

## Issue Tracking

### Workflow
1. Check for assigned issues before starting work
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Reference issues in commits: `Fixes #123` or `Refs #123`
4. Close issues after successful testing

### Commits
```
<type>(#issue): Brief description

Fixes #123
```
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`

## Secrets Management

**NEVER hardcode secrets.**

```bash
# .env.example is committed (with placeholders)
# .env is NOT committed (contains real values)
```

Required environment variables are documented in `.env.example`.