NestJS Controller Patterns (General)

This skill covers the shared principles and common utilities applicable to ALL controller types in erify_api.

Specialized Patterns

For module-specific controller implementation, refer to:

• •Admin Controllers: For admin/* endpoints (System Admins).
• •User (Me) Controllers: For me/* endpoints (Authenticated Users).
• •Backdoor Controllers: For backdoor/* endpoints (Service-to-Service).
• •Integration Controllers: For google-sheets/*, webhooks, etc.

Shared Principles

The following patterns apply across all controller types.

1. Response Serialization

ALL endpoints must use Zod for response serialization to ensure no internal data (like database IDs) leaks.

• •Use @ZodResponse(Schema, Status) for standard responses.
• •Use @ZodPaginatedResponse(Schema) for list endpoints.

@Get(':id')
@ZodResponse(UserDto)
async getUser(...)

2. Validation Pipes

Always use UidValidationPipe for validating uid parameters.

@Param('id', new UidValidationPipe(UserService.UID_PREFIX, 'User'))
id: string

3. DTO Standards

• •Request DTOs: Define validation rules using zod.
• •Response DTOs: Define output shape, excluding sensitive fields.
• •Pagination: Use PaginationQueryDto from @/lib/pagination/pagination.schema.

4. HTTP Status Codes

Checklist

• • Choose the correct specialized pattern (Admin, Me, Backdoor, Integration).
• • Use Zod serialization for ALL outputs.
• • Use UidValidationPipe for all UIDs.
• • Document all endpoints with Swagger/OpenAPI decorators (handled via @ZodResponse automatically where possible).