---
description: NestJS API response format, feature modules, and Drizzle repository pattern
globs: "**/*.ts"
alwaysApply: false
---

# Common Patterns

## API Response Format

Paginated lists (after `@Pagination()` + `TransformInterceptor`):

```typescript
interface PaginationMeta {
  currentPage: number
  itemCount: number
  itemsPerPage: number
  totalItems: number
  totalPages: number
}

interface SuccessResponse<T> {
  data: T
  meta?: PaginationMeta
}

// Handler return for @Pagination() routes only
interface PaginationResponse<T> {
  data: T[]
  total: number
}
```

Detail / create / update / delete responses are the resource DTO (unwrapped). See `.cursor/rules/pagination-response.mdc`.

## Feature Module

```typescript
@Module({
  imports: [],
  controllers: [ShipmentsReadController, ShipmentsWriteController],
  providers: [ShipmentsService, ShipmentsRepository],
  exports: [ShipmentsService],
})
export class ShipmentsModule {}
```

Auth-style modules may register a single controller.

## Repository Pattern (Drizzle)

```typescript
interface Repository<T> {
  findAll(filters?: Filters): Promise<{ data: T[]; total: number }>
  findById(id: string): Promise<T | null>
  create(data: CreateDto): Promise<T>
  update(id: string, data: UpdateDto): Promise<T>
  delete(id: string): Promise<void>
}
```

## Skeleton Projects

When implementing new functionality:
1. Search for battle-tested NestJS module patterns
2. Use parallel agents to evaluate options:
   - Security assessment
   - Extensibility analysis
   - Relevance scoring
   - Implementation planning
3. Clone best match as foundation
4. Iterate within proven structure