@breadstone/archipel-mcp 0.0.16 → 0.0.17

package/data/guides/controller-best-practices.md

@@ -0,0 +1,766 @@
+---
+title: Controller Best Practices
+description: Structure, annotate, and implement NestJS controllers following Archipel conventions — regions, dependency injection, ResponseReturn, guards, and the @Api decorator.
+order: 4
+---
+
+# Controller Best Practices
+
+This guide defines the canonical structure of a NestJS controller in an Archipel-powered application. Controllers are the HTTP boundary — they map transport concerns (routes, headers, status codes) to service calls and response objects. **No business logic lives here.**
+
+If you haven't set up OpenAPI documentation yet, read the [OpenAPI & Feature Discovery](/guides/openapi-and-feature-discovery) guide first.
+
+---
+
+## Anatomy of a Controller
+
+Every controller follows the same skeleton: **Imports → Class decorator → Regions (Fields, Ctor, Methods)**. No other regions are allowed.
+
+```typescript
+// #region Imports
+
+import { Body, Controller, Get, HttpStatus, Post, Query, UseGuards } from '@nestjs/common';
+import { Api } from '@breadstone/archipel-platform-openapi';
+import { Public, ResponseReturn, IpAddress, UserAgent } from '@breadstone/archipel-platform-core';
+import { JwtAuthGuard, Token, User, type IAuthSubject } from '@breadstone/archipel-platform-authentication';
+import { CreateOrderRequest, OrderResponse, OrderListResponse } from '../models';
+
+// #endregion
+
+@Api({ tags: ['Orders'] })
+@Controller('api/orders')
+export class OrderController {
+
+    // #region Fields
+
+    private readonly _orderService: OrderService;
+
+    // #endregion
+
+    // #region Ctor
+
+    /**
+     * Constructs a new instance of the `OrderController` class.
+     *
+     * @public
+     */
+    public constructor(orderService: OrderService) {
+        this._orderService = orderService;
+    }
+
+    // #endregion
+
+    // #region Methods
+
+    // ... endpoint methods
+
+    // #endregion
+
+}
+```
+
+### Key Rules
+
+| Rule | Why |
+|------|-----|
+| Controllers use **constructor injection** (not `inject()`) | Framework requires it for request-scoped providers; keeps DI explicit |
+| Private fields prefixed with `_` | Coding standard — distinguishes injected dependencies from local variables |
+| Regions in strict order: Fields → Ctor → Methods | Consistency across the entire codebase |
+| No business logic in controllers | Controllers are I/O adapters; logic belongs in services |
+| No direct Prisma/repository calls | Services orchestrate data access; controllers never touch persistence |
+
+---
+
+## Class-Level Decorators
+
+Apply `@Api({ tags })` and `@Controller(path)` at class level. The tag groups all endpoints under a single OpenAPI section.
+
+```typescript
+@Api({ tags: ['Auth'] })
+@Controller('api/auth')
+export class AuthController { ... }
+```
+
+For versioned APIs, include the version in the path:
+
+```typescript
+@Api({ tags: ['Users'] })
+@Controller('api/v1/users')
+export class UserController { ... }
+```
+
+---
+
+## Dependency Injection
+
+Controllers receive services via constructor parameters. Store them in private `readonly` fields.
+
+```typescript
+// #region Fields
+
+private readonly _userService: UserService;
+private readonly _verificationService: VerificationService;
+private readonly _userNameGeneratorService: UserNameGeneratorService;
+
+// #endregion
+
+// #region Ctor
+
+public constructor(
+    userService: UserService,
+    verificationService: VerificationService,
+    userNameGeneratorService: UserNameGeneratorService
+) {
+    this._userService = userService;
+    this._verificationService = verificationService;
+    this._userNameGeneratorService = userNameGeneratorService;
+}
+
+// #endregion
+```
+
+**Never** create service instances manually. NestJS resolves the dependency graph automatically via the module system.
+
+---
+
+## ResponseReturn
+
+Every endpoint returns `Promise<ResponseReturn<T>>`. This wrapper provides a consistent response envelope with `success`, `status`, `data`, `error`, and `timestamp` fields.
+
+### Success Responses
+
+| Factory Method | HTTP Status | Use Case |
+|---------------|-------------|----------|
+| `ResponseReturn.ok(Type, data)` | 200 | Returning data (GET, POST with result) |
+| `ResponseReturn.created(Type, data)` | 201 | Resource creation |
+| `ResponseReturn.accepted(Type, data)` | 202 | Async processing started |
+| `ResponseReturn.noContent()` | 204 | Mutations with no response body |
+
+### Examples
+
+```typescript
+// 200 OK — return data
+public async login(
+    @Body() body: AuthLoginRequest
+): Promise<ResponseReturn<AuthLoginResponse>> {
+    const result = await this._userService.signIn(body.login, body.password);
+    return ResponseReturn.ok(AuthLoginResponse, {
+        accessToken: result.accessToken,
+        mfaRequired: result.mfaRequired
+    });
+}
+
+// 204 No Content — mutation without response body
+public async register(
+    @Body() body: AuthRegisterRequest
+): Promise<ResponseReturn<void>> {
+    await this._userService.signUp(body.email, body.password, body.type);
+    return ResponseReturn.noContent();
+}
+```
+
+The first argument to `ok()` / `created()` is the **response DTO class** — `ResponseReturn` uses `class-transformer` internally to ensure the response matches the declared shape. This prevents accidentally leaking internal fields.
+
+### What NOT to Do
+
+```typescript
+// ❌ BAD — inline object literal without ResponseReturn
+public async getUser(): Promise<{ id: string; name: string }> {
+    const user = await this._userService.find(id);
+    return { id: user.id, name: user.name };
+}
+
+// ❌ BAD — raw service entity as response
+public async getUser(): Promise<UserEntity> {
+    return this._userService.find(id);
+}
+
+// ✅ GOOD — ResponseReturn with typed DTO
+public async getUser(): Promise<ResponseReturn<UserResponse>> {
+    const result = await this._userService.find(id);
+    return ResponseReturn.ok(UserResponse, result);
+}
+```
+
+---
+
+## Guards and Decorators
+
+### Authentication Guard
+
+Use `@UseGuards(JwtAuthGuard)` for protected endpoints. Extract the authenticated user with `@User()`:
+
+```typescript
+@Get('me')
+@UseGuards(JwtAuthGuard)
+@Api({
+    auth: 'bearer',
+    operation: {
+        operationId: 'me',
+        description: 'Gets the current user.',
+        summary: 'Get current user'
+    },
+    responses: [{
+        status: HttpStatus.OK,
+        description: 'Authenticated user profile.',
+        type: UserResponse
+    }, {
+        status: HttpStatus.UNAUTHORIZED,
+        description: 'Authentication is required.'
+    }]
+})
+public async me(
+    @User() user: IAuthSubject
+): Promise<ResponseReturn<UserResponse>> {
+    const result = await this._userService.find({ id: user.id });
+    return ResponseReturn.ok(UserResponse, result);
+}
+```
+
+### Public Routes
+
+Mark unauthenticated endpoints with `@Public()`. This bypasses the global JWT guard if one is registered:
+
+```typescript
+@Post('register')
+@Public()
+public async register(@Body() body: RegisterRequest): Promise<ResponseReturn<void>> { ... }
+```
+
+### Token Extraction
+
+Use `@Token()` when you need the raw JWT string (e.g., for logout or refresh):
+
+```typescript
+@Post('logout')
+@UseGuards(JwtAuthGuard)
+public async logout(@Token() token: string): Promise<ResponseReturn<void>> {
+    await this._userService.signOut(token);
+    return ResponseReturn.noContent();
+}
+```
+
+### Custom Parameter Decorators
+
+Archipel provides built-in decorators for common request data:
+
+| Decorator | Extracts | Typical Use |
+|-----------|----------|-------------|
+| `@User()` | `request.user` as `IAuthSubject` | Authenticated user identity |
+| `@Token()` | Bearer token string | Logout, refresh |
+| `@IpAddress()` | Client IP address | Audit logging, rate limiting |
+| `@UserAgent()` | User-Agent header | Device tracking, session metadata |
+
+---
+
+## Annotating with @Api
+
+Every endpoint **must** have an `@Api()` decorator with `operation` and `responses`. This generates accurate OpenAPI documentation.
+
+### Minimal Annotation
+
+```typescript
+@Get()
+@Api({
+    operation: {
+        operationId: 'listOrders',
+        description: 'Lists all orders for the authenticated user.',
+        summary: 'List orders'
+    },
+    responses: [{
+        status: HttpStatus.OK,
+        description: 'List of orders.',
+        type: OrderListResponse
+    }]
+})
+public async listOrders(): Promise<ResponseReturn<OrderListResponse>> { ... }
+```
+
+### Full Annotation with Body, Query, and Auth
+
+```typescript
+@Post('login')
+@Api({
+    operation: {
+        operationId: 'login',
+        description: 'Logs the user in and returns an access token.',
+        summary: 'Authenticate user'
+    },
+    body: {
+        description: 'Credentials used for authentication.',
+        type: AuthLoginRequest
+    },
+    responses: [{
+        status: HttpStatus.OK,
+        description: 'Access token successfully generated.',
+        type: AuthLoginResponse
+    }, {
+        status: HttpStatus.UNAUTHORIZED,
+        description: 'Provided credentials are invalid.'
+    }]
+})
+public async login(
+    @IpAddress() ipAddress: string,
+    @UserAgent() userAgent: string,
+    @Body() body: AuthLoginRequest
+): Promise<ResponseReturn<AuthLoginResponse>> { ... }
+```
+
+### Protected Endpoint with Params
+
+```typescript
+@Get(':provider')
+@UseGuards(JwtAuthGuard)
+@Api({
+    auth: 'bearer',
+    operation: {
+        operationId: 'getProvider',
+        description: 'Returns details about a payment provider.',
+        summary: 'Get provider'
+    },
+    params: [{
+        name: 'provider',
+        description: 'Provider identifier.',
+        required: true,
+        type: String
+    }],
+    responses: [{
+        status: HttpStatus.OK,
+        description: 'Provider details.',
+        type: ProviderResponse
+    }, {
+        status: HttpStatus.NOT_FOUND,
+        description: 'Provider not found.'
+    }]
+})
+```
+
+### Query Parameters
+
+```typescript
+@Get('availability')
+@Api({
+    operation: {
+        operationId: 'checkAvailability',
+        description: 'Checks if a username is available.',
+        summary: 'Check availability'
+    },
+    query: [{
+        name: 'username',
+        description: 'The username to check.',
+        required: true,
+        type: String
+    }],
+    responses: [{
+        status: HttpStatus.OK,
+        description: 'Availability status.',
+        type: AvailabilityResponse
+    }]
+})
+public async checkAvailability(
+    @Query('username') username: string
+): Promise<ResponseReturn<AvailabilityResponse>> { ... }
+```
+
+---
+
+## Method Naming Conventions
+
+Controller methods should clearly reflect the action and resource:
+
+| Pattern | HTTP Method | Example |
+|---------|-------------|---------|
+| `listX` | GET (collection) | `listOrders()` |
+| `getX` / `X` | GET (single) | `getOrder()`, `me()` |
+| `createX` / domain verb | POST | `createOrder()`, `login()`, `register()` |
+| `updateX` | PUT / PATCH | `updateProfile()` |
+| `deleteX` | DELETE | `deleteOrder()` |
+| `verbNoun` | POST (action) | `changePassword()`, `forgotPassword()`, `resendVerification()` |
+
+Methods are always `public async` and return `Promise<ResponseReturn<T>>`.
+
+---
+
+## Rate Limiting
+
+Use `@Throttle()` from `@nestjs/throttler` for endpoints that need rate limiting:
+
+```typescript
+import { Throttle } from '@nestjs/throttler';
+
+@Get('availability')
+@Public()
+@Throttle({ default: { limit: 10, ttl: 60000 } })
+public async checkAvailability(
+    @Query('username') username: string
+): Promise<ResponseReturn<AvailabilityResponse>> { ... }
+```
+
+Always document the rate limit in the `@Api` responses:
+
+```typescript
+responses: [{
+    status: HttpStatus.OK,
+    description: 'Availability result.'
+}, {
+    status: HttpStatus.TOO_MANY_REQUESTS,
+    description: 'Rate limit exceeded (max 10 requests per minute).'
+}]
+```
+
+---
+
+## Social Authentication Pattern
+
+Social login uses a guard factory and a two-endpoint flow: initiate → callback.
+
+```typescript
+@Public()
+@Get('social/:provider')
+@UseGuards(socialAuthGuardFactory(':provider'))
+@Api({
+    operation: {
+        operationId: 'socialAuthentication',
+        description: 'Redirects the user to the social provider.',
+        summary: 'Start social authentication'
+    },
+    params: [{
+        name: 'provider',
+        description: 'Authentication provider (github, google, microsoft, apple).',
+        required: true,
+        type: String
+    }],
+    responses: [{
+        status: HttpStatus.TEMPORARY_REDIRECT,
+        description: 'Redirects to the social provider.'
+    }]
+})
+public async socialAuthentication(): Promise<void> {
+    // Guard handles the redirect flow.
+}
+
+@Public()
+@Get('social/:provider/callback')
+@UseGuards(socialAuthGuardFactory(':provider'))
+@Api({
+    operation: {
+        operationId: 'socialAuthenticationCallback',
+        description: 'Handles the callback from the authentication provider.',
+        summary: 'Handle social callback'
+    },
+    params: [{
+        name: 'provider',
+        description: 'Authentication provider that initiated the callback.',
+        required: true,
+        type: String
+    }],
+    responses: [{
+        status: HttpStatus.TEMPORARY_REDIRECT,
+        description: 'Redirects to the application.'
+    }]
+})
+public async socialAuthenticationCallback(
+    @Req() req: Request,
+    @Res({ passthrough: true }) res: Response
+): Promise<void> {
+    const user = req.user as IAuthSubject;
+    await new Promise<void>((resolve, reject) => {
+        req.login(user, (err) => err ? reject(err) : resolve());
+    });
+
+    const redirectUri = (req.authInfo as { state: { redirectUri?: string } }).state?.redirectUri;
+    res.redirect(redirectUri ?? '/');
+}
+```
+
+> **Note:** Social callback endpoints are the only place where `@Req()` and `@Res()` are acceptable. In all other endpoints, use typed parameter decorators (`@Body()`, `@Query()`, `@User()`, etc.).
+
+---
+
+## Complete Controller Example
+
+Below is a full authentication controller demonstrating every pattern covered in this guide:
+
+```typescript
+// #region Imports
+
+import { Body, Controller, Get, HttpStatus, Post, Query, Req, Res, UseGuards } from '@nestjs/common';
+import { Request, Response } from 'express';
+import { Throttle } from '@nestjs/throttler';
+import { Api } from '@breadstone/archipel-platform-openapi';
+import { IpAddress, Public, ResponseReturn, UserAgent } from '@breadstone/archipel-platform-core';
+import {
+    type IAuthSubject,
+    JwtAuthGuard,
+    Token,
+    User,
+    socialAuthGuardFactory
+} from '@breadstone/archipel-platform-authentication';
+import {
+    AuthLoginRequest,
+    AuthLoginResponse,
+    AuthRefreshResponse,
+    AuthRegisterRequest,
+    AuthChangePasswordRequest,
+    AuthForgotPasswordRequest,
+    AuthVerifyPinRequest,
+    AuthVerifyResponse,
+    UserResponse
+} from '../models';
+
+// #endregion
+
+@Api({ tags: ['Auth'] })
+@Controller('api/auth')
+export class AuthController {
+
+    // #region Fields
+
+    private readonly _userService: UserService;
+    private readonly _verificationService: VerificationService;
+
+    // #endregion
+
+    // #region Ctor
+
+    /**
+     * Constructs a new instance of the `AuthController` class.
+     *
+     * @public
+     */
+    public constructor(
+        userService: UserService,
+        verificationService: VerificationService
+    ) {
+        this._userService = userService;
+        this._verificationService = verificationService;
+    }
+
+    // #endregion
+
+    // #region Methods
+
+    /**
+     * Logs the user in and returns an access token.
+     *
+     * @public
+     */
+    @Post('login')
+    @Api({
+        operation: {
+            operationId: 'login',
+            description: 'Logs the user in and returns an access token.',
+            summary: 'Authenticate user'
+        },
+        body: {
+            description: 'Credentials used for authentication.',
+            type: AuthLoginRequest
+        },
+        responses: [{
+            status: HttpStatus.OK,
+            description: 'Access token successfully generated.',
+            type: AuthLoginResponse
+        }, {
+            status: HttpStatus.UNAUTHORIZED,
+            description: 'Provided credentials are invalid.'
+        }]
+    })
+    public async login(
+        @IpAddress() ipAddress: string,
+        @UserAgent() userAgent: string,
+        @Body() body: AuthLoginRequest
+    ): Promise<ResponseReturn<AuthLoginResponse>> {
+        const result = await this._userService.signIn(
+            body.login, body.password, ipAddress, userAgent
+        );
+        return ResponseReturn.ok(AuthLoginResponse, {
+            accessToken: result.accessToken,
+            mfaRequired: result.mfaRequired
+        });
+    }
+
+    /**
+     * Logs the user out.
+     *
+     * @public
+     */
+    @Post('logout')
+    @UseGuards(JwtAuthGuard)
+    @Api({
+        auth: 'bearer',
+        operation: {
+            operationId: 'logout',
+            description: 'Logs the authenticated user out.',
+            summary: 'Log out user'
+        },
+        responses: [{
+            status: HttpStatus.NO_CONTENT,
+            description: 'User has been logged out.'
+        }, {
+            status: HttpStatus.UNAUTHORIZED,
+            description: 'Authentication is required.'
+        }]
+    })
+    public async logout(
+        @Token() token: string
+    ): Promise<ResponseReturn<void>> {
+        await this._userService.signOut(token);
+        return ResponseReturn.noContent();
+    }
+
+    /**
+     * Registers a new user.
+     *
+     * @public
+     */
+    @Post('register')
+    @Api({
+        operation: {
+            operationId: 'register',
+            description: 'Registers a new user.',
+            summary: 'Register user'
+        },
+        body: {
+            description: 'Registration payload.',
+            type: AuthRegisterRequest
+        },
+        responses: [{
+            status: HttpStatus.NO_CONTENT,
+            description: 'The user has been registered.'
+        }, {
+            status: HttpStatus.BAD_REQUEST,
+            description: 'Email or password are missing.'
+        }, {
+            status: HttpStatus.CONFLICT,
+            description: 'The email address is already registered.'
+        }]
+    })
+    public async register(
+        @Body() body: AuthRegisterRequest
+    ): Promise<ResponseReturn<void>> {
+        await this._userService.signUp(body.email, body.password, body.type, {
+            avatar: body.profile?.avatar,
+            firstName: body.profile?.firstName,
+            lastName: body.profile?.lastName,
+            userName: body.profile?.userName
+        });
+        return ResponseReturn.noContent();
+    }
+
+    /**
+     * Gets the current user.
+     *
+     * @public
+     */
+    @Get('me')
+    @UseGuards(JwtAuthGuard)
+    @Api({
+        auth: 'bearer',
+        operation: {
+            operationId: 'me',
+            description: 'Gets the current user.',
+            summary: 'Get current user'
+        },
+        responses: [{
+            status: HttpStatus.OK,
+            description: 'Authenticated user profile.',
+            type: UserResponse
+        }, {
+            status: HttpStatus.UNAUTHORIZED,
+            description: 'Authentication is required.'
+        }]
+    })
+    public async me(
+        @User() user: IAuthSubject
+    ): Promise<ResponseReturn<UserResponse>> {
+        const result = await this._userService.find({ id: user.id });
+        return ResponseReturn.ok(UserResponse, result);
+    }
+
+    /**
+     * Changes the password.
+     *
+     * @public
+     */
+    @Post('change-password')
+    @UseGuards(JwtAuthGuard)
+    @Api({
+        auth: 'bearer',
+        operation: {
+            operationId: 'changePassword',
+            description: 'Changes the authenticated user\'s password.',
+            summary: 'Change password'
+        },
+        body: {
+            description: 'Payload containing the new password.',
+            type: AuthChangePasswordRequest
+        },
+        responses: [{
+            status: HttpStatus.NO_CONTENT,
+            description: 'Password has been changed.'
+        }, {
+            status: HttpStatus.UNAUTHORIZED,
+            description: 'Authentication is required.'
+        }]
+    })
+    public async changePassword(
+        @Body() body: AuthChangePasswordRequest,
+        @User() user: IAuthSubject
+    ): Promise<ResponseReturn<void>> {
+        await this._userService.changePassword({ id: user.id }, body.password);
+        return ResponseReturn.noContent();
+    }
+
+    /**
+     * Sends a password reset email.
+     *
+     * @public
+     */
+    @Post('forgot-password')
+    @Api({
+        operation: {
+            operationId: 'forgotPassword',
+            description: 'Sends a password reset email.',
+            summary: 'Forgot password'
+        },
+        body: {
+            description: 'Payload identifying the account.',
+            type: AuthForgotPasswordRequest
+        },
+        responses: [{
+            status: HttpStatus.NO_CONTENT,
+            description: 'Password reset instructions sent.'
+        }, {
+            status: HttpStatus.BAD_REQUEST,
+            description: 'Login identifier is missing.'
+        }]
+    })
+    public async forgotPassword(
+        @Body() body: AuthForgotPasswordRequest
+    ): Promise<ResponseReturn<void>> {
+        await this._userService.forgotPassword(body.login);
+        return ResponseReturn.noContent();
+    }
+
+    // #endregion
+
+}
+```
+
+---
+
+## Checklist
+
+Before submitting a controller, verify:
+
+- [ ] Class has `@Api({ tags })` and `@Controller(path)` decorators
+- [ ] Every method has `@Api()` with `operation` and `responses`
+- [ ] Protected endpoints use `@UseGuards(JwtAuthGuard)` and `@Api({ auth: 'bearer' })`
+- [ ] Public endpoints have `@Public()` decorator
+- [ ] All methods return `Promise<ResponseReturn<T>>`
+- [ ] No business logic — only delegation to services
+- [ ] No direct repository or Prisma calls
+- [ ] Constructor injection with private `readonly` fields
+- [ ] Regions: Fields → Ctor → Methods (no other regions)
+- [ ] TSDoc on every public method
+- [ ] Rate-limited endpoints document `TOO_MANY_REQUESTS` response

package/data/guides/index.md

@@ -9,13 +9,17 @@ Practical guides for working with Archipel packages in your NestJS application.
 
 ## Foundations
 
-| Guide                                       | What you'll learn                                                                      |
-| ------------------------------------------- | -------------------------------------------------------------------------------------- |
-| [Getting Started](./getting-started)        | Install packages, register your first module, implement ports, and run the app.        |
-| [Configuration Management](./configuration) | Type-safe config keys, strategy-based resolution, central registry, and validation.    |
-| [Implementing Ports](./implementing-ports)  | How the port/adapter pattern works, how to write adapters, and how to test them.       |
-| [Testing](./testing)                        | Unit testing services, testing port adapters, integration testing with real databases. |
-| [TSDoc Guidelines](./tsdoc-guidelines)      | Documentation standards for public APIs and generated reference pages.                 |
+| Guide                                                     | What you'll learn                                                                                             |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [Getting Started](./getting-started)                      | Install packages, register your first module, implement ports, and run the app.                               |
+| [Configuration Management](./configuration)               | Type-safe config keys, strategy-based resolution, central registry, and validation.                           |
+| [Implementing Ports](./implementing-ports)                | How the port/adapter pattern works, how to write adapters, and how to test them.                              |
+| [Controller Best Practices](./controller-best-practices)  | Structure, annotate, and implement controllers — regions, DI, ResponseReturn, guards, and the @Api decorator. |
+| [Request & Response DTOs](./request-response-dtos)        | DTO naming conventions, validation decorators, cross-field validation, and class-transformer integration.     |
+| [Testing](./testing)                                      | Unit testing services, testing port adapters, integration testing with real databases.                        |
+| [TSDoc Guidelines](./tsdoc-guidelines)                    | Documentation standards for public APIs and generated reference pages.                       ld validation, and class-transformer integration.     |
+| [Testing](./testing)                                      | Unit testing services, testing port adapters, integration testing with real databases.                        |
+| [TSDoc Guidelines](./tsdoc-guidelines)                    | Documentation standards for public APIs and generated reference pages.                                        |
 
 ## Security & Identity
 

package/data/guides/request-response-dtos.md

@@ -0,0 +1,411 @@
+---
+title: Request & Response DTOs
+description: Naming conventions, validation decorators, and class-transformer integration for request and response data transfer objects in Archipel NestJS applications.
+order: 4
+---
+
+# Request & Response DTOs
+
+This guide covers how to define, validate, and transform request and response DTOs in an Archipel-powered NestJS application. DTOs are the contract between your API and its consumers — they define what goes in and what comes out.
+
+For how controllers use DTOs together with `ResponseReturn`, see the [Controller Best Practices](/guides/controller-best-practices) guide.
+
+---
+
+## Naming Conventions
+
+DTOs follow a strict naming pattern:
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Create request | `Create{Resource}Request` | `CreateOrderRequest` |
+| Update request | `Update{Resource}Request` | `UpdateProfileRequest` |
+| Action request | `{Action}{Resource}Request` | `AuthLoginRequest`, `AuthVerifyPinRequest` |
+| Single response | `{Resource}Response` | `UserResponse`, `OrderResponse` |
+| List response | `{Resource}ListResponse` | `OrderListResponse` |
+| Action response | `{Action}{Resource}Response` | `AuthLoginResponse`, `AuthRefreshResponse` |
+| Availability / status | `{Resource}{Status}Response` | `AuthUsernameAvailabilityResponse` |
+
+### Grouping by Feature
+
+When a controller has many DTOs, prefix them with the feature name to keep imports clean:
+
+```typescript
+// Auth feature DTOs
+AuthLoginRequest
+AuthLoginResponse
+AuthRegisterRequest
+AuthRefreshResponse
+AuthChangePasswordRequest
+AuthChangeEmailRequest
+AuthForgotPasswordRequest
+AuthVerifyPinRequest
+AuthVerifyResponse
+AuthResendVerificationRequest
+AuthUsernameSuggestionsResponse
+AuthUsernameAvailabilityResponse
+AuthAvatarSuggestionResponse
+```
+
+All DTOs for a feature are exported from a `models/` barrel file:
+
+```typescript
+// models/index.ts
+export { AuthLoginRequest } from './AuthLoginRequest';
+export { AuthLoginResponse } from './AuthLoginResponse';
+export { AuthRegisterRequest } from './AuthRegisterRequest';
+// ...
+```
+
+---
+
+## File Organization
+
+**One public export per file.** Each DTO class gets its own file, named after the class.
+
+```
+src/
+  auth/
+    models/
+      AuthLoginRequest.ts
+      AuthLoginResponse.ts
+      AuthRegisterRequest.ts
+      AuthRefreshResponse.ts
+      UserResponse.ts
+      index.ts
+    AuthController.ts
+    AuthModule.ts
+```
+
+---
+
+## Request DTOs (Validation)
+
+Request DTOs are classes decorated with `class-validator` and `@ApiProperty` from `@nestjs/swagger`.
+
+### Basic Request
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty, IsString, MinLength } from 'class-validator';
+
+export class AuthLoginRequest {
+
+    /**
+     * The user's email address or username.
+     *
+     * @public
+     */
+    @ApiProperty({ description: 'Email address or username.' })
+    @IsNotEmpty()
+    @IsString()
+    public login!: string;
+
+    /**
+     * The user's password.
+     *
+     * @public
+     */
+    @ApiProperty({ description: 'Account password.' })
+    @IsNotEmpty()
+    @IsString()
+    @MinLength(8)
+    public password!: string;
+
+}
+```
+
+### Request with Optional Fields
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class AuthRegisterRequest {
+
+    @ApiProperty({ description: 'Email address for the new account.' })
+    @IsNotEmpty()
+    @IsEmail()
+    public email!: string;
+
+    @ApiProperty({ description: 'Password for the new account.', minLength: 8 })
+    @IsNotEmpty()
+    @IsString()
+    @MinLength(8)
+    public password!: string;
+
+    @ApiProperty({ description: 'Account type.', example: 'personal' })
+    @IsNotEmpty()
+    @IsString()
+    public type!: string;
+
+    @ApiPropertyOptional({ description: 'Optional profile information.' })
+    @IsOptional()
+    @ValidateNested()
+    @Type(() => ProfilePayload)
+    public profile?: ProfilePayload;
+
+}
+```
+
+### Nested Payloads
+
+When a request contains nested objects, define them as separate classes with `@ValidateNested()` and `@Type()`:
+
+```typescript
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsOptional, IsString } from 'class-validator';
+
+export class ProfilePayload {
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public avatar?: string;
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public firstName?: string;
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public lastName?: string;
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public userName?: string;
+
+}
+```
+
+---
+
+## Response DTOs (Transformation)
+
+Response DTOs use `@ApiProperty` for documentation and `@Expose()` from `class-transformer` for serialization control.
+
+### Basic Response
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
+
+export class AuthLoginResponse {
+
+    @ApiProperty({ description: 'JWT access token.' })
+    @Expose()
+    public accessToken!: string;
+
+    @ApiProperty({ description: 'Whether multi-factor authentication is required.' })
+    @Expose()
+    public mfaRequired!: boolean;
+
+}
+```
+
+### Response with Optional Fields
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
+
+export class AuthLoginResponse {
+
+    @ApiProperty({ description: 'JWT access token.' })
+    @Expose()
+    public accessToken!: string;
+
+    @ApiProperty({ description: 'Whether MFA is required.' })
+    @Expose()
+    public mfaRequired!: boolean;
+
+    @ApiProperty({ description: 'Whether email verification is required.' })
+    @Expose()
+    public verificationRequired!: boolean;
+
+    @ApiPropertyOptional({ description: 'MFA challenge identifier.' })
+    @Expose()
+    public challengeId?: string;
+
+    @ApiPropertyOptional({ description: 'Available MFA methods.', type: [String] })
+    @Expose()
+    public methods?: Array<string>;
+
+    @ApiPropertyOptional({ description: 'Preferred MFA method.' })
+    @Expose()
+    public preferredMethod?: string;
+
+}
+```
+
+### User / Entity Response
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Expose } from 'class-transformer';
+
+export class UserResponse {
+
+    @ApiProperty({ description: 'Unique user identifier.' })
+    @Expose()
+    public id!: string;
+
+    @ApiProperty({ description: 'Email address.' })
+    @Expose()
+    public email!: string;
+
+    @ApiPropertyOptional({ description: 'Display username.' })
+    @Expose()
+    public userName?: string;
+
+    @ApiPropertyOptional({ description: 'First name.' })
+    @Expose()
+    public firstName?: string;
+
+    @ApiPropertyOptional({ description: 'Last name.' })
+    @Expose()
+    public lastName?: string;
+
+    @ApiPropertyOptional({ description: 'Avatar URL or base64 image.' })
+    @Expose()
+    public avatar?: string;
+
+    @ApiProperty({ description: 'Whether the email is verified.' })
+    @Expose()
+    public isVerified!: boolean;
+
+}
+```
+
+---
+
+## How ResponseReturn Uses DTOs
+
+When a controller calls `ResponseReturn.ok(AuthLoginResponse, data)`, the response pipeline:
+
+1. Instantiates `AuthLoginResponse` via `class-transformer`'s `plainToInstance()`
+2. Applies `@Expose()` / `@Exclude()` rules — only explicitly exposed fields appear in the output
+3. Wraps the result in the standard envelope: `{ success, status, data, timestamp }`
+
+This means the DTO class **controls what the client sees**. Even if the service returns extra fields, they won't leak unless the DTO exposes them.
+
+```typescript
+// Service returns: { id, email, password, internalFlag, ... }
+// DTO only exposes: { id, email, userName }
+// Client receives:  { success: true, status: 200, data: { id, email, userName }, timestamp: ... }
+```
+
+---
+
+## Validation Pipeline
+
+Archipel applications use a global `ValidationPipe` with strict settings:
+
+```typescript
+app.useGlobalPipes(new ValidationPipe({
+    whitelist: true,           // Strip properties not in the DTO
+    forbidNonWhitelisted: true, // Throw if unknown properties are sent
+    transform: true,            // Auto-transform payloads to DTO instances
+}));
+```
+
+This means:
+- Properties without decorators are **silently removed** (`whitelist`)
+- Unknown properties cause a **400 Bad Request** (`forbidNonWhitelisted`)
+- Request bodies are automatically transformed to class instances (`transform`)
+
+---
+
+## Cross-Field Validation
+
+When fields depend on each other (e.g., either `email` or `phone` is required, but not both), implement a custom class-level validator:
+
+```typescript
+import { ValidatorConstraint, ValidatorConstraintInterface, Validate, ValidationArguments } from 'class-validator';
+
+@ValidatorConstraint({ name: 'eitherEmailOrPhone', async: false })
+export class EitherEmailOrPhoneConstraint implements ValidatorConstraintInterface {
+
+    public validate(_: unknown, args: ValidationArguments): boolean {
+        const obj = args.object as { email?: string; phone?: string };
+        return Boolean(obj.email) !== Boolean(obj.phone);
+    }
+
+    public defaultMessage(): string {
+        return 'Exactly one of email or phone must be provided.';
+    }
+
+}
+
+@Validate(EitherEmailOrPhoneConstraint)
+export class ContactRequest {
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsEmail()
+    public email?: string;
+
+    @ApiPropertyOptional()
+    @IsOptional()
+    @IsString()
+    public phone?: string;
+
+}
+```
+
+**Never** do cross-field validation in controllers or services — always use class-level validators so it's reusable and testable.
+
+---
+
+## Constants for Limits
+
+Define and reuse constants for bounds that appear in validation and pagination:
+
+```typescript
+// constants.ts
+export const MAX_PAGE_SIZE = 100;
+export const MAX_SEARCH_LIMIT = 50;
+export const DEFAULT_PAGE_SIZE = 20;
+```
+
+```typescript
+import { Max, Min, IsOptional, IsInt } from 'class-validator';
+import { MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE } from '../constants';
+
+export class PaginationQuery {
+
+    @ApiPropertyOptional({ default: DEFAULT_PAGE_SIZE, maximum: MAX_PAGE_SIZE })
+    @IsOptional()
+    @IsInt()
+    @Min(1)
+    @Max(MAX_PAGE_SIZE)
+    public limit?: number = DEFAULT_PAGE_SIZE;
+
+    @ApiPropertyOptional({ default: 0 })
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    public offset?: number = 0;
+
+}
+```
+
+---
+
+## Checklist
+
+Before submitting DTOs, verify:
+
+- [ ] One DTO class per file, named after the class
+- [ ] Request DTOs have `class-validator` decorators on every property
+- [ ] Response DTOs have `@Expose()` on every public property
+- [ ] Nested objects use `@ValidateNested()` + `@Type()`
+- [ ] All properties have `@ApiProperty` or `@ApiPropertyOptional`
+- [ ] No `any` types — use `unknown` or specific types
+- [ ] Cross-field validation uses class-level validators, not imperative checks
+- [ ] Pagination limits use shared constants with `@Max()`
+- [ ] DTOs exported from a `models/index.ts` barrel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "MCP server providing Archipel platform knowledge — documentation, query patterns, and coding conventions — to AI development tools.",
   "type": "commonjs",
   "main": "./src/main.js",