Capstone: a fully-typed, authed, tested API

The skeleton: feature modules over a typed core

When you inherit a codebase where the same role-check appears in a dozen controllers, you feel the cost of every missing seam. The skeleton below makes those seams explicit so each concern has exactly one home.

A service you can reason about has two kinds of module. Feature modules (OrdersModule, UsersModule) own one slice of the domain and follow the same internal shape: a Controller (HTTP edge, no logic), a Service (business operations, the only place rules live), and a Repository (persistence, a typed Repository<T>). A single core module owns everything cross-cutting: a typed ConfigModule, the global ValidationPipe, the global logging interceptor, the global exception filter, the auth guard, and the health controller. Feature modules import the core; nothing imports a feature module’s internals.

The core module is where the lifecycle gets bound once, with DI-aware provider tokens so the guard/filter/interceptor can themselves inject dependencies:

import { Module } from '@nestjs/common';
import { APP_GUARD, APP_PIPE, APP_FILTER, APP_INTERCEPTOR } from '@nestjs/core';
import { ConfigModule } from '@nestjs/config';
import { ValidationPipe } from '@nestjs/common';
import { JwtAuthGuard } from './auth/jwt-auth.guard';
import { AllExceptionsFilter } from './filters/all-exceptions.filter';
import { TransformInterceptor } from './interceptors/transform.interceptor';
import { validateEnv } from './config/env.validation';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true, validate: validateEnv }), // fail-fast at boot
  ],
  providers: [
    { provide: APP_GUARD, useClass: JwtAuthGuard },                  // authn on every route
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({ whitelist: true, transform: true }),
    },
    { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },     // envelope + timing
    { provide: APP_FILTER, useClass: AllExceptionsFilter },           // one error shape
  ],
})
export class CoreModule {}

whitelist: true strips properties with no DTO decorator (defends against mass-assignment); transform: true turns the plain JSON body into a real DTO instance and coerces primitives. Binding via APP_* tokens — not app.useGlobalGuards() — keeps these globals inside the DI container, so the guard can inject Reflector and the filter can inject your Logger.

One request, the fixed lifecycle as the spine

Every request walks the same gauntlet you learned earlier — now read it as the spine of the whole design. JwtAuthGuard (authentication) runs first and reads @Public() metadata so /health and /login opt out. RolesGuard (authorization) reads @Roles() and decides access — settled before any body is parsed. ValidationPipe turns the typed DTO in. The handler is thin: it calls the service and returns. The Service runs the business operation inside dataSource.transaction, sharing the transactional EntityManager so every write commits or rolls back together. The interceptor wraps the response in the envelope and records timing on the way out. The AllExceptionsFilter shapes anything that throws at any stage.

// orders.controller.ts — thin edge, no business logic
@Controller('orders')
export class OrdersController {
  constructor(private readonly orders: OrdersService) {}

  @Post()
  @Roles('customer')
  create(@Body() dto: CreateOrderDto, @CurrentUser() user: AuthUser) {
    return this.orders.place(dto, user.id); // DTO already validated by the global pipe
  }
}

// orders.service.ts — rules live here, persistence runs in one transaction
@Injectable()
export class OrdersService {
  constructor(private readonly dataSource: DataSource) {}

  place(dto: CreateOrderDto, userId: string): Promise<OrderView> {
    return this.dataSource.transaction(async (manager) => {
      const repo = manager.getRepository(Order);                 // typed Repository<Order>
      const stock = await manager.findOne(Product, { where: { id: dto.productId } });
      if (!stock || stock.qty < dto.quantity) throw new ConflictException('out of stock');
      const order = repo.create({ userId, ...dto });
      await repo.save(order);                                    // same tx as the stock read
      return toOrderView(order);                                 // domain -> response DTO
    });
  }
}

The handler never sees a transaction, a role check, or an error shape — those live in their lifecycle slots. The service never sees HTTP. That separation is the whole point: each stage references the right earlier lesson — guards for authz, the pipe for validation, the shared transactional manager for persistence, the interceptor for the envelope, the filter for errors.

Types at the edges, fail-fast at boot

The contract of this service is its types, enforced where data crosses a boundary. Three DTOs, never one: a request DTO (validated input), a domain entity (what the database holds), and a response DTO (what callers see — never leak the entity). Config is typed too: registerAs plus ConfigType gives the service a strongly-typed slice instead of stringly-typed process.env lookups, and validate rejects a bad environment at boot rather than at first use.

// config/database.config.ts
import { registerAs, ConfigType } from '@nestjs/config';

export const databaseConfig = registerAs('db', () => ({
  url: process.env.DATABASE_URL!,
  poolSize: Number(process.env.DB_POOL_SIZE ?? 10),
}));
export type DatabaseConfig = ConfigType<typeof databaseConfig>;

// somewhere in a provider:
constructor(@Inject(databaseConfig.KEY) private readonly db: DatabaseConfig) {}
// db.poolSize is number, db.url is string — no `as`, no `process.env` at call sites

The production-readiness checklist is the senior judgment that separates “compiles” from “trust on call”:

Together, these six items form a single fail-fast strategy: the earlier a misconfiguration surfaces — at boot rather than at checkout, at the load-balancer rather than in a running pod — the smaller the blast radius. Miss any one of them and you own that specific on-call night.

The testing strategy mirrors the layering: unit-test services with mocked repositories — fast, no DB, asserting the business rules in isolation — and e2e-test the wired pipeline with a real test database and a real token, so the guard, pipe, transaction, interceptor, and filter are all exercised exactly as in production.