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

# 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