🚀 v0.2.0: Architecture Polish & DDD Hardening

[raouf-b-dev]

🚀 v0.2.0: Architecture Polish & DDD Hardening

This release focuses on refining the architecture, enforcing strict Domain-Driven Design boundaries, cleaning up redundant boilerplate, and optimizing data access. Every change ensures system boundary definitions and error handling are as clear and efficient as possible.

🛠 What's New & Improved

🏗️ ACL Gateway & SAGA Cleanup

• Eliminated all cross-module imports violating DDD boundaries in the Orders module.
• Moved PaymentMethod + PaymentMethodType to shared-kernel to resolve downstream dependency violations.
• Gateway ports now define their own downstream DTOs (CheckoutCustomerInfo, CheckoutCartInfo) instead of leaking upstream types (ICustomer, ICart).
• Decoupled OrderEntity ↔ ProductEntity foreign key in the ORM layer (@ManyToOne removed).
• Rewired all 7 BullMQ SAGA job handlers to inject Application Services (Use Cases) instead of directly injecting secondary adapters — enforcing Job → UseCase → Gateway flow.
• Created 6 new SAGA-step Use Cases: ReserveStockForCheckoutUseCase, ReleaseCheckoutStockUseCase, ConfirmCheckoutReservationUseCase, CreateCheckoutPaymentUseCase, RefundCheckoutPaymentUseCase, ClearCheckoutCartUseCase.

🐛 Repository Cleanup & Bug Fix

• Removed cross-context ProductEntity and InventoryEntity queries from postgres.order-repository.ts — it now strictly manages orders and order_items tables only.
• Fixed a Double Stock Release Bug: cancelOrder() previously released stock atomically and triggered a SAGA compensation job, causing double-release. Now the repository only persists state; stock release is handled exclusively by the SAGA orchestrator.

🧹 Try/Catch Boilerplate Cleanup (61 Use Cases & Services)

• Repositories and Adapters use explicit Result<T, E> types internally. Outer use-cases previously wrapped this with redundant try/catch blocks.
• Result: Try/catch boilerplate stripped from 61 use-case files, leaving pure business logic orchestration with clean isFailure(result) checks.

🗄️ Database Index Optimization (Orders)

• Trimmed the orders table indexes from 12 down to the 4 essential patterns based on actual query behaviors (customer_id, status, payment_id, and customer_status).

♻️ Caching Decorator Naming Fix (21 files)

• Renamed all 7 caching repositories from Redis*Repository to Cached*Repository — explicitly separating the intent (caching) from the infrastructure (Redis), respecting Dependency Inversion.

🧪 Testing Infrastructure

• Added createMockRepository<T>() generic factory to typeorm.mocks.ts for strictly-typed ORM mocks — no more as any casting.
• Rewrote postgres.order-repository.spec.ts to match the simplified repository behavior (no cross-context tests).
• Updated all test mocks in job handlers and listeners to inject new Application Services.

🔌 Gateway Ports → Abstract Classes

• Converted all 4 Orders gateway ports (CustomerGateway, CartGateway, InventoryReservationGateway, PaymentGateway) from TypeScript interface to abstract class.
• Removed @Inject(TOKEN) decorators from 8 Use Cases and Listeners — NestJS now resolves dependencies natively via class type.
• Registered useExisting aliases in orders.module.ts so both the string token and the abstract class resolve to the same adapter.

🧱 DDD Layer Fix: ShippingAddressResolver

• Moved ShippingAddressResolver from core/domain/services/ → core/application/services/.
• Why: It imported ShippingAddressDto (primary adapter) and CheckoutCustomerInfo (application port) — two violations of the domain dependency rule.
• Updated spec file to use CheckoutCustomerInfo instead of ICustomer.

📝 Documentation Alignment

• Updated ARCHITECTURE.md context map — ACL arrows now show Use Case injection (e.g., FindCustomerUseCase) instead of the old *Repository references.
• Updated README.md v0.2.0 section with correct gateway count (7), new SAGA use cases, bug fix, and DDD relocation.
• Fixed stale PaymentMethodType import paths in Payments test suites after shared-kernel migration.

🗺️ New Production-Ready Roadmap

• Introduced a ROADMAP.md prioritizing features by real-world impact.
• Upcoming phases: Health Checks, Structured Logging, Correlation IDs, Dockerfile, Graceful Shutdown, Stripe/PayPal integrations.

🤖 CI/CD Automation

• Added .github/workflows/tag-on-merge.yml for automatic tagging upon version bumps.

📊 By The Numbers

• 86 Test Suites
• 578 individual tests passing
• Zero cross-module imports in orders/core/ (except shared-kernel)
• 7 ACL Gateway Ports across 3 modules
• 6 new SAGA Application Services
• 1 double-release bug fixed
• 1 DDD layer violation fixed (ShippingAddressResolver)

---

This discussion was created from the release 🚀 v0.2.0: Architecture Polish & DDD Hardening.