Chapter 8 — Modules & Services

The why

Every layer in NestJS has exactly one job. The moment you blur the lines — SQL in a controller, HTTP types in a service — the whole system becomes untestable and hard to change.

Before you write any code, trace the path a request takes from the moment it arrives to the moment a response goes out.

Each box has exactly one job. The moment you put SQL in the controller or HTTP knowledge in the service, you've crossed a layer boundary.

Guards — the gatekeeper

A guard answers one question: "Is this request allowed to proceed?"

The most common guard is JwtGuard, which:

1. Reads the Authorization: Bearer <token> header
2. Verifies the JWT signature
3. Checks it hasn't expired
4. Puts the user info into req.user

// Apply to a whole controller:
@Controller('orders')
@UseGuards(JwtGuard)
export class OrdersController { ... }
 
// Apply to a single method:
@Post()
@UseGuards(JwtGuard)
async create() { ... }

If no token is provided, JwtGuard returns HTTP 401 before the controller method ever runs.

Controllers — the thin HTTP adapter

The controller's job:

1. Parse the HTTP request (path params, query params, body, headers)
2. Call the service with clean arguments
3. Map the result to an output DTO
4. Return the HTTP response

Nothing more. No business logic. No SQL. No if/else decisions.

@ApiTags('orders')
@ApiBearerAuth()
@Controller({ path: 'orders', version: '1' })
@UseGuards(JwtGuard)
export class OrdersController {
  constructor(private readonly ordersService:

Services — where business logic lives

The service's job:

1. Apply business rules
2. Orchestrate multiple repository calls
3. Manage database transactions
4. Return domain objects

The service knows NOTHING about HTTP — no req, res, no status codes, no headers.

@Injectable()
export class OrdersService {
  private readonly logger = new Logger(OrdersService.name);
 
  constructor(
    @InjectModel(Order) private readonly orderModel: typeof Order,
    private readonly paymentsService

Service rules

Modules — how it all fits together

A module groups everything related to one bounded context:

// src/modules/orders/orders.module.ts
@Module({
  imports: [
    SequelizeModule.forFeature([Order, OrderItem]),  // register models
    RestaurantsModule,    // import module that provides RestaurantsService
  ],
  controllers: [OrdersController],

Module rules

Events — for cross-module side effects

When creating an order, do you also need to send an email, notify the restaurant, and update user stats? Don’t add all those service calls to OrdersService.create() — that would give it 8 dependencies and make it untestable.

Use events instead:

// In OrdersService — just announce what happened
this.eventEmitter.emit('order.placed', new OrderPlacedEvent(order));

// In EmailService — reacts to the event independently
@OnEvent('order.placed')
async sendConfirmation(event: OrderPlacedEvent) {
  await this.mailer.sendOrderConfirmation(event.order);
}

Now OrdersService has no idea who reacts to its events. Adding a new listener never requires touching OrdersService.

Dependency Injection — how NestJS wires everything

NestJS uses Dependency Injection. Instead of a service creating its own dependencies with new, they are declared in the constructor and NestJS provides them.

@Injectable()
export class OrdersService {
  constructor(
    // NestJS reads this constructor and automatically provides:
    @InjectModel(Order) private readonly orderModel: typeof Order,
    private readonly paymentsService: PaymentsService,
    private readonly sequelize: Sequelize

When NestJS starts up, it reads all @Module definitions, builds a dependency tree, and creates instances in the right order. You never call new OrdersService(...) yourself.

Why this is powerful: In tests, you can replace WalletService with a mock:

const module = await Test.createTestingModule({
  providers: [
    OrdersService,
    { provide: WalletService, useValue: { debit: jest.fn() } }, // mock!
    { provide: getModelToken(Order

One thing to remember