Merge pull request #65 from raouf-b-dev/feature/ES-66-decouple-cross-module-dependencies-in-orders

Feature/es 66 decouple cross module dependencies in orders

Author: raouf-b-dev

ARCHITECTURE.md

@@ -5,6 +5,7 @@ This document provides a high-level overview of the **ecommerce-store-api** arch
 ## 📋 Table of Contents
 
 - [System Context](#-system-context-c4-level-1)
+- [Strategic Domain-Driven Design](#-strategic-domain-driven-design)
 - [High-Level Architecture](#-high-level-architecture)
 - [Component Dependencies](#-component-dependencies-c4-level-2)
 - [Checkout Sequence Diagram](#-checkout-sequence-diagram-online-flow)
@@ -15,6 +16,58 @@ This document provides a high-level overview of the **ecommerce-store-api** arch
 - [Idempotency Logic](#-idempotency-logic)
 - [Notification System Architecture](#-notification-system-architecture)
 
+## 🧠 Strategic Domain-Driven Design
+
+We utilize **Strategic DDD** to define boundaries and relationships between different parts of the system.
+
+### Subdomains
+
+| Subdomain         | Type            | Description                                                                                                              |
+| :---------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| **Orders**        | **Core Domain** | The heart of the business. Handles the complex lifecycle of customer orders, SAGA orchestration, and revenue generation. |
+| **Inventory**     | Supporting      | Manages stock levels. Essential but not the primary competitive advantage.                                               |
+| **Products**      | Supporting      | Manages the catalog. Supports the core selling process.                                                                  |
+| **Payments**      | Generic         | Handles transaction processing. Uses standard patterns (Stripe/PayPal) that can be bought/outsourced.                    |
+| **Auth**          | Generic         | Identity and Access Management. Standard JWT implementation.                                                             |
+| **Notifications** | Generic         | Delivery mechanism for alerts.                                                                                           |
+
+### Bounded Contexts & Context Mapping
+
+Each Module acts as a **Bounded Context**. We use **Context Mapping** to define how they interact, strictly enforcing boundaries to prevent a "Big Ball of Mud".
+
+```mermaid
+graph TD
+    subgraph "Core Domain"
+        Orders[Orders Context]
+    end
+
+    subgraph "Supporting Subdomains"
+        Inventory[Inventory Context]
+        Products[Products Context]
+        Carts[Carts Context]
+    end
+
+    subgraph "Generic Subdomains"
+        Customers[Customers Context]
+        Payments[Payments Context]
+    end
+
+    %% Relationships
+    Orders -->|ACL / CustomerGateway| Customers
+    Orders -->|ACL / CartGateway| Carts
+    Carts -->|ACL / InventoryGateway| Inventory
+
+    classDef core fill:#ff9999,stroke:#333,stroke-width:2px;
+    classDef support fill:#99ff99,stroke:#333,stroke-width:1px;
+    classDef generic fill:#9999ff,stroke:#333,stroke-width:1px;
+
+    class Orders core;
+    class Inventory,Products,Carts support;
+    class Customers,Payments generic;
+```
+
+> **Anti-Corruption Layer (ACL)**: The `Orders` context does **not** directly depend on the implementation of `Customers` or `Carts`. Instead, it defines its own **Ports** (Gateways), and we implement **Adapters** that translate external models into the Order domain's language. This protects the Core Domain from changes in upstream modules.
+
 ## 🌍 System Context (C4 Level 1)
 
 A high-level view of how the E-commerce API fits into the existing landscape.
@@ -106,14 +159,14 @@ graph TD
     end
 
     %% Orders Dependencies
-    Orders -->|Reserves Stock| Inventory
-    Orders -->|Processes Payment| Payments
-    Orders -->|Validates User| Customers
-    Orders -->|Retrieves Cart| Carts
-    Orders -->|Triggers| Notifications
+    Orders -->|ACL| Inventory
+    Orders -->|ACL| Payments
+    Orders -->|ACL| Customers
+    Orders -->|ACL| Carts
+    Orders -->|Event| Notifications
 
     %% Carts Dependencies
-    Carts -->|Checks Stock| Inventory
+    Carts -->|ACL| Inventory
     Carts -->|Validates Item| Products
 
     %% Auth Dependencies

README.md

@@ -49,6 +49,8 @@ I built this to prove (to myself and future employers) that I can handle complex
 ### 🏗️ **Architecture & Design**
 
 - **Domain-Driven Design (DDD)** with clear layer separation (Domain, Application, Infrastructure, Presentation)
+- **Strategic DDD** with explicit Subdomains (Core, Generic, Supporting) and Bounded Contexts
+- **Anti-Corruption Layer (ACL)** using Ports & Adapters to decouple modules
 - **Clean Architecture** principles ensuring the core logic is independent of frameworks and external tools
 - **Result Pattern** for consistent, type-safe error handling across the entire application
 - **Hexagonal Architecture (Ports & Adapters)** for easy swapping of infrastructure components (e.g., switching between Postgres and Redis repositories)

src/modules/carts/application/ports/inventory.gateway.ts

@@ -0,0 +1,10 @@
+import { Result } from '../../../../core/domain/result';
+import { InfrastructureError } from '../../../../core/errors/infrastructure-error';
+import { CheckStockResponse } from '../../../inventory/presentation/dto/check-stock-response.dto';
+
+export interface InventoryGateway {
+  checkStock(
+    productId: number,
+    quantity: number,
+  ): Promise<Result<CheckStockResponse, InfrastructureError>>;
+}

src/modules/carts/application/usecases/add-cart-item/add-cart-item.usecase.spec.ts

@@ -9,12 +9,13 @@ import { RepositoryError } from '../../../../../core/errors/repository.error';
 import { AddCartItemDto } from '../../../presentation/dto/add-cart-item.dto';
 import { ProductRepository } from '../../../../products/domain/repositories/product-repository';
 import { IProduct } from '../../../../products/domain/interfaces/product.interface';
+import { InventoryGateway } from '../../ports/inventory.gateway';
 
 describe('AddCartItemUseCase', () => {
   let usecase: AddCartItemUseCase;
   let mockCartRepository: MockCartRepository;
   let mockProductRepository: jest.Mocked<ProductRepository>;
-  let mockCheckStockUseCase: any;
+  let mockInventoryGateway: jest.Mocked<InventoryGateway>;
 
   const mockProduct: IProduct = {
     id: 1,
@@ -35,14 +36,14 @@ describe('AddCartItemUseCase', () => {
       findAll: jest.fn(),
       deleteById: jest.fn(),
     } as any;
-    mockCheckStockUseCase = {
-      execute: jest.fn(),
+    mockInventoryGateway = {
+      checkStock: jest.fn(),
     };
 
     usecase = new AddCartItemUseCase(
       mockCartRepository,
       mockProductRepository,
-      mockCheckStockUseCase,
+      mockInventoryGateway,
     );
   });
 
@@ -70,7 +71,7 @@ describe('AddCartItemUseCase', () => {
       mockProductRepository.findById.mockResolvedValue(
         Result.success(mockProduct),
       );
-      mockCheckStockUseCase.execute.mockResolvedValue(
+      mockInventoryGateway.checkStock.mockResolvedValue(
         Result.success({
           isAvailable: true,
           availableQuantity: 10,
@@ -159,7 +160,7 @@ describe('AddCartItemUseCase', () => {
       mockProductRepository.findById.mockResolvedValue(
         Result.success(mockProduct),
       );
-      mockCheckStockUseCase.execute.mockResolvedValue(
+      mockInventoryGateway.checkStock.mockResolvedValue(
         Result.success({
           isAvailable: false,
           availableQuantity: 5,
@@ -171,10 +172,10 @@ describe('AddCartItemUseCase', () => {
       const result = await usecase.execute({ cartId, dto });
 
       // Assert
-      expect(mockCheckStockUseCase.execute).toHaveBeenCalledWith({
-        productId: dto.productId,
-        quantity: dto.quantity,
-      });
+      expect(mockInventoryGateway.checkStock).toHaveBeenCalledWith(
+        dto.productId,
+        dto.quantity,
+      );
       ResultAssertionHelper.assertResultFailure(
         result,
         'Insufficient stock',

src/modules/carts/application/usecases/add-cart-item/add-cart-item.usecase.ts

@@ -1,4 +1,4 @@
-import { Injectable } from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
 import { UseCase } from '../../../../../core/application/use-cases/base.usecase';
 import { AddCartItemDto } from '../../../presentation/dto/add-cart-item.dto';
 import { ICart } from '../../../domain/interfaces/cart.interface';
@@ -7,7 +7,8 @@ import { CartRepository } from '../../../domain/repositories/cart.repository';
 import { ProductRepository } from '../../../../products/domain/repositories/product-repository';
 import { isFailure, Result } from '../../../../../core/domain/result';
 import { ErrorFactory } from '../../../../../core/errors/error.factory';
-import { CheckStockUseCase } from '../../../../inventory/application/check-stock/check-stock.usecase';
+import { InventoryGateway } from '../../ports/inventory.gateway';
+import { INVENTORY_GATEWAY } from '../../../carts.token';
 
 @Injectable()
 export class AddCartItemUseCase extends UseCase<
@@ -18,7 +19,8 @@ export class AddCartItemUseCase extends UseCase<
   constructor(
     private readonly cartRepository: CartRepository,
     private readonly productRepository: ProductRepository,
-    private readonly checkStockUseCase: CheckStockUseCase,
+    @Inject(INVENTORY_GATEWAY)
+    private readonly inventoryGateway: InventoryGateway,
   ) {
     super();
   }
@@ -52,10 +54,10 @@ export class AddCartItemUseCase extends UseCase<
       }
 
       // Check stock availability
-      const stockCheckResult = await this.checkStockUseCase.execute({
-        productId: dto.productId,
-        quantity: dto.quantity,
-      });
+      const stockCheckResult = await this.inventoryGateway.checkStock(
+        dto.productId,
+        dto.quantity,
+      );
 
       if (isFailure(stockCheckResult)) {
         return ErrorFactory.UseCaseError(stockCheckResult.error.message);

src/modules/carts/carts.module.ts

@@ -11,9 +11,14 @@ import { UpdateCartItemController } from './presentation/controllers/update-cart
 import { CartEntity } from './infrastructure/orm/cart.schema';
 import { CartItemEntity } from './infrastructure/orm/cart-item.schema';
 import { RedisModule } from '../../core/infrastructure/redis/redis.module';
-import { POSTGRES_CART_REPOSITORY, REDIS_CART_REPOSITORY } from './carts.token';
+import {
+  POSTGRES_CART_REPOSITORY,
+  REDIS_CART_REPOSITORY,
+  INVENTORY_GATEWAY,
+} from './carts.token';
 import { PostgresCartRepository } from './infrastructure/repositories/postgres-cart-repository/postgres.cart-repository';
 import { RedisCartRepository } from './infrastructure/repositories/redis-cart-repository/redis.cart-repository';
+import { ModuleInventoryGateway } from './infrastructure/adapters/module-inventory.gateway';
 import { CacheService } from '../../core/infrastructure/redis/cache/cache.service';
 import { CartRepository } from './domain/repositories/cart.repository';
 import { InventoryModule } from '../inventory/inventory.module';
@@ -58,6 +63,12 @@ import { ProductsModule } from '../products/products.module';
       inject: [CacheService, POSTGRES_CART_REPOSITORY],
     },
 
+    // Gateways
+    {
+      provide: INVENTORY_GATEWAY,
+      useClass: ModuleInventoryGateway,
+    },
+
     // Default Repository Binding
     {
       provide: CartRepository,

src/modules/carts/carts.token.ts

@@ -1,2 +1,3 @@
 export const POSTGRES_CART_REPOSITORY = Symbol('POSTGRES_CART_REPOSITORY');
 export const REDIS_CART_REPOSITORY = Symbol('REDIS_CART_REPOSITORY');
+export const INVENTORY_GATEWAY = Symbol('INVENTORY_GATEWAY');

src/modules/carts/infrastructure/adapters/module-inventory.gateway.ts

@@ -0,0 +1,31 @@
+import { Injectable } from '@nestjs/common';
+import { InventoryGateway } from '../../application/ports/inventory.gateway';
+import { CheckStockUseCase } from '../../../inventory/application/check-stock/check-stock.usecase';
+import { Result, isFailure } from '../../../../core/domain/result';
+import { InfrastructureError } from '../../../../core/errors/infrastructure-error';
+import { CheckStockResponse } from '../../../inventory/presentation/dto/check-stock-response.dto';
+import { ErrorFactory } from '../../../../core/errors/error.factory';
+
+@Injectable()
+export class ModuleInventoryGateway implements InventoryGateway {
+  constructor(private readonly checkStockUseCase: CheckStockUseCase) {}
+
+  async checkStock(
+    productId: number,
+    quantity: number,
+  ): Promise<Result<CheckStockResponse, InfrastructureError>> {
+    const result = await this.checkStockUseCase.execute({
+      productId,
+      quantity,
+    });
+
+    if (isFailure(result)) {
+      return ErrorFactory.InfrastructureError(
+        'Failed to check stock',
+        result.error,
+      );
+    }
+
+    return Result.success(result.value);
+  }
+}

src/modules/orders/application/ports/cart.gateway.ts

@@ -0,0 +1,8 @@
+import { Result } from '../../../../core/domain/result';
+import { ICart } from '../../../carts/domain/interfaces/cart.interface';
+import { InfrastructureError } from '../../../../core/errors/infrastructure-error';
+
+export interface CartGateway {
+  validateCart(cartId: number): Promise<Result<ICart, InfrastructureError>>;
+  getCart(cartId: number): Promise<Result<ICart, InfrastructureError>>;
+}

src/modules/orders/application/ports/customer.gateway.ts

@@ -0,0 +1,9 @@
+import { Result } from '../../../../core/domain/result';
+import { ICustomer } from '../../../customers/domain/interfaces/customer.interface';
+import { InfrastructureError } from '../../../../core/errors/infrastructure-error';
+
+export interface CustomerGateway {
+  validateCustomer(
+    userId: number,
+  ): Promise<Result<ICustomer, InfrastructureError>>;
+}