---
description: NestJS modular TDD structure with Drizzle and PostgreSQL
globs: "**/*.{ts,js}"
alwaysApply: false
---

# NestJS Project Conventions

Stack: NestJS + PostgreSQL + Drizzle ORM. Follow `.agents/skills/nestjs-best-practices` and `.agents/skills/project-guidelines-example`.

## Modules

- One feature folder under `src/modules/`
- **Main (CRUD) features:** `*.module.ts`, `*-read.controller.ts`, `*-write.controller.ts`, service(s), repository, `dto/`
- **Auth-style / non-CRUD modules** may keep a single `*.controller.ts`
- Share cross-cutting code via `src/common/` (filters, guards, pipes, interceptors, HTTP response helpers)
- Primary entities: `.cursor/rules/primary-entity.mdc`, `.cursor/rules/status.mdc`
- Read/write split: `.cursor/rules/read-write-controllers.mdc`
- List pagination: `.cursor/rules/pagination-response.mdc`
- Document HTTP endpoints per `.cursor/rules/nestjs-swagger.mdc`

## Tests

- Unit tests colocated as `*.spec.ts`
- E2E tests in `test/*.e2e-spec.ts` with Supertest
- Write tests first (RED → GREEN → REFACTOR)
- Mock Drizzle and external services, not Nest internals

## Database

- Schema and SQL migrations in `drizzle/` (table defs may live in `src/database/schema.ts`)
- Primary tables spread `primaryEntityColumns(users)` from `src/database/primary-entity-columns.ts`
- Config in `drizzle.config.ts`
- Never mutate production schema without a migration