# 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
```

# Project Rules

## Overview
E-commerce platform built with Go microservices and React frontend.
All services communicate via gRPC with Protocol Buffers.

## Go Services
- Follow standard Go project layout (cmd/, internal/, pkg/)
- Use structured logging with slog (not log or fmt.Println)
- Error handling: always wrap errors with fmt.Errorf("%w", err)
- Database access through repository pattern in internal/repo/
- All public functions must have godoc comments

## API Design
- Proto files live in proto/ directory with buf for linting
- Use field masks for partial updates
- Pagination via cursor-based tokens, not offset

## Testing
- Table-driven tests for all business logic
- Use testcontainers-go for integration tests
- Minimum 80% coverage on internal/ packages
- Mock external services with gomock interfaces

## Do Not
- Use global variables or init() functions
- Import internal packages across service boundaries
- Commit generated .pb.go files (CI generates them)