# vladotesanovic/cqrs architecture

> Architecture diagram of the GitHub repository vladotesanovic/cqrs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vladotesanovic/cqrs
- Repository: https://github.com/vladotesanovic/cqrs

## Overview

#### 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.

Main entry points: [`src/auction/auction.handler.ts`](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.handler.ts) (Auction handlers), [`src/app.module.ts`](https://github.com/vladotesanovic/cqrs/blob/master/src/app.module.ts) (Module wiring), [`src/app.controller.ts`](https://github.com/vladotesanovic/cqrs/blob/master/src/app.controller.ts) (HTTP controller), [`src/auction/auction.events.ts`](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.events.ts) (Auction events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main(("Bootstrap<br/>NestJS entry<br/>[main.ts]"))
  node_app_module["Module wiring<br/>NestJS module<br/>[app.module.ts]"]
  node_controller["HTTP controller<br/>request boundary<br/>[app.controller.ts]"]
end

subgraph group_auction["Auction CQRS"]
  node_auction_commands["Auction commands<br/>CQRS write contracts<br/>[auction.command.ts]"]
  node_auction_queries["Auction queries<br/>CQRS read contracts<br/>[auction.query.ts]"]
  node_auction_handlers["Auction handlers<br/>command/query handlers<br/>[auction.handler.ts]"]
  node_auction_model{{"Auction model<br/>domain state<br/>[auction.model.ts]"}}
  node_auction_repository[("Auction repository<br/>persistence boundary")]
  node_auction_events["Auction events<br/>domain events<br/>[auction.events.ts]"]
  node_auction_saga["Auction saga<br/>process manager<br/>[auction.saga.ts]"]
end

subgraph group_bid["Bid Processing"]
  node_bid_commands["Bid commands<br/>CQRS write contracts<br/>[bid.command.ts]"]
  node_bid_handlers["Bid handlers<br/>command handlers<br/>[bid.handler.ts]"]
  node_bid_events["Bid events<br/>domain events<br/>[bid.events.ts]"]
  node_bid_saga["Bid saga<br/>process manager<br/>[bid.saga.ts]"]
end

subgraph group_mail["Notifications"]
  node_mail_commands["Mail commands and DTO<br/>notification contracts<br/>[mail.command.ts]"]
  node_mail_handler["Mail handler<br/>notification boundary<br/>[mail.handler.ts]"]
end

node_main -->|"boots"| node_app_module
node_app_module -->|"registers"| node_controller
node_app_module -->|"wires"| node_auction_handlers
node_app_module -->|"wires"| node_bid_handlers
node_app_module -->|"wires"| node_mail_handler
node_controller -->|"issues"| node_auction_commands
node_controller -->|"issues"| node_auction_queries
node_controller -->|"issues"| node_bid_commands
node_auction_commands -->|"handled by"| node_auction_handlers
node_auction_queries -->|"handled by"| node_auction_handlers
node_auction_handlers -->|"changes state"| node_auction_model
node_auction_handlers -->|"reads/writes"| node_auction_repository
node_auction_handlers -->|"publishes"| node_auction_events
node_auction_events -.->|"observed by"| node_auction_saga
node_auction_saga -.->|"dispatches"| node_auction_commands
node_bid_commands -->|"handled by"| node_bid_handlers
node_bid_handlers -->|"publishes"| node_bid_events
node_bid_events -.->|"observed by"| node_bid_saga
node_auction_events -.->|"can coordinate"| node_bid_saga
node_auction_saga -.->|"dispatches"| node_mail_commands
node_bid_saga -.->|"dispatches"| node_mail_commands
node_mail_commands -->|"handled by"| node_mail_handler

click node_main "https://github.com/vladotesanovic/cqrs/blob/master/src/main.ts"
click node_app_module "https://github.com/vladotesanovic/cqrs/blob/master/src/app.module.ts"
click node_controller "https://github.com/vladotesanovic/cqrs/blob/master/src/app.controller.ts"
click node_auction_commands "https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.command.ts"
click node_auction_queries "https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.query.ts"
click node_auction_handlers "https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.handler.ts"
click node_auction_model "https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.model.ts"
click node_auction_repository "https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.repository.ts"
click node_auction_events "https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.events.ts"
click node_auction_saga "https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.saga.ts"
click node_bid_commands "https://github.com/vladotesanovic/cqrs/blob/master/src/bid/bid.command.ts"
click node_bid_handlers "https://github.com/vladotesanovic/cqrs/blob/master/src/bid/bid.handler.ts"
click node_bid_events "https://github.com/vladotesanovic/cqrs/blob/master/src/bid/bid.events.ts"
click node_bid_saga "https://github.com/vladotesanovic/cqrs/blob/master/src/bid/bid.saga.ts"
click node_mail_commands "https://github.com/vladotesanovic/cqrs/blob/master/src/mail/mail.command.ts"
click node_mail_handler "https://github.com/vladotesanovic/cqrs/blob/master/src/mail/mail.handler.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app_module,node_controller toneBlue
class node_auction_commands,node_auction_queries,node_auction_handlers,node_auction_model,node_auction_repository,node_auction_events,node_auction_saga toneAmber
class node_bid_commands,node_bid_handlers,node_bid_events,node_bid_saga toneMint
class node_mail_commands,node_mail_handler toneRose
```

## Components

### Application

- [Bootstrap](https://github.com/vladotesanovic/cqrs/blob/master/src/main.ts): NestJS entry · `src/main.ts`
- [Module wiring](https://github.com/vladotesanovic/cqrs/blob/master/src/app.module.ts): NestJS module · Composes application dependencies. · `src/app.module.ts`
- [HTTP controller](https://github.com/vladotesanovic/cqrs/blob/master/src/app.controller.ts): request boundary · `src/app.controller.ts`

### Auction CQRS

- [Auction commands](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.command.ts): CQRS write contracts · `src/auction/auction.command.ts`
- [Auction queries](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.query.ts): CQRS read contracts · `src/auction/auction.query.ts`
- [Auction handlers](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.handler.ts): command/query handlers · Executes separate write and read paths. · `src/auction/auction.handler.ts`
- [Auction model](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.model.ts): domain state · `src/auction/auction.model.ts`
- [Auction repository](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.repository.ts): persistence boundary · `src/auction/auction.repository.ts`
- [Auction events](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.events.ts): domain events · `src/auction/auction.events.ts`
- [Auction saga](https://github.com/vladotesanovic/cqrs/blob/master/src/auction/auction.saga.ts): process manager · Reacts to lifecycle events with follow-up commands. · `src/auction/auction.saga.ts`

### Bid Processing

- [Bid commands](https://github.com/vladotesanovic/cqrs/blob/master/src/bid/bid.command.ts): CQRS write contracts · `src/bid/bid.command.ts`
- [Bid handlers](https://github.com/vladotesanovic/cqrs/blob/master/src/bid/bid.handler.ts): command handlers · `src/bid/bid.handler.ts`
- [Bid events](https://github.com/vladotesanovic/cqrs/blob/master/src/bid/bid.events.ts): domain events · `src/bid/bid.events.ts`
- [Bid saga](https://github.com/vladotesanovic/cqrs/blob/master/src/bid/bid.saga.ts): process manager · Coordinates bid activity through events. · `src/bid/bid.saga.ts`

### Notifications

- [Mail commands and DTO](https://github.com/vladotesanovic/cqrs/blob/master/src/mail/mail.command.ts): notification contracts · `src/mail/mail.command.ts`
- [Mail handler](https://github.com/vladotesanovic/cqrs/blob/master/src/mail/mail.handler.ts): notification boundary · Consumes notification commands; no provider adapter is present. · `src/mail/mail.handler.ts`

## Connections

- Bootstrap → Module wiring: boots
- Module wiring → HTTP controller: registers
- Module wiring → Auction handlers: wires
- Module wiring → Bid handlers: wires
- Module wiring → Mail handler: wires
- HTTP controller → Auction commands: issues
- HTTP controller → Auction queries: issues
- HTTP controller → Bid commands: issues
- Auction commands → Auction handlers: handled by
- Auction queries → Auction handlers: handled by
- Auction handlers → Auction model: changes state
- Auction handlers → Auction repository: reads/writes
- Auction handlers → Auction events: publishes
- Auction events → Auction saga: observed by
- Auction saga → Auction commands: dispatches
- Bid commands → Bid handlers: handled by
- Bid handlers → Bid events: publishes
- Bid events → Bid saga: observed by
- Auction events → Bid saga: can coordinate
- Auction saga → Mail commands and DTO: dispatches
- Bid saga → Mail commands and DTO: dispatches
- Mail commands and DTO → Mail handler: handled by