@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/guides/creating-services.mdx

@@ -0,0 +1,1736 @@
+---
+title: Creating Backend Services
+description: Complete guide to creating NestJS-based backend services for the Blue Alba Platform
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+import MermaidDiagram from '~/components/MermaidDiagram.astro';
+
+The Blue Alba Platform uses a microservices architecture with NestJS + Fastify as the primary framework for building high-performance, scalable backend services. This guide walks you through everything you need to create production-ready services that integrate seamlessly with the platform.
+
+## Overview
+
+Backend services in the Blue Alba Platform are independent, self-contained applications that handle specific business domains. They communicate with the gateway, integrate with databases, publish events, and provide RESTful APIs for frontend applications.
+
+---
+
+## Architecture
+
+The platform's microservices architecture uses a gateway pattern to route requests, handle authentication, and aggregate API documentation.
+
+<MermaidDiagram
+  title="Microservices Architecture"
+  code={`graph TB
+    A[Client Applications<br/>React UI Modules]:::client --> B[API Gateway<br/>pae-nestjs-gateway-service]:::gateway
+
+    B --> C[Application Catalog]:::catalog
+    B --> D[Authentication]:::auth
+    B --> E[Authorization]:::authz
+
+    B --> F[Microservice 1<br/>Habits Service]:::service
+    B --> G[Microservice 2<br/>Custom Service]:::service
+    B --> H[Microservice N<br/>...]:::service
+
+    F --> I[(PostgreSQL)]:::database
+    G --> I
+    H --> I
+
+    F --> J[Kafka<br/>Event Bus]:::kafka
+    G --> J
+    H --> J
+
+    K[pae-service-nestjs-sdk<br/>Service SDK]:::sdk --> F
+    K --> G
+    K --> H
+
+    L[pae-core<br/>Domain Entities]:::core --> B
+    L --> F
+    L --> G
+    L --> H
+
+    classDef client fill:#90EE90,color:#333
+    classDef gateway fill:#FFD700,color:#333
+    classDef catalog fill:#87CEEB,color:#333
+    classDef auth fill:#DDA0DD,color:#333
+    classDef authz fill:#FFB6C1,color:#333
+    classDef service fill:#87CEEB,color:#333
+    classDef database fill:#F0E68C,color:#333
+    classDef kafka fill:#FFA07A,color:#333
+    classDef sdk fill:#ADD8E6,color:#333
+    classDef core fill:#FFB6C1,color:#333`}
+/>
+
+### Architecture Components
+
+- **API Gateway**: Routes requests, handles authentication/authorization, aggregates API docs
+- **Microservices**: Domain-specific services (NestJS or Express) handling business logic
+- **Application Catalog**: Registry of all services and their routes
+- **Database**: PostgreSQL for persistence (shared or per-service)
+- **PAE Service SDK**: NestJS SDK providing common utilities and platform integration
+- **PAE Core**: Shared domain entities, types, and authorization logic
+
+---
+
+## Quick Start
+
+Create your first NestJS service in these steps:
+
+### 1. Install NestJS CLI
+
+```bash
+npm install -g @nestjs/cli
+```
+
+### 2. Create New Service
+
+```bash
+# Create new NestJS project
+nest new my-service
+
+# Navigate to project
+cd my-service
+```
+
+When prompted, choose **npm** as the package manager.
+
+### 3. Install Dependencies
+
+```bash
+# Install platform dependencies
+npm install @bluealba/pae-service-nestjs-sdk
+npm install @bluealba/pae-core
+
+# Install NestJS core dependencies
+npm install @nestjs/common@^11.0.0
+npm install @nestjs/core@^11.0.0
+npm install @nestjs/config@^4.0.2
+npm install @nestjs/platform-fastify@^11.0.0
+
+# Install Fastify
+npm install fastify@5.4.0
+
+# Install validation dependencies
+npm install class-validator class-transformer
+
+# Install HTTP client
+npm install @nestjs/axios
+```
+
+### 4. Update TypeScript Configuration
+
+Edit `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2021",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strictNullChecks": false,
+    "noImplicitAny": false,
+    "strictBindCallApply": false,
+    "forceConsistentCasingInFileNames": false,
+    "noFallthroughCasesInSwitch": false
+  }
+}
+```
+
+### 5. Configure Entry Point (main.ts)
+
+Replace the contents of `src/main.ts`:
+
+```typescript
+import { ValidationPipe } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter({
+      trustProxy: true,
+    }),
+  );
+
+  // Enable validation pipes for DTOs
+  app.useGlobalPipes(new ValidationPipe());
+
+  await app.listen({
+    host: '0.0.0.0',
+    port: 80,
+  });
+}
+
+bootstrap();
+```
+
+### 6. Configure App Module
+
+Update `src/app.module.ts`:
+
+```typescript
+import { PAEServiceModule } from '@bluealba/pae-service-nestjs-sdk';
+import { HttpModule } from '@nestjs/axios';
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+
+@Module({
+  imports: [
+    // Global configuration
+    ConfigModule.forRoot({
+      isGlobal: true,
+    }),
+
+    // HTTP client for external requests
+    HttpModule.register({
+      global: true,
+    }),
+
+    // Platform integration (health, version, changelog endpoints)
+    PAEServiceModule.forRoot({
+      healthPath: '/_/health',
+      versionPath: '/_/version',
+      changelogPath: '/_/changelog',
+    }),
+  ],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}
+```
+
+### 7. Update Package Scripts
+
+Update `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "build": "nest build",
+    "start:dev": "nest start --watch",
+    "start:prod": "node dist/src/main",
+    "test": "jest",
+    "test:unit": "jest",
+    "test:e2e": "jest --config ./test/jest-e2e.json",
+    "test:watch": "jest --watch"
+  }
+}
+```
+
+### 8. Test Your Service
+
+```bash
+# Run in development mode
+npm run start:dev
+
+# Service should be available at http://localhost:80
+# Health check: http://localhost:80/_/health
+# Version info: http://localhost:80/_/version
+```
+
+---
+
+## Project Structure
+
+A typical NestJS service follows this structure:
+
+```
+my-service/
+├── package.json              # Project configuration
+├── tsconfig.json            # TypeScript configuration
+├── nest-cli.json            # NestJS CLI configuration
+├── jest.config.js           # Jest testing configuration
+├── Dockerfile.development   # Development Docker image
+├── Dockerfile              # Production Docker image
+└── src/
+    ├── main.ts             # Application entry point
+    ├── app.module.ts       # Root application module
+    ├── app.controller.ts   # Example controller
+    ├── app.service.ts      # Example service
+    ├── config/             # Configuration files
+    │   └── configuration.ts
+    ├── users/              # Feature module (example)
+    │   ├── users.module.ts
+    │   ├── users.controller.ts
+    │   ├── users.service.ts
+    │   ├── dto/
+    │   │   ├── create-user.dto.ts
+    │   │   └── update-user.dto.ts
+    │   └── entities/
+    │       └── user.entity.ts
+    ├── common/             # Shared utilities
+    │   ├── guards/
+    │   ├── interceptors/
+    │   ├── filters/
+    │   └── decorators/
+    └── database/           # Database integration
+        └── database.module.ts
+```
+
+### Key Directories Explained
+
+<CardGrid>
+  <Card title="src/" icon="folder">
+    Main source code directory containing all application logic.
+  </Card>
+
+  <Card title="src/[feature]/" icon="puzzle">
+    Feature modules organized by domain (users, products, orders, etc.).
+  </Card>
+
+  <Card title="dto/" icon="document">
+    Data Transfer Objects for request validation and API contracts.
+  </Card>
+
+  <Card title="entities/" icon="seti:db">
+    Domain entities representing data models and business logic.
+  </Card>
+
+  <Card title="common/" icon="setting">
+    Shared utilities like guards, interceptors, decorators, and filters.
+  </Card>
+
+  <Card title="test/" icon="approve-check">
+    E2E tests for integration testing across modules.
+  </Card>
+</CardGrid>
+
+---
+
+## Development Workflow
+
+### Running Locally with Docker
+
+The recommended way to develop services is using Docker Compose, which provides a consistent environment and automatic integration with the platform.
+
+### Project Structure Setup
+
+Your repositories should be organized at the same level:
+
+```
+my-projects/
+├── my-product-local/          # Local environment with docker-compose.yml
+│   └── docker-compose.yml
+└── my-service/                # Your service repository
+    ├── Dockerfile.development
+    ├── package.json
+    └── src/
+```
+
+<Aside type="note">
+The docker-compose.yml uses `${PWD}/../my-service` to reference the service repository. This requires both repositories to be siblings in the same parent directory.
+</Aside>
+
+### Step 1: Create Development Dockerfile
+
+Create `Dockerfile.development` in your service repository:
+
+```dockerfile
+FROM node:20-alpine as development
+
+ENV NODE_ENV=development
+ENV PORT=80
+
+ARG BA_NPM_AUTH_TOKEN
+
+WORKDIR /app
+
+COPY package*.json ./
+
+RUN echo "@bluealba:registry=https://bluealba.jfrog.io/artifactory/api/npm/npm-release-virtual/" > .npmrc
+RUN echo "//bluealba.jfrog.io/artifactory/api/npm/npm-release-virtual/:_auth=${BA_NPM_AUTH_TOKEN}" >> .npmrc
+
+RUN npm install
+
+EXPOSE 80
+
+CMD ["npm", "run", "start:dev"]
+```
+
+**Key points:**
+- Uses Node 20 Alpine for a lightweight image
+- Sets `NODE_ENV=development` for development mode
+- Exposes port 80 (configurable)
+- Runs `start:dev` command for hot reload with NestJS watch mode
+
+### Step 2: Configure Docker Compose
+
+Add your service to `docker-compose.yml` in your local environment repository:
+
+```yaml
+services:
+  my-service:
+    build:
+      context: ../my-service
+      dockerfile: Dockerfile.development
+    args:
+        - BA_NPM_AUTH_TOKEN=$BA_NPM_AUTH_TOKEN
+    ports:
+      - 9002:80
+    environment:
+      - GATEWAY_URL=${PAE_GATEWAY_URL}
+    volumes:
+      - ${PWD}/../pae-sandbox-home-service:/app
+```
+
+**Configuration explained:**
+
+| Property | Description |
+|----------|-------------|
+| `context: ../my-service` | Path to your service repository (relative to compose file) |
+| `dockerfile: Dockerfile.development` | Development-specific Dockerfile |
+| `ports: 9002:80` | Maps host port 9002 to container port 80 |
+| `volumes` | Mounts your code for hot reload (changes reflect immediately) |
+| `environment` | Sets environment variables (database URL, etc.) |
+
+### Step 3: Start Development Environment
+
+From your local environment repository:
+
+```bash
+# Start your service
+docker-compose up my-service
+
+# Or start in detached mode
+docker-compose up -d my-service
+
+# View logs
+docker-compose logs -f my-service
+
+# Rebuild after dependency changes
+docker-compose up --build my-service
+```
+
+**What happens:**
+1. Docker builds the development image
+2. Installs npm dependencies inside the container
+3. Starts the NestJS dev server with watch mode (`nest start --watch`)
+4. Your code is mounted as a volume - changes trigger automatic rebuilds
+5. Service is accessible at `http://localhost:9002`
+
+### Step 4: Verify Service is Running
+
+```bash
+# Check health endpoint
+curl http://localhost:9002/_/health
+
+# Check version endpoint
+curl http://localhost:9002/_/version
+
+# Check changelog endpoint
+curl http://localhost:9002/_/changelog
+```
+
+---
+
+## Core Concepts
+
+### Controllers
+
+Controllers handle incoming HTTP requests and return responses to the client. They use decorators to define routes and HTTP methods.
+
+<Tabs>
+  <TabItem label="Basic Controller">
+
+```typescript
+import { Controller, Get, Post, Body, Param, Patch, Delete } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
+import { UsersService } from './users.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+
+@Controller('users')
+@ApiTags('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiResponse({ status: 201, description: 'User created successfully' })
+  create(@Body() createUserDto: CreateUserDto) {
+    return this.usersService.create(createUserDto);
+  }
+
+  @Get()
+  @ApiOperation({ summary: 'Get all users' })
+  findAll() {
+    return this.usersService.findAll();
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get user by ID' })
+  findOne(@Param('id') id: string) {
+    return this.usersService.findOne(+id);
+  }
+
+  @Patch(':id')
+  @ApiOperation({ summary: 'Update user by ID' })
+  update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {
+    return this.usersService.update(+id, updateUserDto);
+  }
+
+  @Delete(':id')
+  @ApiOperation({ summary: 'Delete user by ID' })
+  remove(@Param('id') id: string) {
+    return this.usersService.remove(+id);
+  }
+}
+```
+
+</TabItem>
+
+  <TabItem label="Query Parameters">
+
+```typescript
+import { Controller, Get, Query } from '@nestjs/common';
+import { ApiQuery } from '@nestjs/swagger';
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get()
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  @ApiQuery({ name: 'search', required: false, type: String })
+  findAll(
+    @Query('page') page?: string,
+    @Query('limit') limit?: string,
+    @Query('search') search?: string,
+  ) {
+    return this.usersService.findAll({
+      page: page ? parseInt(page) : 1,
+      limit: limit ? parseInt(limit) : 10,
+      search,
+    });
+  }
+}
+```
+
+</TabItem>
+
+  <TabItem label="Request Headers">
+
+```typescript
+import { Controller, Get, Headers, HttpCode } from '@nestjs/common';
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get('profile')
+  @HttpCode(200)
+  getProfile(@Headers('authorization') authHeader: string) {
+    // Extract and validate token
+    const token = authHeader?.replace('Bearer ', '');
+    return this.usersService.getProfile(token);
+  }
+}
+```
+
+</TabItem>
+
+  <TabItem label="Async Operations">
+
+```typescript
+import { Controller, Get, Post, Body } from '@nestjs/common';
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  async create(@Body() createUserDto: CreateUserDto) {
+    // Async/await for database operations
+    const user = await this.usersService.create(createUserDto);
+
+    // Trigger async tasks (email, notifications, etc.)
+    this.usersService.sendWelcomeEmail(user.email);
+
+    return user;
+  }
+
+  @Get()
+  async findAll(): Promise<User[]> {
+    return await this.usersService.findAll();
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Services
+
+Services contain business logic and are injected into controllers using dependency injection. They should be stateless and focused on a single responsibility.
+
+<Tabs>
+  <TabItem label="Basic Service">
+
+```typescript
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { User } from './entities/user.entity';
+
+@Injectable()
+export class UsersService {
+  private users: User[] = [];
+  private idCounter = 1;
+
+  create(createUserDto: CreateUserDto): User {
+    const user: User = {
+      id: this.idCounter++,
+      ...createUserDto,
+      createdAt: new Date(),
+    };
+    this.users.push(user);
+    return user;
+  }
+
+  findAll(): User[] {
+    return this.users;
+  }
+
+  findOne(id: number): User {
+    const user = this.users.find(u => u.id === id);
+    if (!user) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+    return user;
+  }
+
+  update(id: number, updateUserDto: UpdateUserDto): User {
+    const user = this.findOne(id);
+    Object.assign(user, updateUserDto);
+    return user;
+  }
+
+  remove(id: number): void {
+    const index = this.users.findIndex(u => u.id === id);
+    if (index === -1) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+    this.users.splice(index, 1);
+  }
+}
+```
+
+</TabItem>
+
+  <TabItem label="Database Service">
+
+```typescript
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { DatabaseService } from '../database/database.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { User } from './entities/user.entity';
+
+@Injectable()
+export class UsersService {
+  private readonly tableName = 'users';
+
+  constructor(private readonly dbService: DatabaseService) {}
+
+  async create(createUserDto: CreateUserDto): Promise<User> {
+    const [result] = await this.dbService.db(this.tableName)
+      .insert({
+        username: createUserDto.username,
+        email: createUserDto.email,
+        display_name: createUserDto.displayName,
+        created_at: new Date(),
+      })
+      .returning('*');
+
+    return User.fromDatabaseRow(result);
+  }
+
+  async findAll(): Promise<User[]> {
+    const result = await this.dbService.db(this.tableName)
+      .select('*')
+      .orderBy('created_at', 'desc');
+
+    return result.map(User.fromDatabaseRow);
+  }
+
+  async findOne(id: number): Promise<User> {
+    const [result] = await this.dbService.db(this.tableName)
+      .select('*')
+      .where('id', id);
+
+    if (!result) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+
+    return User.fromDatabaseRow(result);
+  }
+
+  async update(id: number, updateUserDto: UpdateUserDto): Promise<User> {
+    const [result] = await this.dbService.db(this.tableName)
+      .update({
+        username: updateUserDto.username,
+        email: updateUserDto.email,
+        display_name: updateUserDto.displayName,
+        updated_at: new Date(),
+      })
+      .where('id', id)
+      .returning('*');
+
+    if (!result) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+
+    return User.fromDatabaseRow(result);
+  }
+
+  async remove(id: number): Promise<void> {
+    const deleted = await this.dbService.db(this.tableName)
+      .delete()
+      .where('id', id);
+
+    if (!deleted) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+  }
+}
+```
+
+</TabItem>
+
+  <TabItem label="Service with Caching">
+
+```typescript
+import { Injectable, Inject, NotFoundException } from '@nestjs/common';
+import { Cache } from 'cache-manager';
+import { DatabaseService } from '../database/database.service';
+import { User } from './entities/user.entity';
+
+@Injectable()
+export class UsersService {
+  constructor(
+    private readonly dbService: DatabaseService,
+    @Inject('USERS_CACHE') private readonly cache: Cache,
+  ) {}
+
+  async findAll(): Promise<User[]> {
+    // Cache for 5 minutes
+    return this.cache.wrap<User[]>(
+      'all_users',
+      async () => {
+        const result = await this.dbService.db('users').select('*');
+        return result.map(User.fromDatabaseRow);
+      },
+      300000
+    );
+  }
+
+  async findOne(id: number): Promise<User> {
+    return this.cache.wrap<User>(
+      `user_${id}`,
+      async () => {
+        const [result] = await this.dbService.db('users')
+          .select('*')
+          .where('id', id);
+
+        if (!result) {
+          throw new NotFoundException(`User with ID ${id} not found`);
+        }
+
+        return User.fromDatabaseRow(result);
+      },
+      300000
+    );
+  }
+
+  async invalidateCache(id?: number): Promise<void> {
+    if (id) {
+      await this.cache.del(`user_${id}`);
+    }
+    await this.cache.del('all_users');
+  }
+}
+```
+
+</TabItem>
+
+  <TabItem label="Service with Dependencies">
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { HttpService } from '@nestjs/axios';
+import { firstValueFrom } from 'rxjs';
+import { EmailService } from '../email/email.service';
+import { LoggerService } from '../logger/logger.service';
+import { CreateUserDto } from './dto/create-user.dto';
+
+@Injectable()
+export class UsersService {
+  constructor(
+    private readonly httpService: HttpService,
+    private readonly emailService: EmailService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async create(createUserDto: CreateUserDto) {
+    this.logger.log('Creating new user', { username: createUserDto.username });
+
+    // Create user in database
+    const user = await this.saveUser(createUserDto);
+
+    // Send welcome email (async, don't block)
+    this.emailService.sendWelcomeEmail(user.email, user.displayName)
+      .catch(err => this.logger.error('Failed to send welcome email', err));
+
+    // Notify external system (await response)
+    try {
+      const response = await firstValueFrom(
+        this.httpService.post('https://external-api.com/users', user)
+      );
+      this.logger.log('User synced to external system', response.data);
+    } catch (error) {
+      this.logger.error('Failed to sync user to external system', error);
+    }
+
+    return user;
+  }
+
+  private async saveUser(createUserDto: CreateUserDto) {
+    // Implementation
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Modules
+
+Modules organize your application into cohesive blocks of functionality. Each feature should be its own module.
+
+<Tabs>
+  <TabItem label="Feature Module">
+
+```typescript
+import { Module } from '@nestjs/common';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+
+@Module({
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],  // Export if other modules need it
+})
+export class UsersModule {}
+```
+
+</TabItem>
+
+  <TabItem label="Module with Dependencies">
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DatabaseModule } from '../database/database.module';
+import { EmailModule } from '../email/email.module';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+
+@Module({
+  imports: [
+    DatabaseModule,  // Import other modules this module depends on
+    EmailModule,
+  ],
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}
+```
+
+</TabItem>
+
+  <TabItem label="Global Module">
+
+```typescript
+import { Global, Module } from '@nestjs/common';
+import { LoggerService } from './logger.service';
+
+@Global()  // Make this module available everywhere
+@Module({
+  providers: [LoggerService],
+  exports: [LoggerService],
+})
+export class LoggerModule {}
+```
+
+</TabItem>
+
+  <TabItem label="Dynamic Module">
+
+```typescript
+import { DynamicModule, Module } from '@nestjs/common';
+
+interface DatabaseOptions {
+  host: string;
+  port: number;
+  database: string;
+}
+
+@Module({})
+export class DatabaseModule {
+  static forRoot(options: DatabaseOptions): DynamicModule {
+    return {
+      module: DatabaseModule,
+      providers: [
+        {
+          provide: 'DATABASE_OPTIONS',
+          useValue: options,
+        },
+        DatabaseService,
+      ],
+      exports: [DatabaseService],
+      global: true,
+    };
+  }
+}
+
+// Usage in AppModule:
+// DatabaseModule.forRoot({ host: 'localhost', port: 5432, database: 'mydb' })
+```
+
+</TabItem>
+</Tabs>
+
+### DTOs and Validation
+
+Data Transfer Objects (DTOs) define the shape of data for requests and responses. Use `class-validator` for automatic validation.
+
+<Tabs>
+  <TabItem label="Create DTO">
+
+```typescript
+import { IsString, IsEmail, IsNotEmpty, MinLength, MaxLength } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateUserDto {
+  @ApiProperty({ description: 'User username', example: 'johndoe' })
+  @IsString()
+  @IsNotEmpty()
+  @MinLength(3)
+  @MaxLength(50)
+  username: string;
+
+  @ApiProperty({ description: 'User email address', example: 'john@example.com' })
+  @IsEmail()
+  @IsNotEmpty()
+  email: string;
+
+  @ApiProperty({ description: 'User display name', example: 'John Doe' })
+  @IsString()
+  @IsNotEmpty()
+  displayName: string;
+
+  @ApiProperty({ description: 'User password', example: 'StrongP@ss123' })
+  @IsString()
+  @IsNotEmpty()
+  @MinLength(8)
+  password: string;
+}
+```
+
+</TabItem>
+
+  <TabItem label="Update DTO">
+
+```typescript
+import { PartialType } from '@nestjs/mapped-types';
+import { CreateUserDto } from './create-user.dto';
+
+// All fields optional for updates
+export class UpdateUserDto extends PartialType(CreateUserDto) {}
+```
+
+</TabItem>
+
+  <TabItem label="Advanced Validation">
+
+```typescript
+import {
+  IsString,
+  IsNumber,
+  IsOptional,
+  IsEnum,
+  IsArray,
+  ValidateNested,
+  Min,
+  Max
+} from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiProperty } from '@nestjs/swagger';
+
+enum UserRole {
+  ADMIN = 'admin',
+  USER = 'user',
+  GUEST = 'guest',
+}
+
+class AddressDto {
+  @IsString()
+  street: string;
+
+  @IsString()
+  city: string;
+
+  @IsString()
+  zipCode: string;
+}
+
+export class CreateUserDto {
+  @ApiProperty()
+  @IsString()
+  username: string;
+
+  @ApiProperty({ enum: UserRole, default: UserRole.USER })
+  @IsEnum(UserRole)
+  @IsOptional()
+  role?: UserRole = UserRole.USER;
+
+  @ApiProperty({ minimum: 18, maximum: 120 })
+  @IsNumber()
+  @Min(18)
+  @Max(120)
+  age: number;
+
+  @ApiProperty({ type: [String] })
+  @IsArray()
+  @IsString({ each: true })
+  tags: string[];
+
+  @ApiProperty({ type: AddressDto })
+  @ValidateNested()
+  @Type(() => AddressDto)
+  address: AddressDto;
+}
+```
+
+</TabItem>
+
+  <TabItem label="Custom Validators">
+
+```typescript
+import {
+  registerDecorator,
+  ValidationOptions,
+  ValidatorConstraint,
+  ValidatorConstraintInterface
+} from 'class-validator';
+
+@ValidatorConstraint({ async: false })
+export class IsStrongPasswordConstraint implements ValidatorConstraintInterface {
+  validate(password: string) {
+    // At least 8 characters, 1 uppercase, 1 lowercase, 1 number, 1 special char
+    const regex = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$/;
+    return regex.test(password);
+  }
+
+  defaultMessage() {
+    return 'Password must be at least 8 characters with uppercase, lowercase, number, and special character';
+  }
+}
+
+export function IsStrongPassword(validationOptions?: ValidationOptions) {
+  return function (object: Object, propertyName: string) {
+    registerDecorator({
+      target: object.constructor,
+      propertyName: propertyName,
+      options: validationOptions,
+      constraints: [],
+      validator: IsStrongPasswordConstraint,
+    });
+  };
+}
+
+// Usage
+export class CreateUserDto {
+  @IsStrongPassword()
+  password: string;
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Dependency Injection
+
+NestJS uses dependency injection to manage dependencies between classes. This promotes loose coupling and testability.
+
+```typescript
+// Logger Service
+@Injectable()
+export class LoggerService {
+  log(message: string) {
+    console.log(`[LOG]: ${message}`);
+  }
+}
+
+// Users Service with dependency
+@Injectable()
+export class UsersService {
+  constructor(
+    private readonly logger: LoggerService,  // Injected automatically
+  ) {}
+
+  create(user: CreateUserDto) {
+    this.logger.log(`Creating user: ${user.username}`);
+    // ...
+  }
+}
+
+// Module configuration
+@Module({
+  providers: [
+    LoggerService,  // Register the service
+    UsersService,   // Can inject LoggerService
+  ],
+  exports: [UsersService],
+})
+export class UsersModule {}
+```
+
+---
+
+## Platform Integration
+
+### Using PAE Service SDK
+
+The PAE Service SDK provides common utilities for platform integration:
+
+```typescript
+import { PAEServiceModule } from '@bluealba/pae-service-nestjs-sdk';
+import { Module } from '@nestjs/common';
+
+@Module({
+  imports: [
+    PAEServiceModule.forRoot({
+      healthPath: '/_/health',      // GET /_/health
+      versionPath: '/_/version',     // GET /_/version
+      changelogPath: '/_/changelog', // GET /_/changelog
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+This automatically provides three endpoints:
+
+| Endpoint | Description | Source |
+|----------|-------------|--------|
+| `/_/health` | Returns `{ status: 'ok' }` for health checks | Built-in |
+| `/_/version` | Returns version from `package.json` | `package.json` |
+| `/_/changelog` | Returns changelog content | `CHANGELOG.md` |
+
+### Swagger/OpenAPI Documentation
+
+Add API documentation using the PAE Service SDK:
+
+<Tabs>
+  <TabItem label="Setup in main.ts">
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { ApiDocsService } from '@bluealba/pae-service-nestjs-sdk';
+import packageJSON from '../package.json';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Setup Swagger
+  const apiDocsService = app.get(ApiDocsService);
+  apiDocsService.setup(app, {
+    title: 'My Service API',
+    description: 'API documentation for My Service',
+    version: packageJSON.version,
+    tags: ['Users', 'Products'],
+  });
+
+  await app.listen(80);
+}
+
+bootstrap();
+```
+
+</TabItem>
+
+  <TabItem label="Add to Module">
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ApiDocsModule } from '@bluealba/pae-service-nestjs-sdk';
+import { UsersModule } from './users/users.module';
+
+@Module({
+  imports: [
+    ApiDocsModule,  // Required for API docs
+    UsersModule,
+  ],
+})
+export class AppModule {}
+```
+
+</TabItem>
+
+  <TabItem label="Document Endpoints">
+
+```typescript
+import { Controller, Get, Post, Body } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse, ApiBody } from '@nestjs/swagger';
+import { UsersService } from './users.service';
+import { CreateUserDto } from './dto/create-user.dto';
+
+@Controller('users')
+@ApiTags('users')  // Group in Swagger UI
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiBody({ type: CreateUserDto })
+  @ApiResponse({ status: 201, description: 'User created successfully' })
+  @ApiResponse({ status: 400, description: 'Invalid input' })
+  create(@Body() createUserDto: CreateUserDto) {
+    return this.usersService.create(createUserDto);
+  }
+
+  @Get()
+  @ApiOperation({ summary: 'Get all users' })
+  @ApiResponse({ status: 200, description: 'List of users' })
+  findAll() {
+    return this.usersService.findAll();
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+Swagger UI will be available at `http://localhost/api-docs` by default.
+
+### Authentication with Gateway
+
+Services receive authenticated requests from the gateway with user context in headers:
+
+```typescript
+import { Controller, Get, Headers } from '@nestjs/common';
+
+@Controller('profile')
+export class ProfileController {
+  @Get()
+  getProfile(@Headers('x-forwarded-user-id') userId: string) {
+    // userId is extracted from JWT by gateway
+    return { userId, message: 'User profile' };
+  }
+}
+```
+
+The gateway sets these headers after authentication:
+- `x-forwarded-user-id`: User's unique identifier
+- `x-forwarded-user-email`: User's email
+- `x-forwarded-user-operations`: Comma-separated list of granted operations
+
+### Authorization
+
+Use operations from `@bluealba/pae-core` for authorization:
+
+```typescript
+import { Controller, Get, Headers, ForbiddenException } from '@nestjs/common';
+
+@Controller('users')
+export class UsersController {
+  @Get('admin')
+  getAdminData(@Headers('x-forwarded-user-operations') operations: string) {
+    const userOps = operations?.split(',') || [];
+
+    if (!userOps.includes('users::admin::read')) {
+      throw new ForbiddenException('Insufficient permissions');
+    }
+
+    return { data: 'Admin data' };
+  }
+}
+```
+
+---
+
+## Catalog Registration
+
+Services must register with the application catalog to be discovered by the gateway.
+
+<Tabs>
+  <TabItem label="Via API">
+
+```bash
+POST /api/catalog
+Content-Type: application/json
+Authorization: Bearer <admin-jwt>
+
+{
+  "name": "@myorg/my-service",
+  "type": "service",
+  "displayName": "My Service",
+  "baseUrl": "/api/my-service",
+  "host": "my-service",
+  "port": 80,
+  "authorization": {
+    "operations": [
+      "my-service::read",
+      "my-service::write"
+    ]
+  }
+}
+```
+
+</TabItem>
+
+  <TabItem label="Via Bootstrap">
+
+For automated deployments, include in bootstrap configuration:
+
+```json
+{
+  {
+    "name": "@myorg/my-service",
+    "displayName": "My Service",
+    "description": "My custom service",
+    "type": "service",
+    "baseUrl": "/api/my-service",
+    "service": {
+      "host": "my-service",
+      "port": 80
+    },
+    "authorization": {
+      "routes": [
+        {
+          pattern: '/api/v1/users',
+          operations: ["my-service::read"],
+          methods: ['GET'],
+        }
+      ]
+    }
+  }
+}
+```
+
+</TabItem>
+
+  <TabItem label="Configuration Fields">
+
+| Field | Description | Required |
+|-------|-------------|----------|
+| `name` | Unique service identifier (use @scope/name format) | Yes |
+| `displayName` | Human-readable service name | Yes |
+| `type` | Always `"service"` for backend services | Yes |
+| `baseUrl` | API path prefix (e.g., `/api/my-service`) | Yes |
+| `host` | Docker service name or hostname | Yes |
+| `port` | Service port (usually 80 in Docker) | Yes |
+| `authorization.operations` | List of operations required by this service | No |
+| `authorization.routes` | List of operations that this service requires for each of the endpoints | No |
+
+</TabItem>
+</Tabs>
+
+---
+
+## Best Practices
+
+### Code Organization
+
+<CardGrid>
+  <Card title="Feature-Based Modules" icon="folder">
+    Organize code by business domain (users, products, orders) rather than technical layers.
+  </Card>
+
+  <Card title="Single Responsibility" icon="document">
+    Each service should handle one concern. Keep controllers thin and services focused.
+  </Card>
+
+  <Card title="Dependency Injection" icon="puzzle">
+    Use constructor injection for all dependencies. Avoid service locator pattern.
+  </Card>
+
+  <Card title="Error Handling" icon="warning">
+    Use NestJS built-in exceptions. Create custom exceptions for domain errors.
+  </Card>
+</CardGrid>
+
+**Recommended Module Structure:**
+
+```
+src/
+├── users/
+│   ├── users.module.ts
+│   ├── users.controller.ts
+│   ├── users.service.ts
+│   ├── dto/
+│   │   ├── create-user.dto.ts
+│   │   └── update-user.dto.ts
+│   ├── entities/
+│   │   └── user.entity.ts
+│   └── tests/
+│       ├── users.controller.spec.ts
+│       └── users.service.spec.ts
+└── products/
+    ├── products.module.ts
+    ├── products.controller.ts
+    ├── products.service.ts
+    └── ...
+```
+
+### Error Handling
+
+```typescript
+import {
+  BadRequestException,
+  NotFoundException,
+  ConflictException,
+  InternalServerErrorException
+} from '@nestjs/common';
+
+@Injectable()
+export class UsersService {
+  async findOne(id: number) {
+    const user = await this.db.findById(id);
+
+    if (!user) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+
+    return user;
+  }
+
+  async create(dto: CreateUserDto) {
+    const existing = await this.db.findByEmail(dto.email);
+
+    if (existing) {
+      throw new ConflictException(`User with email ${dto.email} already exists`);
+    }
+
+    try {
+      return await this.db.create(dto);
+    } catch (error) {
+      throw new InternalServerErrorException('Failed to create user');
+    }
+  }
+}
+```
+
+### Logging
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class UsersService {
+  private readonly logger = new Logger(UsersService.name);
+
+  async create(dto: CreateUserDto) {
+    this.logger.log(`Creating user: ${dto.username}`);
+
+    try {
+      const user = await this.db.create(dto);
+      this.logger.log(`User created successfully: ${user.id}`);
+      return user;
+    } catch (error) {
+      this.logger.error(`Failed to create user: ${error.message}`, error.stack);
+      throw error;
+    }
+  }
+}
+```
+
+### Testing
+
+<Tabs>
+  <TabItem label="Unit Test">
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { UsersService } from './users.service';
+import { DatabaseService } from '../database/database.service';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let dbService: DatabaseService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        {
+          provide: DatabaseService,
+          useValue: {
+            db: jest.fn(() => ({
+              select: jest.fn().mockReturnThis(),
+              where: jest.fn().mockResolvedValue([{ id: 1, username: 'test' }]),
+            })),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<UsersService>(UsersService);
+    dbService = module.get<DatabaseService>(DatabaseService);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  it('should find a user by id', async () => {
+    const user = await service.findOne(1);
+    expect(user).toEqual({ id: 1, username: 'test' });
+  });
+});
+```
+
+</TabItem>
+
+  <TabItem label="Controller Test">
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+
+describe('UsersController', () => {
+  let controller: UsersController;
+  let service: UsersService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [UsersController],
+      providers: [
+        {
+          provide: UsersService,
+          useValue: {
+            findAll: jest.fn().mockResolvedValue([{ id: 1, username: 'test' }]),
+            findOne: jest.fn().mockResolvedValue({ id: 1, username: 'test' }),
+            create: jest.fn().mockResolvedValue({ id: 1, username: 'test' }),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get<UsersController>(UsersController);
+    service = module.get<UsersService>(UsersService);
+  });
+
+  it('should return an array of users', async () => {
+    const result = await controller.findAll();
+    expect(result).toEqual([{ id: 1, username: 'test' }]);
+    expect(service.findAll).toHaveBeenCalled();
+  });
+});
+```
+
+</TabItem>
+
+  <TabItem label="E2E Test">
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import * as request from 'supertest';
+import { AppModule } from './../src/app.module';
+
+describe('UsersController (e2e)', () => {
+  let app: INestApplication;
+
+  beforeEach(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('/users (GET)', () => {
+    return request(app.getHttpServer())
+      .get('/users')
+      .expect(200)
+      .expect((res) => {
+        expect(Array.isArray(res.body)).toBe(true);
+      });
+  });
+
+  it('/users (POST)', () => {
+    return request(app.getHttpServer())
+      .post('/users')
+      .send({ username: 'test', email: 'test@example.com' })
+      .expect(201)
+      .expect((res) => {
+        expect(res.body).toHaveProperty('id');
+        expect(res.body.username).toBe('test');
+      });
+  });
+});
+```
+
+</TabItem>
+
+</Tabs>
+
+---
+
+## Troubleshooting
+
+<Tabs>
+  <TabItem label="Build Failures">
+
+**Problem: Module not found errors**
+
+```
+Error: Cannot find module '@bluealba/pae-service-nestjs-sdk'
+```
+
+**Solution:**
+```bash
+# Install missing dependencies
+npm install
+
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+---
+
+**Problem: TypeScript compilation errors**
+
+```
+error TS2304: Cannot find name 'Express'
+```
+
+**Solution:**
+```bash
+# Install type definitions
+npm install --save-dev @types/node @types/express
+
+# Rebuild
+npm run build
+```
+
+</TabItem>
+
+  <TabItem label="Runtime Errors">
+
+**Problem: Service doesn't start**
+
+```
+Error: listen EADDRINUSE: address already in use :::80
+```
+
+**Solution:**
+```bash
+# Check what's using port 80
+lsof -i :80
+
+# Kill the process or change port
+PORT=3000 npm run start:dev
+```
+
+---
+
+**Problem: Database connection fails**
+
+```
+Error: connect ECONNREFUSED 127.0.0.1:5432
+```
+
+**Solution:**
+1. Verify database is running:
+   ```bash
+   docker-compose ps postgres
+   ```
+
+2. Check environment variables:
+   ```bash
+   echo $DATABASE_URL
+   ```
+
+3. Test connection manually:
+   ```bash
+   psql -h localhost -U user -d mydb
+   ```
+
+</TabItem>
+
+  <TabItem label="Docker Issues">
+
+**Problem: Container exits immediately**
+
+```bash
+# View logs
+docker-compose logs my-service
+
+# Common causes:
+# - npm install failed
+# - Missing environment variables
+# - Syntax error in code
+```
+
+**Solution:**
+```bash
+# Rebuild with no cache
+docker-compose build --no-cache my-service
+
+# Run interactively to debug
+docker-compose run my-service sh
+```
+
+---
+
+**Problem: Code changes not reflected**
+
+**Solution:**
+```bash
+# Ensure volume mount is correct in docker-compose.yml
+volumes:
+  - ../my-service:/app/out/apps/my-service
+
+# Restart with rebuild
+docker-compose up --build my-service
+```
+
+</TabItem>
+
+</Tabs>
+
+---
+
+## Related Documentation
+
+- **[Architecture Overview](../architecture/overview)** - Understand platform architecture
+- **[Gateway Architecture](../architecture/gateway-architecture)** - Learn about the API gateway
+- **[Authentication System](../architecture/authentication-system)** - Understand authentication flows
+- **[Authorization System](../architecture/authorization-system)** - Master operations and RBAC
+- **[Multi-Tenancy](../architecture/multi-tenancy)** - Learn about tenant isolation
+- **[Creating UI Modules](./creating-ui-modules)** - Build frontend applications
+- **[Using Feature Flags](./using-feature-flags)** - Implement feature toggles