TODO: Clean Architecture Best Practices Implementation

This file tracks the implementation of the three critical approaches for maximizing the effectiveness of this Clean Architecture template.

Overview

Status Legend: ❌ Not Started | 🟡 In Progress | ✅ Completed
Priority: 🔴 High | 🟠 Medium | 🟢 Low

1. Strict Layer Separation with Port-Adapter Pattern

Goal: Ensure domain and application layers only depend on interfaces (ports), never concrete implementations.

1.1 Audit Current Architecture

1.2 Define Missing Ports (Interfaces)

❌ 🔴 Create port interfaces for repositories

Location: src/modules/order/application/ports/IOrderRepository.ts
Location: src/modules/products/application/ports/IProductRepository.ts

Template:

export interface IOrderRepository {
  save: (order: Order) => Promise<Order>;
  findById: (id: string) => Promise<Order | null>;
  delete: (id: string) => Promise<void>;
  findByCustomerId: (customerId: string) => Promise<Order[]>;
}

❌ 🟠 Create port interfaces for external services
- Location: src/modules/order/application/ports/IPaymentService.ts
- Location: src/modules/order/application/ports/INotificationService.ts
❌ 🟠 Create port interfaces for cache service
- Location: src/shared/application/ports/ICacheService.ts
❌ 🟠 Create port interfaces for HTTP client
- Location: src/shared/application/ports/IHttpClient.ts

1.3 Refactor Use Cases to Depend on Ports

❌ 🔴 Update all use cases in src/modules/order/application/useCases/
- Replace concrete repository dependencies with port interfaces
- Ensure constructor injection uses interfaces only
- Example files to update:
  - src/modules/order/application/useCases/*/[UseCase].usecase.ts
❌ 🔴 Update all use cases in src/modules/products/application/useCases/
- Replace concrete dependencies with port interfaces

1.4 Update Module Providers

❌ 🔴 Update NestJS module providers to inject implementations via DI
- Location: src/modules/order/application/useCases/*/[UseCase].module.ts
- Pattern:
```
providers: [
  {
    provide: 'IOrderRepository',
    useClass: MongoOrderRepository,
  },
  CreateOrderUseCase,
];
```
❌ 🟠 Create shared provider configurations
- Location: src/shared/adapters/providers.config.ts

1.5 Validate Domain Layer Purity

❌ 🔴 Ensure domain entities have NO framework dependencies
- Check: src/modules/order/domain/*.ts - No NestJS decorators
- Check: src/modules/products/domain/*.ts - No Mongoose decorators
- Domain should only extend base classes from src/shared/ddd/

2. Event-Driven Domain Design with Choreography

Goal: Implement robust domain events and choreography-based sagas for loose coupling.

2.1 Audit Current Event Implementation

❌ 🔴 Review existing domain events
- Location: src/modules/order/domain/events/emitters/
- Verify: Events extend DomainEvent base class
- Verify: Events are past tense (OrderCreated, not CreateOrder)
❌ 🟠 Review existing event handlers
- Location: src/modules/order/domain/events/handlers/
- Verify: Handlers use @EventsHandler() decorator
- Verify: Handlers implement IEventHandler<T>

2.2 Identify Missing Domain Events

2.3 Implement Missing Domain Events

❌ 🔴 Create event emitters

Template location: src/modules/order/domain/events/emitters/OrderCreated.event.ts

Template:

import { DomainEvent } from '@shared/ddd/DomainEvent.base';

export class OrderCreatedEvent extends DomainEvent {
  constructor(
    public readonly orderId: string,
    public readonly customerId: string,
    public readonly totalAmount: number,
  ) {
    super({ aggregateId: orderId });
  }
}

❌ 🔴 Add events to aggregates

Update: src/modules/order/domain/Order.ts

Pattern:

public static create(props: OrderProps): Result<Order> {
  const order = new Order(props);
  order.addDomainEvent(new OrderCreatedEvent(order.id, order.customerId));
  return Result.ok(order);
}

2.4 Implement Event Handlers

❌ 🔴 Create cross-module event handlers for choreography
- Location: src/modules/[module]/domain/events/handlers/
- Examples:
  - OrderCreatedHandler.ts → Update inventory
  - OrderCreatedHandler.ts → Send notification
  - PaymentProcessedHandler.ts → Confirm order
❌ 🟠 Ensure handlers are idempotent
- Add event ID tracking to prevent duplicate processing
- Location: Consider adding src/shared/adapters/eventstore/

2.5 Update Use Cases to Publish Events

❌ 🔴 Ensure all use cases publish aggregate events after persistence

Pattern:

// After successful save
const savedOrder = await this.orderRepository.save(order);

// Publish domain events
savedOrder.domainEvents.forEach((event) => {
  this.eventEmitter.emit(event.constructor.name, event);
});
savedOrder.clearEvents();

❌ 🟠 Add error handling for event publishing failures
- Consider implementing outbox pattern
- Location: src/shared/adapters/eventstore/outbox/

2.6 Implement Choreography Sagas

❌ 🟠 Review saga documentation
- Read: _docs/microservice_labs/
❌ 🟠 Implement example saga: Order Processing Flow
- Flow: OrderCreated → ValidateInventory → ProcessPayment → ConfirmOrder
- Create handlers for each step in respective modules
❌ 🟢 Document saga patterns
- Location: _docs/sagas/order-processing-saga.md

3. Result/Either Pattern for Explicit Error Handling

Goal: Eliminate throw exceptions in domain/application layers; use Result pattern for all operations.

3.1 Audit Current Error Handling

❌ 🔴 Search for throw statements in domain layer
- Search: src/modules/*/domain/ for throw new Error
- Should be: Return Result.fail() instead
❌ 🔴 Search for throw statements in application layer
- Search: src/modules/*/application/useCases/ for throw
- Should be: Return Result.fail() instead
❌ 🟠 Review use cases return types
- All should return: Promise<Result<T>> or Result<T>

3.2 Implement Guard Validations

❌ 🔴 Add Guards to all entity factory methods

Location: src/modules/order/domain/Order.ts → Order.create()

Pattern:

public static create(props: OrderProps): Result<Order> {
  const guardResult = Guard.againstNullOrUndefinedBulk([
    { argument: props.customerId, argumentName: 'customerId' },
    { argument: props.items, argumentName: 'items' },
  ]);

  if (!guardResult.succeeded) {
    return Result.fail<Order>(guardResult.message);
  }

  // Additional business validation
  if (props.items.length === 0) {
    return Result.fail<Order>('Order must have at least one item');
  }

  const order = new Order(props);
  return Result.ok<Order>(order);
}

❌ 🔴 Add Guards to all value object factory methods
- Review all files in: src/modules/*/domain/*ValueObject.ts

3.3 Refactor Use Cases to Return Results

❌ 🔴 Update all use cases in Order module
- Files: src/modules/order/application/useCases/*/[UseCase].usecase.ts
- Return type: Promise<Result<ResponseDTO>>
- Remove all try-catch blocks; use Result pattern
❌ 🔴 Update all use cases in Products module
- Files: src/modules/products/application/useCases/*/[UseCase].usecase.ts
❌ 🟠 Chain Results for complex flows
- Example: Validation → Entity Creation → Persistence
- Use Result.combine() for multiple validations

3.4 Update Controllers to Handle Results

❌ 🔴 Update HTTP controllers

Location: src/modules/order/application/ms/http/

Pattern:

@Post()
async createOrder(@Body() dto: CreateOrderDto) {
  const result = await this.createOrderUseCase.execute(dto);

  if (result.isFailure) {
    throw new BadRequestException(result.getErrorValue());
  }

  return result.getValue();
}

❌ 🟠 Update WebSocket gateways
- Location: src/modules/order/application/ms/websocket/
❌ 🟠 Update TCP controllers
- Location: src/modules/order/application/ms/tcp/

3.5 Create Domain Error Classes

❌ 🟠 Create base domain error

Location: src/shared/ddd/DomainError.ts

Template:

export abstract class DomainError extends Error {
  constructor(message: string) {
    super(message);
    this.name = this.constructor.name;
  }
}

❌ 🟠 Create specific domain errors
- Location: src/modules/order/domain/errors/
- Examples:
  - OrderNotFoundError.ts
  - InvalidOrderStateError.ts
  - InsufficientInventoryError.ts

3.6 Add Comprehensive Validation

❌ 🟠 Review and enhance Guard utility
- Location: src/shared/commons/Guard.ts
- Add missing validations:
  - Email format
  - Phone format
  - Date ranges
  - Numeric ranges
❌ 🟠 Create custom validators for domain rules
- Location: src/modules/order/domain/validators/

4. Additional Improvements (Bonus)

4.1 Claude Code Skills Development

Goal: Enhance developer productivity with custom Claude Code skills for code generation, analysis, and quality assurance.

4.1.1 Completed Skills ✅

4.1.2 Priority Skills (Tier 1) - High Impact ✅

✅ 🔴 /generate-tests - Smart test generator
- Why: Immediate impact on test coverage (currently 12.91%, target 80%)
- Features:
  - Generate unit tests for use cases with success/failure paths
  - Generate domain entity tests (factory methods, business logic)
  - Generate integration tests for repositories
  - Generate E2E tests for HTTP endpoints
  - Generate test fixtures and mocks
  - Edge case and error case coverage
- Impact: Accelerate path to 80% coverage target
✅ 🔴 /security-audit - Security vulnerability analysis
- Why: Production readiness and OWASP compliance
- Features:
  - OWASP Top 10 vulnerability checks
  - Secrets/credentials detection in code
  - SQL injection and XSS detection
  - Authentication/Authorization review
  - Input validation gap analysis
  - Dependency security audit
- Impact: Ensure production-grade security
✅ 🔴 /refactor-to-pattern - Architecture refactoring assistant
- Why: Maintain Clean Architecture quality as codebase evolves
- Features:
  - Convert anemic models to rich domain entities
  - Extract value objects from primitives
  - Move business logic from use cases to domain
  - Split god classes into proper aggregates
  - Convert transaction scripts to use cases
- Impact: Prevent architectural erosion

4.1.3 High-Value Skills (Tier 2)

❌ 🟠 /performance-audit - Performance analysis
- N+1 query detection
- Slow/blocking operations
- Memory leak detection
- Database query optimization
❌ 🟠 /generate-docs - Documentation generator
- Module README files
- API documentation (Swagger/OpenAPI)
- Architecture diagrams (C4, UML)
- Changelog from git commits
❌ 🟠 /setup-ci-cd - CI/CD pipeline generator
- GitHub Actions workflows
- GitLab CI/CD pipelines
- Docker/Docker Compose setup
- Quality gates configuration
❌ 🟠 /env-validator - Environment configuration helper
- Validate .env files
- Generate .env.example from code
- Type-safe environment config

4.1.4 Nice-to-Have Skills (Tier 3)

❌ 🟢 /generate-migration - Database migration helper
❌ 🟢 /api-contract - API contract management
❌ 🟢 /dependency-upgrade - Safe dependency updates
❌ 🟢 /review-pr - Pull request reviewer
❌ 🟢 /generate-e2e - E2E test scenario generator

Current Status: 12 skills created (9 base + 3 priority Tier 1), 9 remaining for complete suite

4.2 Testing

✅ 🟠 Create unit tests for config module
- Created comprehensive tests for all config providers
- Achieved 100% coverage (45/45 statements, 17/17 functions, 43/43 lines)
- 46 tests across 5 test suites
❌ 🟠 Create unit tests for all use cases
- Pattern: [UseCase].usecase.spec.ts
- Test both success and failure paths with Result pattern
❌ 🟠 Create unit tests for domain entities
- Pattern: [Entity].spec.ts
- Test factory methods and business logic
❌ 🟢 Create integration tests for event flows
- Test complete saga workflows

4.2 Documentation

❌ 🟠 Document port interfaces
- Add JSDoc comments explaining each port's responsibility
❌ 🟠 Document domain events
- Create event catalog: _docs/events/event-catalog.md
❌ 🟢 Create architecture decision records (ADRs)
- Location: _docs/adr/

4.3 Code Quality

❌ 🟢 Run ESLint and fix violations
- Command: npm run lint
✅ 🟢 Run tests and ensure coverage
- Command: npm run test:cov
- Target: >80% coverage
- Current Status: 12.11% statements, 0% branches, 21.11% functions, 19.35% lines
- Gap: 67.89% coverage needed to reach target
- Analysis: See TEST_COVERAGE_ANALYSIS.md for full report
❌ 🟢 Run SonarQube analysis
- Fix critical/major issues

5. Module Migration to New Structure

Goal: Migrate all modules to follow the new 4-layer architecture (Domain → Application → Adapters → Infrastructure).

5.1 Migrate Products Module

5.2 Migrate Logger Module

❌ 🔴 Create src/modules/logger/infrastructure/ layer
- Create logger.module.ts with DI wiring
- Move adapter imports from application to infrastructure
❌ 🟠 Review and fix layer boundary violations
- Ensure domain has zero framework dependencies
- Update ports to not import from adapters

5.3 Validate All Modules

❌ 🟠 Run architecture validation
- Verify all domain layers have zero @nestjs/* imports
- Verify all application layers don't import from adapters
- Verify all ports use DTOs instead of schemas
❌ 🟢 Update documentation
- Update module-specific READMEs if they exist
- Add migration notes to _docs/

Progress Tracker

Approach	Total Tasks	Completed	Not Started	% Complete
1. Port-Adapter Pattern	12	4	8	33%
2. Event-Driven Design	13	0	13	0%
3. Result Pattern	14	0	14	0%
4. Bonus Improvements	8	2	6	25%
5. Module Migration	8	0	8	0%
TOTAL	55	6	49	11%

Completed Tasks Log

2026-01-14

✅ Order Module WebSocket - 100% Coverage Achieved 🎉
- Improved WebSocket module from 76.08% to 100% coverage
- Added comprehensive tests for all uncovered files
- Test improvements:
  - Enhanced websocket.service.spec.ts with module tests
  - Added 3 tests for WebsocketGatewayModule (definition, provider, export)
  - Created index.spec.ts for bootstrap testing
  - Added 3 tests for bootstrap function and IIFE execution
- Total: 12 tests for WebSocket module (was 6, +6 tests)
- Files now at 100% coverage:
  - websocket.service.ts (was 100%, maintained)
  - websocket.module.ts (was 0%, now 100%)
  - index.ts (was 0%, now 100%)
- Overall impact:
  - Project statements: 12.11% → 12.91% (+0.80%)
  - Project functions: 21.11% → 22.36% (+1.25%)
  - Project lines: 19.35% → 20.56% (+1.21%)
  - Total tests: 56 → 62 (+6 tests)
  - Test suites: 9 → 10 (+1 suite)
- Updated TEST_COVERAGE_ANALYSIS.md with improvements
- Note: Moved WebSocket from "Partial Coverage" to "Excellent Coverage (80-100%)" section
✅ Test Coverage Analysis - Baseline Established
- Ran comprehensive test coverage analysis: npm run test:cov
- Total tests: 56 passed across 9 test suites
- Execution time: 5.795s
- Overall coverage results:
  - Statements: 12.11% (Target: 80% - Gap: 67.89%)
  - Branches: 0% (Target: 80% - Gap: 80%)
  - Functions: 21.11% (Target: 80% - Gap: 58.89%)
  - Lines: 19.35% (Target: 80% - Gap: 60.65%)
- Created comprehensive analysis report: TEST_COVERAGE_ANALYSIS.md
- Documented module-level breakdown:
  - 🟢 Config module: 100% coverage (46 tests)
  - 🟢 Order HTTP Core: 100% coverage
  - 🟡 Order HTTP API: 79.41% coverage
  - 🟡 Order WebSocket: 76.08% coverage
  - 🔴 Order Use Cases: 30.76% coverage (0% function coverage)
  - 🔴 Order Domain: 34.61% coverage (0% branch/function coverage)
  - 🔴 Products module: 0% coverage (entire module)
  - 🔴 Logger module: 0% coverage (except health endpoints)
- Identified critical gaps:
  1. 0% branch coverage across entire codebase
  2. Use cases untested (CreateOrder, CreateProduct, CreateLog)
  3. Domain entities untested (factory methods, business logic)
  4. Repository implementations untested
  5. Event handlers untested
- Created 4-phase roadmap to reach 80% coverage target
- Recommendations prioritized by High/Medium/Low priority
- Next actions: Focus on use case and domain entity testing
✅ Config Module Unit Tests - 100% Coverage
- Created comprehensive unit tests for all config providers
- Test files created:
  - src/config/config.service.spec.ts - 9 tests covering config orchestration
  - src/config/config.module.spec.ts - 5 tests covering NestJS module setup
  - src/config/providers/database.config.spec.ts - 6 tests covering database configuration
  - src/config/providers/logger.module.config.spec.ts - 25 tests covering all logger configuration getters
  - src/config/providers/microservice.config.spec.ts - 7 tests covering version parsing from package.json
- Coverage achieved:
  - Statements: 100% (45/45)
  - Branches: 100% (0/0)
  - Functions: 100% (17/17)
  - Lines: 100% (43/43)
- Total: 46 tests passed across 5 test suites
- Test patterns: Proper mocking with jest, error handling scenarios, edge cases
- All tests follow existing project conventions

2026-01-12

✅ Shared Layer Abstraction Separation Review
- Reviewed entire src/shared/ directory for Clean Architecture compliance
- Found 3 critical layer boundary violations:
  - ddd/AggregateRoot.ts imports @nestjs/event-emitter (framework dependency in domain)
  - commons/core/Event.handler.ts imports @nestjs/event-emitter (framework in commons)
  - commons/core/Event.handler.ts has upward dependency to application/context/RequestContextService
- Identified root cause: EventHandler base class pollutes domain layer with framework coupling
- Documented structural issues:
  - EventHandler mixing concerns (event management + context + framework)
  - Static RequestContext dependency problematic for domain objects outside HTTP context
  - Inconsistent port naming (interface.ts vs logger.port.ts)
- Positive findings:
  - Guard, Result, UseCase, ValueObject, Identifier are pure (zero framework deps)
  - Repository interfaces properly separated from implementations
  - Adapters correctly isolated
- Created task list for fixing violations with refactoring strategy
- Impact: Every domain Entity is indirectly coupled to NestJS through EventHandler inheritance
✅ Port Interface Naming Standardization & Documentation
- Renamed src/shared/adapters/repository/interface.ts to Repository.port.ts
- Added comprehensive JSDoc documentation to Repository.port.ts:
  - Interface overview with architecture context
  - Generic type parameter documentation
  - Detailed method documentation with @param, @returns, @throws, @remarks
  - Code examples for each method
  - Best practices and usage patterns
  - @todo annotations for future improvements (pagination, better type safety)
- Enhanced src/shared/adapters/ports/logger.port.ts with comprehensive documentation:
  - Port interface overview and purpose
  - Dependency injection examples
  - Detailed method documentation for log(), error(), warn(), debug()
  - Use case examples for each log level
  - Best practices for production vs development logging
- Updated all 3 import references to use new Repository.port.ts:
  - src/shared/adapters/repository/mongoose/mongoose.service.ts
  - src/modules/order/adapters/repository/order.interface.ts
  - src/modules/products/adapters/repository/order.interface.ts
- Deleted old interface.ts file
- Verified build passes with new structure
- Consistent naming convention now established: [InterfaceName].port.ts

2026-01-10

✅ Husky replaced with Lefthook
- Uninstalled Husky package from devDependencies
- Installed Lefthook v2.0.13
- Created lefthook.yml with pre-commit hook running npm test
- Updated package.json prepare script from husky install to lefthook install
- Removed .husky/ directory
- Fixed git core.hooksPath config (was pointing to old .husky/_)
- Verified hooks work correctly in git worktree environment
✅ Products Module Layer Boundary Audit
- Reviewed all layers: Domain, Application, Adapters, Infrastructure
- Found 11 critical violations of clean architecture boundaries
- Created comprehensive audit report: PRODUCTS_MODULE_AUDIT.md
- Violations documented:
  - Domain layer: 2 violations (cross-module domain imports)
  - Application layer: 4 violations (importing from other module's domain/application)
  - Adapters layer: 2 violations (importing domain from other modules)
  - Infrastructure layer: 3 violations (importing all adapters from order module)
- Root cause: Module is copy-paste of Order module, not a real Products module
- Decision: Left as-is, documented for educational purposes
- Added warning notes to prevent use as clean architecture reference

2026-01-07

✅ Order Module Layer Boundary Audit
- Fixed domain layer: removed all @nestjs/* imports from event handlers
- Moved orderCreated.handler.ts from domain/events/handlers/ to application/events/
- Fixed port orderService.port.ts: replaced schema import with DTO
- Created infrastructure/order.module.ts for NestJS DI wiring
- Updated CreateOrder.module.ts to not import from adapters
- Updated api.module.ts to use OrderInfrastructureModule
- Fixed all unit tests (12 passing)

Next Steps

Start Here: Begin with approach #1 (Port-Adapter Pattern) as it establishes the foundation ✅ Done for Order module
Current Focus: Migrate products and logger modules to new structure
Priority Order:
- Complete all 🔴 High priority tasks first
- Then tackle 🟠 Medium priority tasks
- Finally address 🟢 Low priority tasks
Replicate Pattern: Apply same patterns from order module to other modules

Notes

Update this file as you complete tasks
Add new tasks as you discover architectural improvements
Link to specific commits when tasks are completed
Document any deviations from the plan with rationale

Last Updated: 2026-01-14 Current Focus: WebSocket module achieved 100% coverage (76.08% → 100%). Overall coverage improved to 12.91% statements (+0.80%). Next targets: HTTP API module (79.41% → 100%), then use cases and domain entities. See TEST_COVERAGE_ANALYSIS.md for roadmap.

FilesExpand file tree

TODO.md

Latest commit

History

TODO.md

File metadata and controls

TODO: Clean Architecture Best Practices Implementation

Overview

1. Strict Layer Separation with Port-Adapter Pattern

1.1 Audit Current Architecture

1.2 Define Missing Ports (Interfaces)

1.3 Refactor Use Cases to Depend on Ports

1.4 Update Module Providers

1.5 Validate Domain Layer Purity

2. Event-Driven Domain Design with Choreography

2.1 Audit Current Event Implementation

2.2 Identify Missing Domain Events

2.3 Implement Missing Domain Events

2.4 Implement Event Handlers

2.5 Update Use Cases to Publish Events

2.6 Implement Choreography Sagas

3. Result/Either Pattern for Explicit Error Handling

3.1 Audit Current Error Handling

3.2 Implement Guard Validations

3.3 Refactor Use Cases to Return Results

3.4 Update Controllers to Handle Results

3.5 Create Domain Error Classes

3.6 Add Comprehensive Validation

4. Additional Improvements (Bonus)

4.1 Claude Code Skills Development

4.1.1 Completed Skills ✅

4.1.2 Priority Skills (Tier 1) - High Impact ✅

4.1.3 High-Value Skills (Tier 2)

4.1.4 Nice-to-Have Skills (Tier 3)

4.2 Testing

4.2 Documentation

4.3 Code Quality

5. Module Migration to New Structure

5.1 Migrate Products Module

5.2 Migrate Logger Module

5.3 Validate All Modules

Progress Tracker

Completed Tasks Log

2026-01-14

2026-01-12

2026-01-10

2026-01-07

Next Steps

Notes