# AGENTS.md

## Project Overview

This is a Next.js 14 e-commerce application using the App Router,
Server Components, and Drizzle ORM with PostgreSQL.

## Code Conventions

- Use TypeScript strict mode throughout
- Prefer Server Components; use "use client" only when necessary
- Name files with kebab-case: `product-card.tsx`, not `ProductCard.tsx`
- Co-locate tests: `product-card.test.tsx` next to `product-card.tsx`

## Architecture

- `app/`           — Next.js App Router pages and layouts
- `components/`    — Shared UI components
- `lib/`           — Utilities, database client, auth helpers
- `actions/`       — Server Actions for mutations

## Testing

- Use Vitest for unit tests, Playwright for E2E
- Mock database calls using `lib/test-utils.ts` helpers
- Every new component needs at least one test

## Build Commands

```bash
pnpm dev          # Start dev server
pnpm build        # Production build
pnpm test         # Run Vitest
pnpm test:e2e     # Run Playwright
pnpm lint         # ESLint check
```

# Application Guidelines

## Architecture
- This is a monorepo managed with Turborepo
- Apps: web (Next.js), api (Express), mobile (React Native)
- Shared packages: ui, config, types

## Code Standards
- TypeScript strict mode in all packages
- Use barrel exports (index.ts) for public APIs
- No default exports; use named exports everywhere
- Prefer async/await over raw Promises

## API Design
- RESTful endpoints follow /api/v1/{resource} pattern
- All responses use { data, error, meta } envelope
- Validate request bodies with Zod schemas
- Return 4xx for client errors, 5xx for server errors

## Database
- Use Prisma ORM for all database operations
- Migrations checked into source control
- Soft-delete pattern: use deletedAt timestamp, never hard delete
- All timestamps stored as UTC

## Testing
- Jest for unit tests, Playwright for E2E
- Test files colocated: foo.ts -> foo.test.ts
- Mock external services, never call real APIs in tests