Align Module — Isolate Guards, DTOs, and Error Handling

[SheyeJDev]

Refactor Portfolio Module for Domain Encapsulation, Validation, and Error Handling

Overview

This PR refactors the Portfolio module to improve domain ownership, reduce duplication, strengthen validation, and introduce portfolio-specific error handling.

The Portfolio module is one of the most complex domains in the application, containing multiple entities, services, DTOs, optimization algorithms, and ML-driven portfolio management logic. Prior to this change, portfolio concerns were partially scattered across the application, with entities registered globally, duplicate guard implementations, and generic exception handling for financial operations.

This refactor aligns the module with NestJS modular architecture principles by making Portfolio responsible for its own entities, validation, and domain-specific behaviors.

---

Changes Made

1. Portfolio Entity Encapsulation

Moved portfolio entity registration from the global application configuration into the Portfolio module.

Before

• Portfolio entities were registered globally in app.module.ts.
• Portfolio dependencies were not fully encapsulated within the module.

After

• Added TypeOrmModule.forFeature([...portfolioEntities]) to PortfolioModule.
• Removed portfolio entities from the global TypeORM entity registration.
• Portfolio repositories are now scoped to the module that owns them.

Benefits

• Better module isolation.
• Reduced coupling with the application root module.
• Improved maintainability and scalability.

---

2. Guard Consolidation

Reviewed all guards located in:

src/investment/portfolio/guards/

Actions Taken

• Audited existing portfolio-specific guards.
• Identified reusable authorization and access-control logic.
• Merged unique functionality into:

src/common/guard/

• Removed duplicate or redundant implementations.
• Deleted the local portfolio guards directory.

Benefits

• Eliminates duplicate authorization logic.
• Centralizes guard management.
• Ensures consistent behavior across modules.

---

3. Domain-Specific Exception Handling

Introduced portfolio-specific exception classes for financial and optimization workflows.

New Exceptions

src/investment/portfolio/exceptions/

Examples:

• InsufficientBalanceException
• OptimizationFailedException
• RebalancingFailedException

Usage

Portfolio services now throw explicit domain exceptions instead of generic NestJS or JavaScript errors when:

• Portfolio optimization fails
• Rebalancing operations cannot be completed
• Available balance is insufficient
• Allocation constraints cannot be satisfied

Benefits

• Clearer API error responses.
• Easier debugging and monitoring.
• Improved client-side error handling.
• Better alignment with business rules.

---

4. DTO Validation Improvements

Reviewed all Portfolio DTOs and ensured validation rules are explicitly defined using class-validator.

Validation Enhancements

Added appropriate decorators where applicable:

@IsUUID()
@IsNumber()
@IsString()
@IsEnum()
@IsOptional()
@Min()
@Max()
@IsArray()
@ValidateNested()

Validation Flow

• Portfolio DTOs now fully leverage the application's global ValidationPipe.
• Invalid requests are rejected before reaching service logic.

Benefits

• Stronger input validation.
• Reduced runtime failures.
• Improved API consistency.

---

Architectural Improvements

This PR moves the Portfolio domain closer to a true bounded-context architecture by ensuring it owns:

• Entities
• Repositories
• Exceptions
• Validation rules
• Authorization concerns

while relying only on shared infrastructure provided by the common module.

---

Files/Areas Updated

Portfolio Module

• src/investment/portfolio/portfolio.module.ts

App Module

• src/app.module.ts

Guards

• src/investment/portfolio/guards/* (removed)
• src/common/guard/* (updated)

Exceptions

• src/investment/portfolio/exceptions/*

DTOs

• src/investment/portfolio/dto/*

Services

• Portfolio services updated to use domain-specific exceptions.

---

Validation Performed

• Verified successful compilation with:

npm run build

• Confirmed Portfolio module dependency injection resolves correctly.
• Confirmed repositories are available through TypeOrmModule.forFeature().
• Verified DTO validation works through the global ValidationPipe.
• Verified portfolio services throw domain-specific exceptions.
• Executed portfolio test suite successfully.

---

Acceptance Criteria Checklist

• PortfolioModule uses TypeOrmModule.forFeature() for all portfolio entities
• Portfolio entities removed from global entity registration in app.module.ts
• Portfolio guards consolidated into common/guard/
• src/investment/portfolio/guards/ removed
• Domain-specific exceptions created and integrated into services
• Portfolio DTOs use class-validator decorators
• npm run build succeeds
• Portfolio tests pass
• Portfolio module is self-contained and follows NestJS modular architecture principles

Closes #10

[memplethee-lab]

@SheyeJDev Please check and fix