1b:I[288412,["/_next/static/immutable/chunks/22p29gwb96j-r.js","/_next/static/immutable/chunks/36h3b3-9blmzs.js","/_next/static/immutable/chunks/3bpgduqf4ksca.js","/_next/static/immutable/chunks/2d3m-k720jl5i.js","/_next/static/immutable/chunks/1cz1vzqlz0yhj.js","/_next/static/immutable/chunks/1eb739fc05qmz.js","/_next/static/immutable/chunks/0xd1eiu9_iw_y.js"],"WireframeBlogDetail"] 1c:T1b63,

Most NestJS apps I've worked on end up organized the same way: one controllers/ folder, one services/ folder, one entities/ folder. It looks tidy on day one. By month six, adding a single feature means touching five different folders, and nobody can look at the codebase and say "that's the orders feature" — it's smeared across the whole app.

I put together nest-cqrs-vertical-slice as the reference I wish I'd had the first time I ran into vertical slice architecture — something to clone and actually run, not another article full of pseudo-code.

The problem with organizing by layer

Layer-first structure groups code by what it technically is — controller, service, entity — instead of what it does. That means:

A single feature's logic is scattered across the whole codebase
Changing one feature risks touching files that other features also depend on
There's no natural boundary stopping features from reaching into each other

Vertical slices flip the axis. Instead of organizing by layer, you organize by feature — and each feature owns its full stack, end to end, in one folder.

src/
├── category/     ← one feature = one folder = its own full stack
│   ├── api/               HTTP surface: controllers, DTOs
│   ├── application/       CQRS: commands, queries, their handlers
│   └── infrastructure/    persistence: TypeORM entities
├── product/
│   ├── api/
│   ├── application/
│   ├── domain/             events/   (published, not just declared)
│   └── infrastructure/
├── notification/
│   ├── api/                 a controller for a direct HTTP trigger
│   ├── application/
│   │   ├── commands/        SendNotificationCommand — manual send
│   │   ├── events/          ProductCreatedNotificationHandler — reacts to product/
│   │   └── interfaces/      INotificationService port + DI token
│   └── infrastructure/
│       └── services/        TelegramService — swappable concrete impl
└── shared/                 cross-cutting only: guards, decorators, entities

shared/ is the only thing every slice is allowed to depend on — and it's kept deliberately thin: guards, decorators, base entities. Nothing feature-specific lives there.

Three slices, three different lessons

Rather than one exhaustive example, the repo has three slices that each teach something different about the pattern.

category/ — the floor. Plain CRUD, no domain/ layer at all. There's no real business invariant to protect here, so the handler talks straight to Repository<CategoryEntity>. This is the point: you don't need a domain layer just because the pattern has room for one. Skip it when there's nothing to protect.

product/ — slices aren't sealed boxes. create-product validates categoryId against category/'s own entity, and category/'s delete handler checks product/'s entity before allowing a delete (409 if a product still references it). Slices can read across boundaries when the domain genuinely requires it — the rule isn't "never touch another slice," it's "no slice imports another slice's internals." product/ also publishes a real ProductCreatedEvent via a plain EventBus.publish() call — no aggregate, no event-sourcing machinery, just a domain event doing its job.

notification/ — event-driven, two ways in. POST /notifications/send triggers a notification directly through a command. ProductCreatedEvent triggers the same thing automatically via an @EventsHandler. Both paths go through the same INotificationService interface, currently backed by a TelegramService — swap in email or SMS without touching the handler at all.

Commands write, queries read — and never mix

The CQRS half of the pattern is enforced structurally, not just by convention. A command and a query never share a code path:

Write path:

Client → Controller → CommandBus.execute(CreateProductCommand)
       → CreateProductHandler → Repository.save(product)
       → EventBus.publish(ProductCreatedEvent)
       → 201 Created

Read path:

Client → Controller → QueryBus.execute(GetProductQuery)
       → GetProductHandler → Repository.findOne(id)
       → 200 OK

Controllers only ever dispatch to a bus. No business logic lives in api/ — that's the boundary that keeps HTTP concerns from leaking into the rest of the slice.

Running it

bash

cp .env.example .env      # defaults already match docker-compose
docker compose up -d      # postgres:16
npm install
npm run start:dev         # http://localhost:3000

Stack is NestJS 11, @nestjs/cqrs, TypeORM, PostgreSQL, and Jest for tests.

Adding your own slice

The repo's pattern for a new feature is five steps:

src/<feature>/api/{controllers,dto} — the HTTP surface
src/<feature>/application/{commands,queries} — one file per command/query, one per handler
src/<feature>/infrastructure/entities — the TypeORM entity
Only add domain/ if there's a real invariant to protect or an event to publish — category/ is proof it's fine to skip
Register the entity in src/typeorm.config.ts and the module in src/app.module.ts

Why this exists

There's no shortage of articles explaining vertical slice architecture and CQRS in the abstract. What's harder to find is a small, real codebase that shows the judgment calls — when to skip a domain/ layer, when it's fine for one slice to read another's entity, how an event actually gets published and consumed end to end. That's what this repo is for.

Clone it, run it, and read the actual handlers: 🔗 https://github.com/itsnang/NestJsCqrs

MIT licensed.

6:["$","$L1b",null,{"post":{"id":"blog_6Jw8EGcp0IYiyP","profileId":"1","title":"Vertical Slice Architecture + CQRS in NestJS","slug":"vertical-slice-architecture-cqrs-in-nestjs","excerpt":"A Working Reference for Vertical Slice Architecture + CQRS in NestJS","coverImage":"https://res.cloudinary.com/dnye8vqwb/image/upload/v1787495928/Blogs/NestJS_Header_4x3_qbqgqd.png","content":"$1c","status":"published","publishedAt":"$D2026-08-21T15:24:15.168Z","createdAt":"$D2026-08-21T15:24:15.278Z","updatedAt":"$D2026-08-23T15:29:24.808Z","deletedAt":null,"number":1,"total":1,"prev":null,"next":null}}]