omgkit 2.2.0 → 2.3.0

package/plugin/skills/frameworks/nestjs/SKILL.md

@@ -1,1046 +1,179 @@
 ---
-name: nestjs
-description: Enterprise NestJS development with TypeScript, dependency injection, and microservices patterns
-category: frameworks
-triggers:
-  - nestjs
-  - nest.js
-  - nest
-  - node typescript
-  - typescript backend
-  - nodejs framework
-  - nestjs api
-  - nestjs microservices
+name: building-nestjs-apis
+description: Builds enterprise NestJS applications with TypeScript, dependency injection, TypeORM, and microservices patterns. Use when creating scalable Node.js backends, REST/GraphQL APIs, or microservices.
 ---
 
 # NestJS
 
-Enterprise-grade **NestJS development** following industry best practices. This skill covers modular architecture, dependency injection, TypeORM integration, authentication with Passport, testing patterns, and microservices configurations used by top engineering teams.
-
-## Purpose
-
-Build scalable Node.js applications with confidence:
-
-- Design modular, maintainable architectures
-- Implement robust dependency injection
-- Handle authentication and authorization
-- Validate requests with class-validator
-- Write comprehensive tests with Jest
-- Deploy production-ready applications
-- Build microservices and message queues
-
-## Features
-
-### 1. Module Architecture
-
-```typescript
-// src/app.module.ts
-import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
-import { ConfigModule, ConfigService } from '@nestjs/config';
-import { TypeOrmModule } from '@nestjs/typeorm';
-import { ThrottlerModule } from '@nestjs/throttler';
-import { APP_GUARD, APP_INTERCEPTOR } from '@nestjs/core';
-
-import { AuthModule } from './auth/auth.module';
-import { UsersModule } from './users/users.module';
-import { OrganizationsModule } from './organizations/organizations.module';
-import { ProjectsModule } from './projects/projects.module';
-import { LoggingInterceptor } from './common/interceptors/logging.interceptor';
-import { RequestIdMiddleware } from './common/middleware/request-id.middleware';
-import configuration from './config/configuration';
-
-@Module({
-  imports: [
-    ConfigModule.forRoot({
-      isGlobal: true,
-      load: [configuration],
-    }),
-    TypeOrmModule.forRootAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        type: 'postgres',
-        host: config.get('database.host'),
-        port: config.get('database.port'),
-        username: config.get('database.username'),
-        password: config.get('database.password'),
-        database: config.get('database.name'),
-        entities: [__dirname + '/**/*.entity{.ts,.js}'],
-        synchronize: config.get('database.synchronize'),
-        logging: config.get('database.logging'),
-      }),
-    }),
-    ThrottlerModule.forRoot([{
-      ttl: 60000,
-      limit: 100,
-    }]),
-    AuthModule,
-    UsersModule,
-    OrganizationsModule,
-    ProjectsModule,
-  ],
-  providers: [
-    {
-      provide: APP_INTERCEPTOR,
-      useClass: LoggingInterceptor,
-    },
-  ],
-})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer.apply(RequestIdMiddleware).forRoutes('*');
-  }
-}
-
-
-// src/users/users.module.ts
-import { Module } from '@nestjs/common';
-import { TypeOrmModule } from '@nestjs/typeorm';
-import { UsersController } from './users.controller';
-import { UsersService } from './users.service';
-import { User } from './entities/user.entity';
-import { UsersRepository } from './users.repository';
-
-@Module({
-  imports: [TypeOrmModule.forFeature([User])],
-  controllers: [UsersController],
-  providers: [UsersService, UsersRepository],
-  exports: [UsersService],
-})
-export class UsersModule {}
-
-
-// src/config/configuration.ts
-export default () => ({
-  port: parseInt(process.env.PORT, 10) || 3000,
-  database: {
-    host: process.env.DB_HOST || 'localhost',
-    port: parseInt(process.env.DB_PORT, 10) || 5432,
-    username: process.env.DB_USERNAME || 'postgres',
-    password: process.env.DB_PASSWORD,
-    name: process.env.DB_NAME || 'app',
-    synchronize: process.env.NODE_ENV !== 'production',
-    logging: process.env.NODE_ENV === 'development',
-  },
-  jwt: {
-    secret: process.env.JWT_SECRET,
-    expiresIn: process.env.JWT_EXPIRES_IN || '1h',
-  },
-  redis: {
-    host: process.env.REDIS_HOST || 'localhost',
-    port: parseInt(process.env.REDIS_PORT, 10) || 6379,
-  },
-});
-```
-
-### 2. Entities and Repositories
+## Quick Start
 
 ```typescript
-// src/users/entities/user.entity.ts
-import {
-  Entity,
-  PrimaryGeneratedColumn,
-  Column,
-  CreateDateColumn,
-  UpdateDateColumn,
-  DeleteDateColumn,
-  ManyToMany,
-  OneToMany,
-  BeforeInsert,
-} from 'typeorm';
-import * as bcrypt from 'bcrypt';
-import { Organization } from '../../organizations/entities/organization.entity';
-import { Exclude } from 'class-transformer';
-
-export enum UserRole {
-  ADMIN = 'admin',
-  USER = 'user',
-  GUEST = 'guest',
-}
-
-@Entity('users')
-export class User {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column({ unique: true })
-  email: string;
-
-  @Column()
-  name: string;
-
-  @Column()
-  @Exclude()
-  password: string;
-
-  @Column({
-    type: 'enum',
-    enum: UserRole,
-    default: UserRole.USER,
-  })
-  role: UserRole;
-
-  @Column({ default: true })
-  isActive: boolean;
+import { Controller, Get, Module, NestFactory } from '@nestjs/common';
 
-  @CreateDateColumn()
-  createdAt: Date;
-
-  @UpdateDateColumn()
-  updatedAt: Date;
-
-  @DeleteDateColumn()
-  deletedAt?: Date;
-
-  @ManyToMany(() => Organization, (org) => org.members)
-  organizations: Organization[];
-
-  @OneToMany(() => Organization, (org) => org.owner)
-  ownedOrganizations: Organization[];
-
-  @BeforeInsert()
-  async hashPassword() {
-    if (this.password) {
-      this.password = await bcrypt.hash(this.password, 10);
-    }
-  }
-
-  async validatePassword(password: string): Promise<boolean> {
-    return bcrypt.compare(password, this.password);
+@Controller('health')
+class HealthController {
+  @Get()
+  check() {
+    return { status: 'ok' };
   }
 }
 
+@Module({ controllers: [HealthController] })
+class AppModule {}
 
-// src/users/users.repository.ts
-import { Injectable } from '@nestjs/common';
-import { DataSource, Repository } from 'typeorm';
-import { User, UserRole } from './entities/user.entity';
-
-interface FindAllOptions {
-  search?: string;
-  role?: UserRole;
-  isActive?: boolean;
-  skip?: number;
-  take?: number;
-}
-
-@Injectable()
-export class UsersRepository extends Repository<User> {
-  constructor(private dataSource: DataSource) {
-    super(User, dataSource.createEntityManager());
-  }
-
-  async findByEmail(email: string): Promise<User | null> {
-    return this.findOne({
-      where: { email },
-    });
-  }
-
-  async findAllWithCount(options: FindAllOptions): Promise<[User[], number]> {
-    const query = this.createQueryBuilder('user')
-      .where('user.deletedAt IS NULL');
-
-    if (options.search) {
-      query.andWhere(
-        '(user.name ILIKE :search OR user.email ILIKE :search)',
-        { search: `%${options.search}%` },
-      );
-    }
-
-    if (options.role) {
-      query.andWhere('user.role = :role', { role: options.role });
-    }
-
-    if (options.isActive !== undefined) {
-      query.andWhere('user.isActive = :isActive', { isActive: options.isActive });
-    }
-
-    return query
-      .orderBy('user.createdAt', 'DESC')
-      .skip(options.skip || 0)
-      .take(options.take || 20)
-      .getManyAndCount();
-  }
-
-  async findWithOrganizations(id: string): Promise<User | null> {
-    return this.findOne({
-      where: { id },
-      relations: ['organizations'],
-    });
-  }
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
 }
+bootstrap();
 ```
 
-### 3. DTOs and Validation
-
-```typescript
-// src/users/dto/create-user.dto.ts
-import {
-  IsEmail,
-  IsString,
-  IsEnum,
-  IsOptional,
-  MinLength,
-  MaxLength,
-  Matches,
-} from 'class-validator';
-import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { UserRole } from '../entities/user.entity';
-
-export class CreateUserDto {
-  @ApiProperty({ example: 'user@example.com' })
-  @IsEmail()
-  email: string;
-
-  @ApiProperty({ example: 'John Doe' })
-  @IsString()
-  @MinLength(2)
-  @MaxLength(100)
-  name: string;
-
-  @ApiProperty({ example: 'SecurePass123!' })
-  @IsString()
-  @MinLength(8)
-  @MaxLength(128)
-  @Matches(
-    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]/,
-    { message: 'Password must contain uppercase, lowercase, number and special character' },
-  )
-  password: string;
-
-  @ApiPropertyOptional({ enum: UserRole })
-  @IsOptional()
-  @IsEnum(UserRole)
-  role?: UserRole;
-}
-
-
-// src/users/dto/update-user.dto.ts
-import { PartialType, OmitType } from '@nestjs/swagger';
-import { CreateUserDto } from './create-user.dto';
-import { IsBoolean, IsOptional } from 'class-validator';
-
-export class UpdateUserDto extends PartialType(
-  OmitType(CreateUserDto, ['password'] as const),
-) {
-  @IsOptional()
-  @IsBoolean()
-  isActive?: boolean;
-}
-
-
-// src/users/dto/user-response.dto.ts
-import { ApiProperty } from '@nestjs/swagger';
-import { Expose, Type } from 'class-transformer';
-import { UserRole } from '../entities/user.entity';
-
-export class UserResponseDto {
-  @ApiProperty()
-  @Expose()
-  id: string;
-
-  @ApiProperty()
-  @Expose()
-  email: string;
-
-  @ApiProperty()
-  @Expose()
-  name: string;
-
-  @ApiProperty({ enum: UserRole })
-  @Expose()
-  role: UserRole;
-
-  @ApiProperty()
-  @Expose()
-  isActive: boolean;
-
-  @ApiProperty()
-  @Expose()
-  createdAt: Date;
-
-  @ApiProperty()
-  @Expose()
-  updatedAt: Date;
-}
-
-
-// src/common/dto/pagination.dto.ts
-import { ApiPropertyOptional } from '@nestjs/swagger';
-import { IsOptional, IsInt, Min, Max } from 'class-validator';
-import { Type } from 'class-transformer';
-
-export class PaginationDto {
-  @ApiPropertyOptional({ default: 1 })
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  page?: number = 1;
-
-  @ApiPropertyOptional({ default: 20 })
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  @Max(100)
-  limit?: number = 20;
-
-  get skip(): number {
-    return (this.page - 1) * this.limit;
-  }
-}
-
-export class PaginatedResponseDto<T> {
-  @ApiProperty()
-  data: T[];
-
-  @ApiProperty()
-  total: number;
-
-  @ApiProperty()
-  page: number;
-
-  @ApiProperty()
-  limit: number;
-
-  @ApiProperty()
-  totalPages: number;
+## Features
 
-  @ApiProperty()
-  hasMore: boolean;
+| Feature | Description | Guide |
+|---------|-------------|-------|
+| Modules | Dependency injection, providers | [MODULES.md](MODULES.md) |
+| Controllers | Routes, validation, guards | [CONTROLLERS.md](CONTROLLERS.md) |
+| Services | Business logic, repositories | [SERVICES.md](SERVICES.md) |
+| Database | TypeORM, Prisma integration | [DATABASE.md](DATABASE.md) |
+| Auth | Passport, JWT, guards | [AUTH.md](AUTH.md) |
+| Testing | Unit, e2e with Jest | [TESTING.md](TESTING.md) |
 
-  static create<T>(
-    data: T[],
-    total: number,
-    page: number,
-    limit: number,
-  ): PaginatedResponseDto<T> {
-    const totalPages = Math.ceil(total / limit);
-    return {
-      data,
-      total,
-      page,
-      limit,
-      totalPages,
-      hasMore: page < totalPages,
-    };
-  }
-}
-```
+## Common Patterns
 
-### 4. Controllers
+### Controller with Validation
 
 ```typescript
-// src/users/users.controller.ts
-import {
-  Controller,
-  Get,
-  Post,
-  Patch,
-  Delete,
-  Body,
-  Param,
-  Query,
-  UseGuards,
-  ParseUUIDPipe,
-  HttpCode,
-  HttpStatus,
-} from '@nestjs/common';
-import {
-  ApiTags,
-  ApiOperation,
-  ApiResponse,
-  ApiBearerAuth,
-} from '@nestjs/swagger';
-import { UsersService } from './users.service';
-import { CreateUserDto } from './dto/create-user.dto';
-import { UpdateUserDto } from './dto/update-user.dto';
-import { UserResponseDto } from './dto/user-response.dto';
-import { PaginationDto, PaginatedResponseDto } from '../common/dto/pagination.dto';
-import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
-import { RolesGuard } from '../auth/guards/roles.guard';
-import { Roles } from '../auth/decorators/roles.decorator';
-import { CurrentUser } from '../auth/decorators/current-user.decorator';
-import { User, UserRole } from './entities/user.entity';
-
-@ApiTags('users')
 @Controller('users')
-@UseGuards(JwtAuthGuard, RolesGuard)
-@ApiBearerAuth()
+@UseGuards(JwtAuthGuard)
 export class UsersController {
   constructor(private readonly usersService: UsersService) {}
 
   @Get()
-  @Roles(UserRole.ADMIN)
-  @ApiOperation({ summary: 'List all users' })
-  @ApiResponse({ status: 200, type: PaginatedResponseDto })
-  async findAll(
-    @Query() pagination: PaginationDto,
-    @Query('search') search?: string,
-    @Query('role') role?: UserRole,
-  ): Promise<PaginatedResponseDto<UserResponseDto>> {
-    return this.usersService.findAll(pagination, { search, role });
-  }
-
-  @Get('me')
-  @ApiOperation({ summary: 'Get current user profile' })
-  @ApiResponse({ status: 200, type: UserResponseDto })
-  async getProfile(@CurrentUser() user: User): Promise<UserResponseDto> {
-    return this.usersService.findOne(user.id);
-  }
-
-  @Patch('me')
-  @ApiOperation({ summary: 'Update current user profile' })
-  @ApiResponse({ status: 200, type: UserResponseDto })
-  async updateProfile(
-    @CurrentUser() user: User,
-    @Body() updateUserDto: UpdateUserDto,
-  ): Promise<UserResponseDto> {
-    return this.usersService.update(user.id, updateUserDto);
+  @Roles('admin')
+  findAll(@Query() query: PaginationDto) {
+    return this.usersService.findAll(query);
   }
 
   @Get(':id')
-  @Roles(UserRole.ADMIN)
-  @ApiOperation({ summary: 'Get user by ID' })
-  @ApiResponse({ status: 200, type: UserResponseDto })
-  async findOne(
-    @Param('id', ParseUUIDPipe) id: string,
-  ): Promise<UserResponseDto> {
+  findOne(@Param('id', ParseUUIDPipe) id: string) {
     return this.usersService.findOne(id);
   }
 
   @Post()
-  @Roles(UserRole.ADMIN)
-  @ApiOperation({ summary: 'Create new user' })
-  @ApiResponse({ status: 201, type: UserResponseDto })
-  async create(@Body() createUserDto: CreateUserDto): Promise<UserResponseDto> {
-    return this.usersService.create(createUserDto);
-  }
-
-  @Patch(':id')
-  @Roles(UserRole.ADMIN)
-  @ApiOperation({ summary: 'Update user' })
-  @ApiResponse({ status: 200, type: UserResponseDto })
-  async update(
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() updateUserDto: UpdateUserDto,
-  ): Promise<UserResponseDto> {
-    return this.usersService.update(id, updateUserDto);
-  }
-
-  @Delete(':id')
-  @Roles(UserRole.ADMIN)
-  @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiOperation({ summary: 'Delete user' })
-  @ApiResponse({ status: 204 })
-  async remove(@Param('id', ParseUUIDPipe) id: string): Promise<void> {
-    await this.usersService.remove(id);
+  create(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
   }
 }
 ```
 
-### 5. Services
+### Service with Repository
 
 ```typescript
-// src/users/users.service.ts
-import {
-  Injectable,
-  NotFoundException,
-  ConflictException,
-} from '@nestjs/common';
-import { plainToInstance } from 'class-transformer';
-import { UsersRepository } from './users.repository';
-import { CreateUserDto } from './dto/create-user.dto';
-import { UpdateUserDto } from './dto/update-user.dto';
-import { UserResponseDto } from './dto/user-response.dto';
-import { PaginationDto, PaginatedResponseDto } from '../common/dto/pagination.dto';
-import { User, UserRole } from './entities/user.entity';
-
-interface FindAllFilters {
-  search?: string;
-  role?: UserRole;
-  isActive?: boolean;
-}
-
 @Injectable()
 export class UsersService {
-  constructor(private readonly usersRepository: UsersRepository) {}
-
-  async findAll(
-    pagination: PaginationDto,
-    filters: FindAllFilters = {},
-  ): Promise<PaginatedResponseDto<UserResponseDto>> {
-    const [users, total] = await this.usersRepository.findAllWithCount({
-      ...filters,
-      skip: pagination.skip,
-      take: pagination.limit,
-    });
-
-    const data = users.map((user) =>
-      plainToInstance(UserResponseDto, user, { excludeExtraneousValues: true }),
-    );
-
-    return PaginatedResponseDto.create(
-      data,
-      total,
-      pagination.page,
-      pagination.limit,
-    );
-  }
-
-  async findOne(id: string): Promise<UserResponseDto> {
-    const user = await this.usersRepository.findOne({ where: { id } });
-
-    if (!user) {
-      throw new NotFoundException(`User with ID ${id} not found`);
-    }
-
-    return plainToInstance(UserResponseDto, user, {
-      excludeExtraneousValues: true,
-    });
-  }
-
-  async findByEmail(email: string): Promise<User | null> {
-    return this.usersRepository.findByEmail(email);
-  }
-
-  async create(createUserDto: CreateUserDto): Promise<UserResponseDto> {
-    const existing = await this.usersRepository.findByEmail(createUserDto.email);
-
-    if (existing) {
-      throw new ConflictException('Email already in use');
-    }
-
-    const user = this.usersRepository.create(createUserDto);
-    await this.usersRepository.save(user);
-
-    return plainToInstance(UserResponseDto, user, {
-      excludeExtraneousValues: true,
-    });
-  }
-
-  async update(id: string, updateUserDto: UpdateUserDto): Promise<UserResponseDto> {
-    const user = await this.usersRepository.findOne({ where: { id } });
+  constructor(private readonly usersRepo: UsersRepository) {}
 
-    if (!user) {
-      throw new NotFoundException(`User with ID ${id} not found`);
-    }
-
-    if (updateUserDto.email && updateUserDto.email !== user.email) {
-      const existing = await this.usersRepository.findByEmail(updateUserDto.email);
-      if (existing) {
-        throw new ConflictException('Email already in use');
-      }
-    }
-
-    Object.assign(user, updateUserDto);
-    await this.usersRepository.save(user);
-
-    return plainToInstance(UserResponseDto, user, {
-      excludeExtraneousValues: true,
+  async findAll(query: PaginationDto) {
+    const [users, total] = await this.usersRepo.findAllWithCount({
+      skip: query.skip,
+      take: query.limit,
     });
+    return { data: users, total, page: query.page };
   }
 
-  async remove(id: string): Promise<void> {
-    const user = await this.usersRepository.findOne({ where: { id } });
-
-    if (!user) {
-      throw new NotFoundException(`User with ID ${id} not found`);
-    }
-
-    await this.usersRepository.softRemove(user);
+  async findOne(id: string) {
+    const user = await this.usersRepo.findOne({ where: { id } });
+    if (!user) throw new NotFoundException('User not found');
+    return user;
   }
 
-  async validateUser(email: string, password: string): Promise<User | null> {
-    const user = await this.usersRepository.findByEmail(email);
-
-    if (!user || !user.isActive) {
-      return null;
-    }
-
-    const isValid = await user.validatePassword(password);
-    return isValid ? user : null;
+  async create(dto: CreateUserDto) {
+    const exists = await this.usersRepo.findByEmail(dto.email);
+    if (exists) throw new ConflictException('Email in use');
+    return this.usersRepo.save(this.usersRepo.create(dto));
   }
 }
 ```
 
-### 6. Authentication
+### DTO with Validation
 
 ```typescript
-// src/auth/auth.module.ts
-import { Module } from '@nestjs/common';
-import { JwtModule } from '@nestjs/jwt';
-import { PassportModule } from '@nestjs/passport';
-import { ConfigModule, ConfigService } from '@nestjs/config';
-import { AuthController } from './auth.controller';
-import { AuthService } from './auth.service';
-import { JwtStrategy } from './strategies/jwt.strategy';
-import { LocalStrategy } from './strategies/local.strategy';
-import { UsersModule } from '../users/users.module';
-
-@Module({
-  imports: [
-    UsersModule,
-    PassportModule,
-    JwtModule.registerAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        secret: config.get('jwt.secret'),
-        signOptions: { expiresIn: config.get('jwt.expiresIn') },
-      }),
-    }),
-  ],
-  controllers: [AuthController],
-  providers: [AuthService, JwtStrategy, LocalStrategy],
-  exports: [AuthService],
-})
-export class AuthModule {}
-
-
-// src/auth/strategies/jwt.strategy.ts
-import { Injectable, UnauthorizedException } from '@nestjs/common';
-import { PassportStrategy } from '@nestjs/passport';
-import { ExtractJwt, Strategy } from 'passport-jwt';
-import { ConfigService } from '@nestjs/config';
-import { UsersService } from '../../users/users.service';
-
-interface JwtPayload {
-  sub: string;
+export class CreateUserDto {
+  @IsEmail()
   email: string;
-  role: string;
-}
-
-@Injectable()
-export class JwtStrategy extends PassportStrategy(Strategy) {
-  constructor(
-    private readonly configService: ConfigService,
-    private readonly usersService: UsersService,
-  ) {
-    super({
-      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
-      ignoreExpiration: false,
-      secretOrKey: configService.get('jwt.secret'),
-    });
-  }
-
-  async validate(payload: JwtPayload) {
-    const user = await this.usersService.findByEmail(payload.email);
-
-    if (!user || !user.isActive) {
-      throw new UnauthorizedException();
-    }
-
-    return user;
-  }
-}
-
 
-// src/auth/guards/roles.guard.ts
-import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
-import { UserRole } from '../../users/entities/user.entity';
-import { ROLES_KEY } from '../decorators/roles.decorator';
-
-@Injectable()
-export class RolesGuard implements CanActivate {
-  constructor(private reflector: Reflector) {}
-
-  canActivate(context: ExecutionContext): boolean {
-    const requiredRoles = this.reflector.getAllAndOverride<UserRole[]>(
-      ROLES_KEY,
-      [context.getHandler(), context.getClass()],
-    );
+  @IsString()
+  @MinLength(2)
+  name: string;
 
-    if (!requiredRoles) {
-      return true;
-    }
+  @IsString()
+  @MinLength(8)
+  @Matches(/^(?=.*[A-Z])(?=.*\d)/, {
+    message: 'Password must contain uppercase and number',
+  })
+  password: string;
 
-    const { user } = context.switchToHttp().getRequest();
-    return requiredRoles.includes(user.role);
-  }
+  @IsOptional()
+  @IsEnum(UserRole)
+  role?: UserRole;
 }
-
-
-// src/auth/decorators/roles.decorator.ts
-import { SetMetadata } from '@nestjs/common';
-import { UserRole } from '../../users/entities/user.entity';
-
-export const ROLES_KEY = 'roles';
-export const Roles = (...roles: UserRole[]) => SetMetadata(ROLES_KEY, roles);
-
-
-// src/auth/decorators/current-user.decorator.ts
-import { createParamDecorator, ExecutionContext } from '@nestjs/common';
-
-export const CurrentUser = createParamDecorator(
-  (data: unknown, ctx: ExecutionContext) => {
-    const request = ctx.switchToHttp().getRequest();
-    return request.user;
-  },
-);
 ```
 
-### 7. Testing
-
-```typescript
-// src/users/users.service.spec.ts
-import { Test, TestingModule } from '@nestjs/testing';
-import { NotFoundException, ConflictException } from '@nestjs/common';
-import { UsersService } from './users.service';
-import { UsersRepository } from './users.repository';
-import { User, UserRole } from './entities/user.entity';
-
-describe('UsersService', () => {
-  let service: UsersService;
-  let repository: jest.Mocked<UsersRepository>;
-
-  const mockUser: Partial<User> = {
-    id: 'test-id',
-    email: 'test@example.com',
-    name: 'Test User',
-    role: UserRole.USER,
-    isActive: true,
-    createdAt: new Date(),
-    updatedAt: new Date(),
-  };
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [
-        UsersService,
-        {
-          provide: UsersRepository,
-          useValue: {
-            findOne: jest.fn(),
-            findByEmail: jest.fn(),
-            findAllWithCount: jest.fn(),
-            create: jest.fn(),
-            save: jest.fn(),
-            softRemove: jest.fn(),
-          },
-        },
-      ],
-    }).compile();
-
-    service = module.get<UsersService>(UsersService);
-    repository = module.get(UsersRepository);
-  });
-
-  describe('findOne', () => {
-    it('should return a user', async () => {
-      repository.findOne.mockResolvedValue(mockUser as User);
-
-      const result = await service.findOne('test-id');
-
-      expect(result.email).toBe(mockUser.email);
-      expect(repository.findOne).toHaveBeenCalledWith({
-        where: { id: 'test-id' },
-      });
-    });
-
-    it('should throw NotFoundException if user not found', async () => {
-      repository.findOne.mockResolvedValue(null);
-
-      await expect(service.findOne('test-id')).rejects.toThrow(NotFoundException);
-    });
-  });
-
-  describe('create', () => {
-    it('should create a new user', async () => {
-      repository.findByEmail.mockResolvedValue(null);
-      repository.create.mockReturnValue(mockUser as User);
-      repository.save.mockResolvedValue(mockUser as User);
-
-      const result = await service.create({
-        email: 'test@example.com',
-        name: 'Test User',
-        password: 'Password123!',
-      });
-
-      expect(result.email).toBe(mockUser.email);
-      expect(repository.save).toHaveBeenCalled();
-    });
-
-    it('should throw ConflictException for duplicate email', async () => {
-      repository.findByEmail.mockResolvedValue(mockUser as User);
-
-      await expect(
-        service.create({
-          email: 'test@example.com',
-          name: 'Test',
-          password: 'Password123!',
-        }),
-      ).rejects.toThrow(ConflictException);
-    });
-  });
-});
-
-
-// src/users/users.controller.spec.ts
-import { Test, TestingModule } from '@nestjs/testing';
-import { UsersController } from './users.controller';
-import { UsersService } from './users.service';
-
-describe('UsersController', () => {
-  let controller: UsersController;
-  let service: jest.Mocked<UsersService>;
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      controllers: [UsersController],
-      providers: [
-        {
-          provide: UsersService,
-          useValue: {
-            findAll: jest.fn(),
-            findOne: jest.fn(),
-            create: jest.fn(),
-            update: jest.fn(),
-            remove: jest.fn(),
-          },
-        },
-      ],
-    }).compile();
+## Workflows
 
-    controller = module.get<UsersController>(UsersController);
-    service = module.get(UsersService);
-  });
+### API Development
 
-  it('should be defined', () => {
-    expect(controller).toBeDefined();
-  });
-});
+1. Create module with `nest g module [name]`
+2. Create controller and service
+3. Define DTOs with class-validator
+4. Add guards for auth/roles
+5. Write unit and e2e tests
 
-
-// test/users.e2e-spec.ts
-import { Test, TestingModule } from '@nestjs/testing';
-import { INestApplication, ValidationPipe } from '@nestjs/common';
-import * as request from 'supertest';
-import { AppModule } from '../src/app.module';
-
-describe('Users (e2e)', () => {
-  let app: INestApplication;
-  let authToken: string;
-
-  beforeAll(async () => {
-    const moduleFixture: TestingModule = await Test.createTestingModule({
-      imports: [AppModule],
-    }).compile();
-
-    app = moduleFixture.createNestApplication();
-    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
-    await app.init();
-
-    // Get auth token
-    const loginResponse = await request(app.getHttpServer())
-      .post('/auth/login')
-      .send({ email: 'admin@test.com', password: 'Admin123!' });
-
-    authToken = loginResponse.body.access_token;
-  });
-
-  afterAll(async () => {
-    await app.close();
-  });
-
-  describe('/users (GET)', () => {
-    it('should return paginated users', () => {
-      return request(app.getHttpServer())
-        .get('/users')
-        .set('Authorization', `Bearer ${authToken}`)
-        .expect(200)
-        .expect((res) => {
-          expect(res.body).toHaveProperty('data');
-          expect(res.body).toHaveProperty('pagination');
-        });
-    });
-
-    it('should return 401 without auth token', () => {
-      return request(app.getHttpServer())
-        .get('/users')
-        .expect(401);
-    });
-  });
-});
-```
-
-## Use Cases
-
-### Microservices with Message Queue
+### Module Structure
 
 ```typescript
-// src/app.module.ts (Microservice)
-import { Module } from '@nestjs/common';
-import { ClientsModule, Transport } from '@nestjs/microservices';
-
 @Module({
-  imports: [
-    ClientsModule.register([
-      {
-        name: 'NOTIFICATION_SERVICE',
-        transport: Transport.RMQ,
-        options: {
-          urls: [process.env.RABBITMQ_URL],
-          queue: 'notifications_queue',
-          queueOptions: { durable: false },
-        },
-      },
-    ]),
-  ],
+  imports: [TypeOrmModule.forFeature([User])],
+  controllers: [UsersController],
+  providers: [UsersService, UsersRepository],
+  exports: [UsersService],
 })
-export class AppModule {}
-
-
-// src/notifications/notifications.service.ts
-import { Injectable, Inject } from '@nestjs/common';
-import { ClientProxy } from '@nestjs/microservices';
-
-@Injectable()
-export class NotificationsService {
-  constructor(
-    @Inject('NOTIFICATION_SERVICE') private client: ClientProxy,
-  ) {}
-
-  async sendWelcomeEmail(userId: string, email: string) {
-    return this.client.emit('user_welcome', { userId, email });
-  }
-}
+export class UsersModule {}
 ```
 
 ## Best Practices
 
-### Do's
-
-- Use modules to organize features
-- Use dependency injection throughout
-- Use DTOs for validation and transformation
-- Use interceptors for cross-cutting concerns
-- Use guards for authentication/authorization
-- Use custom decorators for cleaner code
-- Write unit and e2e tests
-- Use class-transformer for responses
-- Use environment configuration
-- Document APIs with Swagger
+| Do | Avoid |
+|----|-------|
+| Use dependency injection | Direct instantiation |
+| Validate with DTOs | Trusting input |
+| Use guards for auth | Auth logic in controllers |
+| Use interceptors for cross-cutting | Duplicating logging/transform |
+| Write unit + e2e tests | Skipping test coverage |
 
-### Don'ts
+## Project Structure
 
-- Don't put business logic in controllers
-- Don't skip input validation
-- Don't expose internal errors
-- Don't use any type unnecessarily
-- Don't skip authentication guards
-- Don't ignore database transactions
-- Don't hardcode configuration
-- Don't forget error handling
-- Don't skip testing
-- Don't use circular dependencies
-
-## References
+```
+src/
+├── main.ts
+├── app.module.ts
+├── common/
+│   ├── decorators/
+│   ├── guards/
+│   ├── interceptors/
+│   └── pipes/
+├── config/
+├── users/
+│   ├── users.module.ts
+│   ├── users.controller.ts
+│   ├── users.service.ts
+│   ├── dto/
+│   └── entities/
+└── auth/
+    ├── auth.module.ts
+    ├── strategies/
+    └── guards/
+```
 
-- [NestJS Documentation](https://docs.nestjs.com/)
-- [NestJS Best Practices](https://github.com/nestjs/awesome-nestjs)
-- [TypeORM Documentation](https://typeorm.io/)
-- [Passport.js Documentation](http://www.passportjs.org/)
-- [class-validator](https://github.com/typestack/class-validator)
+For detailed examples and patterns, see reference files above.