# NestJS + PostgreSQL + Redis + BullMQ — AI Agent Guidelines & Architecture Rules

> Enterprise backend architecture guidelines for NestJS modular design, PostgreSQL connection pooling, Redis BullMQ background jobs, and DTO validation.
> Technologies: NestJS, Node.js, TypeScript, PostgreSQL, Redis, BullMQ

---

## AGENTS.md
```markdown
# Project Architecture & Guidelines (NestJS + PostgreSQL + Redis + BullMQ)

## 1. System Architecture
- **Framework**: NestJS (Modular architecture with Dependency Injection).
- **Database**: PostgreSQL with TypeORM or Prisma ORM.
- **Queue System**: BullMQ backed by Redis for asynchronous jobs and delayed tasks.
- **Validation & Transformation**: `class-validator` and `class-transformer` via global `ValidationPipe`.

## 2. PostgreSQL Connection Management
- When scaling multiple NestJS container replicas, route connections through PgBouncer or configure explicit pool limits:
  ```typescript
  TypeOrmModule.forRootAsync({
    imports: [ConfigModule],
    inject: [ConfigService],
    useFactory: (config: ConfigService) => ({
      type: 'postgres',
      url: config.get<string>('DATABASE_URL'),
      autoLoadEntities: true,
      synchronize: false, // NEVER true in production
      extra: {
        max: 20, // Max pool size per instance
        idleTimeoutMillis: 30000,
        connectionTimeoutMillis: 2000,
      },
    }),
  })
  ```

## 3. Redis & BullMQ Queue Rules (Critical)
- **Redis Eviction Policy**: Set Redis `maxmemory-policy` to `noeviction`. Evicting keys arbitrarily corrupts BullMQ queue states.
- **Worker Process Isolation**: For heavy compute or long-running tasks, instantiate workers in dedicated background worker processes rather than the main API server process.
- **Graceful Shutdown**: Always configure `enableShutdownHooks()` on the NestJS app instance to allow active BullMQ workers to finish jobs before container termination.

## 4. Layer Organization & Dependency Injection
- `src/modules/<resource>/`:
  - `<resource>.controller.ts`: Pure HTTP routing, status codes, and Swagger decorators.
  - `<resource>.service.ts`: Business logic and database operations.
  - `<resource>.processor.ts`: BullMQ `@Processor` handler for background jobs.
  - `dto/`: Strongly typed request/response DTOs with `@IsString()`, `@IsOptional()`, etc.
  - `entities/`: Database schema entities.

## 5. Common Pitfalls to Avoid
- ❌ Enabling `synchronize: true` in production database config (causes data loss).
- ❌ Non-idempotent job handlers: Always check if a background job was already completed before executing side effects.
- ❌ Unhandled Worker Errors: Ensure workers implement event listeners (`@OnWorkerEvent('failed')`) to prevent silent crashes.

## 6. Testing Conventions
- Use Jest (NestJS default) with `@nestjs/testing`'s `Test.createTestingModule` to build isolated module contexts per test suite.
- Mock BullMQ queues in unit tests (`getQueueToken()`); reserve real Redis-backed queue tests for a dedicated integration suite.
- Write e2e tests with `supertest` against a running Nest app instance for every controller endpoint, not just services.
- Assert processor idempotency explicitly: invoke the same job payload twice and assert no duplicate side effects.

## 7. Git Workflow & PR Conventions
- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the module, e.g. `fix(billing): prevent duplicate invoice job processing`.
- TypeORM/Prisma migrations ship in the same PR as the entity change that generated them.
- Require `bun run test`, `bun run test:e2e`, and `tsc --noEmit` green before merge.
- Squash-merge feature branches; never merge with `synchronize: true` left enabled in any committed config.
```

---

## CLAUDE.md
```markdown
# CLAUDE.md — NestJS + PostgreSQL + Redis

Refer to @AGENTS.md for complete modular architecture and queue rules.

## Common Commands
- `bun run start:dev` - Start NestJS in watch mode
- `bun run build` - Compile NestJS TypeScript application
- `bun run test` - Run unit tests with Jest
- `bun run test:e2e` - Run end-to-end API tests
- `bun run typeorm migration:run` - Run pending migrations

## Claude Specific Directives
- Follow NestJS standard dependency injection patterns; avoid global singletons.
- Ensure all input DTOs are decorated with `class-validator` rules.
```

---

## .cursor/rules/stack.mdc
```markdown
---
description: NestJS + PostgreSQL + Redis + BullMQ architecture rules
globs: ["**/*.ts"]
alwaysApply: true
---

# NestJS + PostgreSQL + Redis + BullMQ

- NestJS modular DI architecture, PostgreSQL via TypeORM/Prisma, BullMQ over Redis for async jobs.
- Explicit pool limits on `TypeOrmModule.forRootAsync` (`max`, `idleTimeoutMillis`, `connectionTimeoutMillis`); route through PgBouncer at scale.
- `synchronize: false` always in production — schema drift belongs in migrations, never auto-sync.
- Redis `maxmemory-policy: noeviction` — arbitrary key eviction corrupts BullMQ queue state.
- Heavy/long-running jobs run in dedicated worker processes, not the main API process. Call `enableShutdownHooks()` for graceful drain on deploy.
- `<resource>.controller.ts` (routing only) / `<resource>.service.ts` (logic) / `<resource>.processor.ts` (BullMQ jobs) / `dto/` (validated I/O) — keep these separated.
- Every job handler must be idempotent; check completion state before re-running side effects.
- `@OnWorkerEvent('failed')` listeners on every worker — no silent job crashes.
```

---

## Architecture Overview & Best Practices
## Architecture Overview

Production conventions for scalable, enterprise-grade backend microservices and APIs with **NestJS**, **PostgreSQL**, **Redis**, and **BullMQ**.

### Verified Real-World Adoption

This architecture is deployed in high-concurrency production platforms including **Twenty CRM**, **ToolJet**, **Novu**, **AFFiNE**, and **Logto**.

### Key Architectural Nuances

- **Redis Memory Policy Safety**: Requires `noeviction` policy to protect BullMQ queue integrity.
- **Dedicated Worker Topologies**: Decouples HTTP request-response latency from asynchronous queue processing.