@sundaysf/cli-v2 1.0.1 → 1.0.5

package/dist/templates/backend-db-sql/CLAUDE.md

@@ -1,374 +1,374 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Commands
-
-### Development
-
-- `npm run start:dev` - Start development server with auto-reload (uses nodemon)
-- `npm run build` - Compile TypeScript to JavaScript (output to dist/)
-- `npm start` - Run production server from compiled dist/
-
-### Code Quality
-
-- `npm run format` - Format code with Prettier
-- No linting command configured - consider using ESLint with the installed configuration
-
-### Testing
-
-- `npm test` - Run tests with Jest (no test files found yet)
-
-### Utilities
-
-- `npm run create:controller` - Generate new controller using Sundays Framework CLI
-
-### Database
-
-- `npm run migrate:create` - Create a new migration file in TypeScript
-- `npm run migrate:deploy` - Apply pending migrations
-- `npm run seed:create` - Create a new seed file in TypeScript
-- `npm run seed:run` - Execute seed files
-- `npm run db:build` - Compile the db module TypeScript to JavaScript
-- `npm run db:publish` - Publish the db module as an independent npm package
-
-## Architecture
-
-This is a Sundays Framework backend built with Express.js and TypeScript following a modular MVC pattern, with an embedded Knex.js database module in `db/`.
-
-### Core Structure
-
-- **Entry Points**: `src/server.ts` initializes the server and connects to the database, `src/app.ts` configures Express middleware
-- **Routing**: Dynamic route loading system in `src/routes/index.ts` that automatically discovers and mounts routers from subdirectories
-- **Controllers**: Business logic separated into controller classes (e.g., `HealthController`)
-- **Middleware**: Error handling middleware in `src/middlewares/error/`
-- **Configuration**: CORS origins managed in `src/common/config/origins/`
-- **Database**: `db/` contains the Knex.js module with DAOs, migrations, seeds, and interfaces
-
-### Key Patterns
-
-1. **Router Auto-Discovery**: The `IndexRouter` class scans the routes directory and automatically mounts any `*.router.ts` files found in subdirectories. Routes are mounted at `/{folder-name}`.
-
-2. **Controller Pattern**: Each router has a corresponding controller class that handles the business logic. Controllers are bound to router methods using `.bind()` to maintain proper context.
-
-3. **Environment Configuration**: Uses dotenv for environment variables. Server port defaults to 3005 if not specified in .env.
-
-4. **CORS Configuration**: Dynamic CORS origin configuration via `getAllowedOrigins()` function.
-
-5. **Database Connection**: `src/server.ts` calls `KnexManager.connect()` before starting the Express server. The KnexManager singleton manages connection pooling.
-
-6. **Dependencies**:
-   - Sundays Framework utilities (`@sundaysf/utils`) for pagination and validation
-   - Standard Express middleware (cors, morgan, etc.)
-   - Knex.js + PostgreSQL for database access
-
-### Database Module (`db/`)
-
-The `db/` directory is an independently publishable Knex.js module:
-
-- **KnexManager** (`db/src/KnexConnection.ts`): Singleton for managing database connections with pooling and SSL support
-- **DAO Pattern**: Data Access Objects implement `IBaseDAO<T>` with CRUD + pagination
-- **Migrations**: `db/migrations/` - Knex migration files in TypeScript
-- **Seeds**: `db/seeds/` - Seed data files
-- **Interfaces**: `db/src/interfaces/` - Entity type definitions
-- **Configuration**: `db/knexfile.ts` - Knex configuration for all environments
-
-#### File Structure Conventions
-
-**Interfaces**: `db/src/interfaces/{entity}/{entity}.interfaces.ts`
-**DAOs**: `db/src/dao/{entity}/{entity}.dao.ts`
-
-#### Environment Variables (Database)
-
-- `SQL_HOST` - PostgreSQL host
-- `SQL_PORT` - Database port (defaults to 5432)
-- `SQL_USER` - Database user
-- `SQL_PASSWORD` - Database password
-- `SQL_DB_NAME` - Database name
-- `SQL_REJECT_UNAUTHORIZED` - Set to 'false' to disable SSL certificate verification
-
-### TypeScript Configuration
-
-- **Backend** (`tsconfig.json`): Strict mode, ES2022, CommonJS. Source in `./src`, output to `./dist`. Excludes `db/`.
-- **Database** (`db/tsconfig.json`): Strict mode, ES2022, CommonJS with declarations. Source in `db/src`, output to `db/dist`.
-
-## Controller Implementation Guide
-
-When creating new controllers, follow the established pattern demonstrated in the CompanyController:
-
-### 1. Controller Structure
-```typescript
-import { Request, Response, NextFunction } from "express";
-import { IBaseController } from "../../types";
-import { inputValidator, IInputValidator, paginationHelper } from "@sundaysf/utils";
-import { [Entity]DAO, I[Entity], IDataPaginator } from "../../db/src";
-import { [Entity]CreateInputDTO } from "../../dto/input/[entity]/[entity].create.dto";
-import { [Entity]UpdateInputDTO } from "../../dto/input/[entity]/[entity].update.dto";
-import { v4 as uuidv4 } from 'uuid';
-
-export class [Entity]Controller implements IBaseController {
-  private _[entity]DAO: [Entity]DAO = new [Entity]DAO();
-
-  // Implement CRUD methods
-}
-```
-
-### 2. API Response Format
-
-All API responses must follow a consistent format:
-
-**Success Response**:
-```json
-{
-  "success": true,
-  "data": {...} // or "message": "Action completed successfully" for operations without data
-}
-```
-
-**Error Response**:
-```json
-{
-  "success": false,
-  "message": "Error description"
-}
-```
-
-**Paginated Response** (from IDataPaginator):
-```json
-{
-  "success": true,
-  "data": [...],
-  "page": 1,
-  "limit": 10,
-  "count": 10,
-  "totalCount": 100,
-  "totalPages": 10
-}
-```
-
-Note: The `IDataPaginator` interface already includes the standard response format with `success` and `data` fields, so responses from paginated endpoints should be returned directly without additional wrapping.
-
-### 3. Standard CRUD Methods
-
-**getAll** - List with pagination:
-```typescript
-public async getAll(req: Request, res: Response, next: NextFunction): Promise<void> {
-  try {
-    const {page, limit} = paginationHelper(req);
-    const result: IDataPaginator<I[Entity]> = await this._[entity]DAO.getAll(page, limit);
-    res.status(200).json(result); // IDataPaginator already includes success and data fields
-  } catch (err: any) {
-    next(err);
-  }
-}
-```
-
-**getByUuid** - Get single resource:
-```typescript
-public async getByUuid(req: Request, res: Response, next: NextFunction): Promise<void> {
-  try {
-    const { uuid } = req.params;
-    const result = await this._[entity]DAO.getByUuid(uuid);
-    if (!result) {
-      res.status(404).json({ success: false, message: "[Entity] not found" });
-      return;
-    }
-    res.status(200).json({
-      success: true,
-      data: result
-    });
-  } catch (err: any) {
-    next(err);
-  }
-}
-```
-
-**create** - Create new resource with DTO validation:
-```typescript
-public async create(req: Request, res: Response, next: NextFunction): Promise<void> {
-  try {
-    const data = req.body;
-    const inputDTO = new [Entity]CreateInputDTO(data).build();
-    const validation: IInputValidator = await inputValidator(inputDTO);
-    if (!validation.success) {
-      req.statusCode = 400;
-      return next(new Error(validation.message));
-    }
-    const dataToCreate = {...inputDTO, uuid: uuidv4()};
-    const result = await this._[entity]DAO.create(dataToCreate);
-    res.status(201).json({
-      success: true,
-      data: result
-    });
-  } catch (err: any) {
-    next(err);
-  }
-}
-```
-
-**update** - Update existing resource with DTO validation:
-```typescript
-public async update(req: Request, res: Response, next: NextFunction): Promise<void> {
-  try {
-    const { uuid } = req.params;
-    const data = req.body;
-
-    // First get the entity by UUID to find its ID
-    const existing = await this._[entity]DAO.getByUuid(uuid);
-    if (!existing || !existing.id) {
-      res.status(404).json({ success: false, message: "[Entity] not found" });
-      return;
-    }
-
-    const inputDTO = new [Entity]UpdateInputDTO(data).build();
-    const validation: IInputValidator = await inputValidator(inputDTO);
-    if (!validation.success) {
-      req.statusCode = 400;
-      return next(new Error(validation.message));
-    }
-
-    const result = await this._[entity]DAO.update(existing.id, inputDTO);
-    res.status(200).json({
-      success: true,
-      data: result
-    });
-  } catch (err: any) {
-    next(err);
-  }
-}
-```
-
-**delete** - Delete resource:
-```typescript
-public async delete(req: Request, res: Response, next: NextFunction): Promise<void> {
-  try {
-    const { uuid } = req.params;
-
-    // First get the entity by UUID to find its ID
-    const existing = await this._[entity]DAO.getByUuid(uuid);
-    if (!existing || !existing.id) {
-      res.status(404).json({ success: false, message: "[Entity] not found" });
-      return;
-    }
-
-    const result = await this._[entity]DAO.delete(existing.id);
-    if (result) {
-      res.status(200).json({ success: true, message: "[Entity] deleted successfully" });
-    } else {
-      res.status(404).json({ success: false, message: "Failed to delete [entity]" });
-    }
-  } catch (err: any) {
-    next(err);
-  }
-}
-```
-
-### 4. Router Implementation
-Create a corresponding router in `src/routes/[entity]/[entity].router.ts`:
-
-```typescript
-import { Router } from "express";
-import { [Entity]Controller } from "../../controllers/[entity]/[entity].controller";
-
-export class [Entity]Router {
-  private _router: Router;
-  private _[entity]Controller = new [Entity]Controller();
-
-  constructor() {
-    this._router = Router();
-    this.initRoutes();
-  }
-
-  private initRoutes(): void {
-    this._router.get("/", this._[entity]Controller.getAll.bind(this._[entity]Controller));
-    this._router.get("/:uuid", this._[entity]Controller.getByUuid.bind(this._[entity]Controller));
-    this._router.post("/", this._[entity]Controller.create.bind(this._[entity]Controller));
-    this._router.put("/:uuid", this._[entity]Controller.update.bind(this._[entity]Controller));
-    this._router.delete("/:uuid", this._[entity]Controller.delete.bind(this._[entity]Controller));
-  }
-
-  public get router(): Router {
-    return this._router;
-  }
-}
-```
-
-### 5. DTO Implementation
-
-Create DTOs to validate and sanitize input data:
-
-**Create DTO** (`src/dto/input/[entity]/[entity].create.dto.ts`):
-```typescript
-export class [Entity]CreateInputDTO {
-    // Define only allowed properties
-    property1: type;
-    property2: type;
-
-    constructor(data: any){
-        this.property1 = data.property1;
-        this.property2 = data.property2;
-        // Set defaults for optional properties
-    }
-
-    public build(): this {
-        return this;
-    }
-}
-```
-
-**Update DTO** (`src/dto/input/[entity]/[entity].update.dto.ts`):
-```typescript
-export class [Entity]UpdateInputDTO {
-    // Define optional properties
-    property1?: type;
-    property2?: type;
-
-    constructor(data: any){
-        // Only set properties that are present in the input
-        if (data.property1 !== undefined) this.property1 = data.property1;
-        if (data.property2 !== undefined) this.property2 = data.property2;
-    }
-
-    public build(): this {
-        // Remove any properties that weren't set
-        const cleanData: any = {};
-        if (this.property1 !== undefined) cleanData.property1 = this.property1;
-        if (this.property2 !== undefined) cleanData.property2 = this.property2;
-
-        // Clear all properties and reassign only the allowed ones
-        Object.keys(this).forEach(key => delete (this as any)[key]);
-        Object.assign(this, cleanData);
-
-        return this;
-    }
-}
-```
-
-### 6. Working with Related Entities
-
-When your entity has foreign key relationships, DAOs can include related entities using PostgreSQL's `to_jsonb()` function:
-
-```typescript
-async getById(id: number): Promise<IEntity | null> {
-  const result = await this._knex("entity as e")
-    .leftJoin("related as r", "e.relatedId", "r.id")
-    .select("e.*", this._knex.raw("to_jsonb(r.*) as related"))
-    .where("e.id", id)
-    .first();
-  return result || null;
-}
-```
-
-### 7. Important Notes
-- Always use `.bind()` when assigning controller methods to router to maintain proper context
-- Use UUID for public-facing endpoints (params) but convert to ID for internal DAO operations
-- Return appropriate HTTP status codes (200, 201, 404, etc.)
-- Pass errors to the next() function for centralized error handling
-- Use paginationHelper from @sundaysf/utils for consistent pagination
-- Use DTOs to validate and sanitize input data, preventing unwanted fields from being processed
-- DTOs ensure only allowed fields are passed to the DAO layer
-- Update DTOs should handle partial updates properly
-- Always generate UUID in the controller for new resources (not in DTO or client-side)
-- All API responses must follow the standard format: `{success: boolean, data?: any, message?: string}`
-- Use status 200 for successful DELETE operations (not 204) to include success message
-- Import DAOs and interfaces from `../db/src` (relative path from controllers)
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development
+
+- `npm run start:dev` - Start development server with auto-reload (uses nodemon)
+- `npm run build` - Compile TypeScript to JavaScript (output to dist/)
+- `npm start` - Run production server from compiled dist/
+
+### Code Quality
+
+- `npm run format` - Format code with Prettier
+- No linting command configured - consider using ESLint with the installed configuration
+
+### Testing
+
+- `npm test` - Run tests with Jest (no test files found yet)
+
+### Utilities
+
+- `npm run create:controller` - Generate new controller using Sundays Framework CLI
+
+### Database
+
+- `npm run migrate:create` - Create a new migration file in TypeScript
+- `npm run migrate:deploy` - Apply pending migrations
+- `npm run seed:create` - Create a new seed file in TypeScript
+- `npm run seed:run` - Execute seed files
+- `npm run db:build` - Compile the db module TypeScript to JavaScript
+- `npm run db:publish` - Publish the db module as an independent npm package
+
+## Architecture
+
+This is a Sundays Framework backend built with Express.js and TypeScript following a modular MVC pattern, with an embedded Knex.js database module in `db/`.
+
+### Core Structure
+
+- **Entry Points**: `src/server.ts` initializes the server and connects to the database, `src/app.ts` configures Express middleware
+- **Routing**: Dynamic route loading system in `src/routes/index.ts` that automatically discovers and mounts routers from subdirectories
+- **Controllers**: Business logic separated into controller classes (e.g., `HealthController`)
+- **Middleware**: Error handling middleware in `src/middlewares/error/`
+- **Configuration**: CORS origins managed in `src/common/config/origins/`
+- **Database**: `db/` contains the Knex.js module with DAOs, migrations, seeds, and interfaces
+
+### Key Patterns
+
+1. **Router Auto-Discovery**: The `IndexRouter` class scans the routes directory and automatically mounts any `*.router.ts` files found in subdirectories. Routes are mounted at `/{folder-name}`.
+
+2. **Controller Pattern**: Each router has a corresponding controller class that handles the business logic. Controllers are bound to router methods using `.bind()` to maintain proper context.
+
+3. **Environment Configuration**: Uses dotenv for environment variables. Server port defaults to 3005 if not specified in .env.
+
+4. **CORS Configuration**: Dynamic CORS origin configuration via `getAllowedOrigins()` function.
+
+5. **Database Connection**: `src/server.ts` calls `KnexManager.connect()` before starting the Express server. The KnexManager singleton manages connection pooling.
+
+6. **Dependencies**:
+   - Sundays Framework utilities (`@sundaysf/utils`) for pagination and validation
+   - Standard Express middleware (cors, morgan, etc.)
+   - Knex.js + PostgreSQL for database access
+
+### Database Module (`db/`)
+
+The `db/` directory is an independently publishable Knex.js module:
+
+- **KnexManager** (`db/src/KnexConnection.ts`): Singleton for managing database connections with pooling and SSL support
+- **DAO Pattern**: Data Access Objects implement `IBaseDAO<T>` with CRUD + pagination
+- **Migrations**: `db/migrations/` - Knex migration files in TypeScript
+- **Seeds**: `db/seeds/` - Seed data files
+- **Interfaces**: `db/src/interfaces/` - Entity type definitions
+- **Configuration**: `db/knexfile.ts` - Knex configuration for all environments
+
+#### File Structure Conventions
+
+**Interfaces**: `db/src/interfaces/{entity}/{entity}.interfaces.ts`
+**DAOs**: `db/src/dao/{entity}/{entity}.dao.ts`
+
+#### Environment Variables (Database)
+
+- `SQL_HOST` - PostgreSQL host
+- `SQL_PORT` - Database port (defaults to 5432)
+- `SQL_USER` - Database user
+- `SQL_PASSWORD` - Database password
+- `SQL_DB_NAME` - Database name
+- `SQL_REJECT_UNAUTHORIZED` - Set to 'false' to disable SSL certificate verification
+
+### TypeScript Configuration
+
+- **Backend** (`tsconfig.json`): Strict mode, ES2022, CommonJS. Source in `./src`, output to `./dist`. Excludes `db/`.
+- **Database** (`db/tsconfig.json`): Strict mode, ES2022, CommonJS with declarations. Source in `db/src`, output to `db/dist`.
+
+## Controller Implementation Guide
+
+When creating new controllers, follow the established pattern demonstrated in the CompanyController:
+
+### 1. Controller Structure
+```typescript
+import { Request, Response, NextFunction } from "express";
+import { IBaseController } from "../../types";
+import { inputValidator, IInputValidator, paginationHelper } from "@sundaysf/utils";
+import { [Entity]DAO, I[Entity], IDataPaginator } from "../../db/src";
+import { [Entity]CreateInputDTO } from "../../dto/input/[entity]/[entity].create.dto";
+import { [Entity]UpdateInputDTO } from "../../dto/input/[entity]/[entity].update.dto";
+import { v4 as uuidv4 } from 'uuid';
+
+export class [Entity]Controller implements IBaseController {
+  private _[entity]DAO: [Entity]DAO = new [Entity]DAO();
+
+  // Implement CRUD methods
+}
+```
+
+### 2. API Response Format
+
+All API responses must follow a consistent format:
+
+**Success Response**:
+```json
+{
+  "success": true,
+  "data": {...} // or "message": "Action completed successfully" for operations without data
+}
+```
+
+**Error Response**:
+```json
+{
+  "success": false,
+  "message": "Error description"
+}
+```
+
+**Paginated Response** (from IDataPaginator):
+```json
+{
+  "success": true,
+  "data": [...],
+  "page": 1,
+  "limit": 10,
+  "count": 10,
+  "totalCount": 100,
+  "totalPages": 10
+}
+```
+
+Note: The `IDataPaginator` interface already includes the standard response format with `success` and `data` fields, so responses from paginated endpoints should be returned directly without additional wrapping.
+
+### 3. Standard CRUD Methods
+
+**getAll** - List with pagination:
+```typescript
+public async getAll(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const {page, limit} = paginationHelper(req);
+    const result: IDataPaginator<I[Entity]> = await this._[entity]DAO.getAll(page, limit);
+    res.status(200).json(result); // IDataPaginator already includes success and data fields
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+**getByUuid** - Get single resource:
+```typescript
+public async getByUuid(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const { uuid } = req.params;
+    const result = await this._[entity]DAO.getByUuid(uuid);
+    if (!result) {
+      res.status(404).json({ success: false, message: "[Entity] not found" });
+      return;
+    }
+    res.status(200).json({
+      success: true,
+      data: result
+    });
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+**create** - Create new resource with DTO validation:
+```typescript
+public async create(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const data = req.body;
+    const inputDTO = new [Entity]CreateInputDTO(data).build();
+    const validation: IInputValidator = await inputValidator(inputDTO);
+    if (!validation.success) {
+      req.statusCode = 400;
+      return next(new Error(validation.message));
+    }
+    const dataToCreate = {...inputDTO, uuid: uuidv4()};
+    const result = await this._[entity]DAO.create(dataToCreate);
+    res.status(201).json({
+      success: true,
+      data: result
+    });
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+**update** - Update existing resource with DTO validation:
+```typescript
+public async update(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const { uuid } = req.params;
+    const data = req.body;
+
+    // First get the entity by UUID to find its ID
+    const existing = await this._[entity]DAO.getByUuid(uuid);
+    if (!existing || !existing.id) {
+      res.status(404).json({ success: false, message: "[Entity] not found" });
+      return;
+    }
+
+    const inputDTO = new [Entity]UpdateInputDTO(data).build();
+    const validation: IInputValidator = await inputValidator(inputDTO);
+    if (!validation.success) {
+      req.statusCode = 400;
+      return next(new Error(validation.message));
+    }
+
+    const result = await this._[entity]DAO.update(existing.id, inputDTO);
+    res.status(200).json({
+      success: true,
+      data: result
+    });
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+**delete** - Delete resource:
+```typescript
+public async delete(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const { uuid } = req.params;
+
+    // First get the entity by UUID to find its ID
+    const existing = await this._[entity]DAO.getByUuid(uuid);
+    if (!existing || !existing.id) {
+      res.status(404).json({ success: false, message: "[Entity] not found" });
+      return;
+    }
+
+    const result = await this._[entity]DAO.delete(existing.id);
+    if (result) {
+      res.status(200).json({ success: true, message: "[Entity] deleted successfully" });
+    } else {
+      res.status(404).json({ success: false, message: "Failed to delete [entity]" });
+    }
+  } catch (err: any) {
+    next(err);
+  }
+}
+```
+
+### 4. Router Implementation
+Create a corresponding router in `src/routes/[entity]/[entity].router.ts`:
+
+```typescript
+import { Router } from "express";
+import { [Entity]Controller } from "../../controllers/[entity]/[entity].controller";
+
+export class [Entity]Router {
+  private _router: Router;
+  private _[entity]Controller = new [Entity]Controller();
+
+  constructor() {
+    this._router = Router();
+    this.initRoutes();
+  }
+
+  private initRoutes(): void {
+    this._router.get("/", this._[entity]Controller.getAll.bind(this._[entity]Controller));
+    this._router.get("/:uuid", this._[entity]Controller.getByUuid.bind(this._[entity]Controller));
+    this._router.post("/", this._[entity]Controller.create.bind(this._[entity]Controller));
+    this._router.put("/:uuid", this._[entity]Controller.update.bind(this._[entity]Controller));
+    this._router.delete("/:uuid", this._[entity]Controller.delete.bind(this._[entity]Controller));
+  }
+
+  public get router(): Router {
+    return this._router;
+  }
+}
+```
+
+### 5. DTO Implementation
+
+Create DTOs to validate and sanitize input data:
+
+**Create DTO** (`src/dto/input/[entity]/[entity].create.dto.ts`):
+```typescript
+export class [Entity]CreateInputDTO {
+    // Define only allowed properties
+    property1: type;
+    property2: type;
+
+    constructor(data: any){
+        this.property1 = data.property1;
+        this.property2 = data.property2;
+        // Set defaults for optional properties
+    }
+
+    public build(): this {
+        return this;
+    }
+}
+```
+
+**Update DTO** (`src/dto/input/[entity]/[entity].update.dto.ts`):
+```typescript
+export class [Entity]UpdateInputDTO {
+    // Define optional properties
+    property1?: type;
+    property2?: type;
+
+    constructor(data: any){
+        // Only set properties that are present in the input
+        if (data.property1 !== undefined) this.property1 = data.property1;
+        if (data.property2 !== undefined) this.property2 = data.property2;
+    }
+
+    public build(): this {
+        // Remove any properties that weren't set
+        const cleanData: any = {};
+        if (this.property1 !== undefined) cleanData.property1 = this.property1;
+        if (this.property2 !== undefined) cleanData.property2 = this.property2;
+
+        // Clear all properties and reassign only the allowed ones
+        Object.keys(this).forEach(key => delete (this as any)[key]);
+        Object.assign(this, cleanData);
+
+        return this;
+    }
+}
+```
+
+### 6. Working with Related Entities
+
+When your entity has foreign key relationships, DAOs can include related entities using PostgreSQL's `to_jsonb()` function:
+
+```typescript
+async getById(id: number): Promise<IEntity | null> {
+  const result = await this._knex("entity as e")
+    .leftJoin("related as r", "e.relatedId", "r.id")
+    .select("e.*", this._knex.raw("to_jsonb(r.*) as related"))
+    .where("e.id", id)
+    .first();
+  return result || null;
+}
+```
+
+### 7. Important Notes
+- Always use `.bind()` when assigning controller methods to router to maintain proper context
+- Use UUID for public-facing endpoints (params) but convert to ID for internal DAO operations
+- Return appropriate HTTP status codes (200, 201, 404, etc.)
+- Pass errors to the next() function for centralized error handling
+- Use paginationHelper from @sundaysf/utils for consistent pagination
+- Use DTOs to validate and sanitize input data, preventing unwanted fields from being processed
+- DTOs ensure only allowed fields are passed to the DAO layer
+- Update DTOs should handle partial updates properly
+- Always generate UUID in the controller for new resources (not in DTO or client-side)
+- All API responses must follow the standard format: `{success: boolean, data?: any, message?: string}`
+- Use status 200 for successful DELETE operations (not 204) to include success message
+- Import DAOs and interfaces from `../db/src` (relative path from controllers)