vladotesanovic/cqrs

Purpose and Runtime

This is a NestJS demonstration of CQRS and event-driven workflow for auctions, bids, and email notifications. It runs as a Node.js HTTP application, bootstrapped by src/main.ts, with dependency composition in src/app.module.ts.

HTTP Entry Layer

The application’s exposed request boundary is the root controller at src/app.controller.ts. The controller delegates work into the Nest/CQRS application layer rather than directly owning auction or bid state. src/app.controller.spec.ts covers this entry surface.

Auction CQRS Domain

The auction feature separates write, read, state, and persistence concerns:

• Commands: src/auction/auction.command.ts

• Queries: src/auction/auction.query.ts

• Command/query handlers: src/auction/auction.handler.ts

• Domain state/model: src/auction/auction.model.ts

• Repository boundary: src/auction/auction.repository.ts

• Shared auction contracts: src/auction/auction.interface.ts

This is the primary aggregate-oriented flow: a caller issues a command, a handler applies changes through the auction model/repository, and reads are routed through query handling rather than command logic.

Auction Event Publication and Process Coordination

Auction lifecycle events are defined in src/auction/auction.events.ts. src/auction/auction.saga.ts reacts to event streams and can issue follow-up commands, making it the long-running/process-manager boundary between auction state changes and downstream behavior. This decouples the command handler that produces an auction event from later actions triggered by that event.

Bid Processing

Bids are a separate command/event subsystem:

• Bid commands: src/bid/bid.command.ts

• Bid handlers: src/bid/bid.handler.ts

• Bid domain events: src/bid/bid.events.ts

• Cross-event orchestration: src/bid/bid.saga.ts

Bid handlers consume bid commands and emit bid-related events. The bid saga provides event-driven coordination, likely linking bid activity to auction lifecycle operations without requiring synchronous direct dependencies between feature handlers.

Mail Notification Boundary

Mail is modeled as a downstream command consumer rather than embedded in auction or bid handlers:

• Mail command and DTO: src/mail/mail.command.ts, src/mail/mail-dto.ts

• Mail command handler: src/mail/mail.handler.ts

Sagas can translate auction/bid events into mail commands; the mail handler is therefore the notification integration boundary. No concrete external mail provider or infrastructure adapter is present in the supplied tree.

Primary Control Flow and Boundaries

1. HTTP requests enter through src/app.controller.ts.

2. Command-side operations flow to auction or bid handlers.

3. Handlers update auction state through src/auction/auction.model.ts and src/auction/auction.repository.ts, then publish domain events.

4. Auction and bid sagas observe those events and dispatch consequential commands.

5. Notification work crosses into the mail command/handler subsystem.

The key architectural boundaries are CQRS command versus query paths, event publication versus event reaction, feature-specific auction/bid domains, and mail as an asynchronous downstream concern. NestJS module wiring is centralized in src/app.module.ts; no database, message broker, or external email-service implementation is represented in this repository tree.