Backend Dev Guidelines

Backend Development Guidelines

Purpose

Establish consistency and best practices across backend microservices (web-server) using modern Node.js/NestJS/TypeScript patterns.

When to Use

Auto-activates when working on:

• Creating or modifying routes, endpoints, APIs
• Building controllers, services, repositories
• Implementing middleware (auth, validation, error handling)
• DTOs with class-validator
• Database operations (via data-access-layer)
• Swagger documentation
• Authentication/authorization (login, logout, session management, RBAC)
• Guards and decorators (@Authorize, @IgnoreAuthorization)
• Logging and error handling
• Backend testing and refactoring

CRITICAL: Implementation Workflow

Before writing ANY code, you MUST:

1. ✅ Read the relevant resource guides for your task (see Navigation Guide below)
2. ✅ Use the "New Backend Feature Checklist" as your TODO list DO NOT:

• ❌ Start by reading existing implementations
• ❌ Copy-paste from existing files without reading the guides
• ❌ Create an abbreviated version of the checklist

Quick Start

New Backend Feature Checklist

• Dto: Create [Entity]Dto in packages/types/src/dto/[entity].dto.ts (see types-guide.md)
• Entity: Create [Entity] entity in packages/data-access-layer/src/features/[entity]/entities/[entity].entity.ts
• DbService: [Entity]DbService in packages/data-access-layer/src/features/[entity]/services/[entity]-db.service.ts (see database-patterns-guide.md)
• Controller: [Entity]Controller in apps/web-server/src/app/features/[entity]/[entity].controller.ts (see controllers-guide.md)
• Service: Create [Entity]Service in apps/web-server/src/app/features/[entity]/[entity].service.ts (see services-guide.md)
• Mapper: [Entity]Mapper in apps/web-server/src/app/features/[entity]/[entity].mapper.ts (see services-guide.md)
• Register: register new DbServices and Entities in data-access.module (see database-patterns-guide.md)
• Unit Tests: Write comprehensive unit tests for all components with business logic (see testing-guide.md)
• Verify Tests Pass: Run: npm run test. 100% of tests should pass. If not fix until all pass
• Code Coverage: Run: npm run test:coverage. Review coverage report and write tests for any untested files with business logic. Achieve 80% coverage (statements, lines, branches 60%, functions 60%) (see code-coverage-guide.md)
• API Documentation: Write API Endpoint documentation (see api-documentation-guide.md)
• Client API Generate: Run: npm run gen-api-client
• Verify Format: Run: npm run format:fix
• Verify Lint: Run: npm run lint
• Verify Build: Run: npm run build

New Microservice Checklist

• Directory structure: Create feature modules pattern (see architecture-overview.md)
• App Module: Configure root module with imports, controllers, providers
• Data Access Module: Set up TypeORM connection and register entities
• Exception Filter: Register global AllExceptionsFilter in main.ts
• Logging: Configure nestjs-pino with proper log levels
• Swagger: Set up OpenAPI documentation in main.ts
• Validation: Enable global ValidationPipe with class-validator
• Auth Guard: Configure @Authorize() decorator and JWT validation
• Testing: Set up Jest with test-setup.ts configuration
• Health Check: Add /health endpoint for monitoring

Architecture

Layered Flow

HTTP Request → Controller → Service → DbService → TypeORM → Database

Key Principle: Each layer has ONE responsibility.

See architecture-overview.md for complete details.

Directory Structure

  apps/web-server/src/
  ├── app/
  │   ├── auth/                          # Authentication feature
  │   │   ├── auth.controller.ts         # Auth endpoints (login, logout, etc.)
  │   │   ├── auth.service.ts            # Auth business logic
  │   │   ├── auth-mapper.service.ts     # DTO ↔ Entity mapping
  │   │   └── auth.module.ts             # Auth module
  │   │
  │   ├── features/                      # Feature modules
  │   │   ├── user/                      # User management feature
  │   │   │   ├── user.controller.ts     # User CRUD endpoints
  │   │   │   ├── user.service.ts        # User business logic
  │   │   │   ├── user.mapper.ts         # User DTO ↔ Entity mapping
  │   │   │   └── user.module.ts         # User module
  │   │   │
  │   │   ├── example/                   # Example feature (reference)
  │   │   │   ├── example.controller.ts
  │   │   │   ├── example.service.ts
  │   │   │   └── example.module.ts
  │   │   │
  │   │   ├── sync-events/               # Server-Sent Events feature
  │   │   │   ├── sync-events.controller.ts
  │   │   │   └── sync-events.module.ts
  │   │   │
  │   │   └── exceptions/                # Exception testing endpoints
  │   │       ├── exceptions.controller.ts
  │   │       └── exceptions.module.ts
  │   │
  │   ├── health/                        # Health check
  │   │   └── health.controller.ts       # Health endpoint
  │   │
  │   ├── app.module.ts                  # Root application module
  │   ├── app-initializer-service.ts     # App initialization logic
  │   └── data-access.module.ts          # Data access layer module setup
  │
  ├── common/                            # Shared utilities
  │   ├── base.mapper.ts                 # Base mapper class
  │   └── all-exceptions.filter.ts       # Global exception filter
  │
  ├── assets/                            # Static assets
  │
  ├── main.ts                            # Application entry point
  └── test-setup.ts                      # Jest test configuration

Naming Conventions:

• Files: kebab-case - user.controller.ts, user.service.ts, user.mapper.ts
• Classes: PascalCase - UserController, UserService, UserMapper

Core Principles (8 Key Rules)

1. Let Services Throw, Controllers Delegate

// ✅ Service throws business exceptions
async findOne(id: string): Promise<ClientUserDto> {
  const user = await this.userDbService.findById(id);
  if (!user) {
    throw new NotFoundException(`User ${id} not found`);
  }
  return this.userMapper.toDto(user);
}

// ✅ Controller just delegates - no try/catch needed
@Get(':id')
async findOne(@Param('id') id: string): Promise<ClientUserDto> {
  return this.userService.findOne(id);
}

Key points:

• ✅ Services throw NotFoundException, ConflictException, BadRequestException
• ✅ Controllers delegate to services - no try/catch blocks
• ✅ Global exception filter handles all errors automatically
• ❌ No manual handleError() methods needed

→ See services-guide.md and controllers-guide.md

2. Authorize requests using guard middleware

  @Authorize(Role.Admin)
  async create(@Body(ValidationPipe) createUserDto: CreateUserDto): Promise<ClientUserDto> {
    return await this.userService.create(createUserDto);
  }

→ See auth-session-guide.md

3. Validate input using class-validator

  async create(@Body(ValidationPipe) createUserDto: CreateUserDto): Promise<ClientUserDto> {
    return this.userService.create(createUserDto);
  }

→ See types-guide.md and controllers-guide.md

4. Use Swagger decorators for API documentation

     @ApiOperation({ summary: 'Create user' })
     @ApiResponse({ status: 201, type: ClientUserDto })
     async create(@Body(ValidationPipe) createUserDto: CreateUserDto): Promise<ClientUserDto> {
       return this.userService.create(createUserDto);
     }

→ See api-documentation-guide.md

5. Use Mapper to transform an entity to DTO

In the service use toDto() to return a DTO object

     async create(createUserDto: CreateUserDto): Promise<ClientUserDto> {
       // Create via DbService
       const user = await this.userDbService.create(createUserDto);

       // Map Entity → DTO
       return this.userMapper.toDto(user); 
     }

→ See services-guide.md

6. Use DbService for database access

// ✅ ALWAYS
const entity = await this.userDbService.create(createUserDto);

→ See database-patterns-guide.md

7. Constructor Conventions and Logger Setup

@Injectable()
export class UserService {
  constructor(
    private readonly userDbService: UserDbService,
    private readonly userMapper: UserMapper,
    private readonly logger: PinoLogger,
  ) {
    this.logger.setContext(UserService.name); // REQUIRED
  }
}

Key points:

• ✅ Use private readonly for all injected dependencies
• ✅ Set logger context in constructor: this.logger.setContext(ClassName.name)
• ✅ Register providers in module's providers array

→ See services-guide.md and logging-guide.md

8. Generate API Client After Controller Changes

After modifying controllers, ALWAYS run:

npm run gen-api-client

What it does:

• Reads NestJS controllers and decorators
• Extracts HTTP methods, paths, parameters, return types
• Generates type-safe Angular services in @ai-nx-starter/api-client
• Ensures frontend always matches backend API contract

Example:

// Backend: UserController
@Post()
@ApiOperation({ summary: 'Create user' })
@ApiResponse({ status: 201, type: ClientUserDto })
async create(@Body() dto: CreateUserDto): Promise<ClientUserDto> { ... }

// ↓ Auto-generates ↓

// Frontend: ApiUserService
create(dto: CreateUserDto): Observable<ClientUserDto> {
  return this.http.post<ClientUserDto>(`${this.BASE_URL}/users`, dto);
}

Why this matters:

• ✅ Type-safe API calls in Angular
• ✅ Breaking changes caught at compile time
• ✅ No manual HTTP service writing
• ❌ Never create manual HTTP services - always auto-generate

Navigation Guide

Resource Files

architecture-overview.md

Layered architecture, request lifecycle, separation of concerns

types-guide.md

Types Package & DTOs - Complete guide for DTOs, enums, constants, validation, naming conventions, and organization

controllers-guide.md

Controller definitions, error handling, examples

services-guide.md

Service patterns, Mapper integration, error handling, async patterns

database-patterns-guide.md

DbService, TypeORM entities, MongoDB queries, data access patterns

auth-session-guide.md

Authentication, authorization, session management, RBAC, Redis sessions

logging-guide.md

Structured logging with Pino, PinoLogger usage, log levels, best practices

security-guide.md

Input validation, authorization, sensitive data protection, password security, CORS, rate limiting

api-documentation-guide.md

Swagger documentation guidelines for API endpoints

testing-guide.md

AI testing guidelines, coverage decisions, proactive test generation policy

code-coverage-guide.md

Coverage exclusion guidelines, decision framework, what to test vs exclude

Skill Status: COMPLETE ✅ Line Count: < 500 ✅ Progressive Disclosure: 11 resource files ✅