{"id":48,"type":"blog","title":"NestJS Modules Are the Boundary","slug":"nestjs-modules-are-the-boundary","canonicalUrl":"https://docs.phatysd.me/content/nestjs-modules-are-the-boundary","status":"published","revision":1,"publishedAt":"2026-09-19T17:51:06.174Z","updatedAt":"2026-09-19T17:51:06.174Z","hierarchyPath":"NestJS > Engineering Journal > Architecture","topics":["NestJS","Modules","Dependency injection","Architecture"],"tags":["nestjs","typescript","modules","dependency-injection","architecture"],"related":[{"slug":"nestjs-feature-module-runbook","title":"NestJS Feature Module Runbook","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/nestjs-feature-module-runbook"}],"body":"# NestJS Modules Are the Boundary\n\nNestJS can look like a collection of decorators when you first open a project.\nThe more useful mental model is a graph of feature modules. Each module says\nwhich controllers and providers belong to a capability and which dependencies\nare intentionally imported or exported.\n\n## A module is an ownership statement\n\n`OrdersModule` is not just a folder name. It answers questions: which routes\nserve orders, which provider owns the use case, which repository is behind it,\nand which service is safe to expose to another feature?\n\nThat makes the module graph a design tool. A root module that imports many\nfeature modules is easy to explain. A root module that owns every provider is a\nsignal that feature boundaries have started to disappear.\n\n## Dependency injection helps when the boundary stays honest\n\nInjecting a service makes the controller easy to test and lets infrastructure\nchange without rewriting the route contract. It does not make every provider a\nglobal utility. If a provider belongs to one capability, keep it private to\nthat module unless another module has a clear reason to use it.\n\nExplicit exports are useful because they turn accidental coupling into a\nreviewable decision.\n\n## Validation is the first line, not the whole policy\n\nA global `ValidationPipe` gives the application a consistent request boundary.\nWhitelisting and rejecting unexpected properties can prevent a client from\nsilently sending fields that the DTO never intended to accept.\n\nBut a valid DTO is not an authorized command. Authorization, ownership, and\nbusiness invariants still belong in guards and application services. The\ncleanest NestJS code makes those responsibilities visible instead of hiding\nthem in a large controller.\n\n## Operations reveal whether the architecture is real\n\nModules and providers look tidy in a diagram. Production tests whether the\nboundaries work: does configuration fail early when required values are\nmissing? Do shutdown hooks close connections? Is API documentation exposed\nonly where the security policy allows it? Can a feature be tested without\nbooting unrelated features?\n\nThose questions are why I now treat the module graph and lifecycle hooks as\npart of the service's operational design, not only its code organization.\n\n## The practical rule\n\nCreate a module when a capability has its own routes, use cases, and data\nboundary. Keep controllers thin. Validate at the edge. Export only what a\ndifferent capability genuinely needs. If a module becomes a dumping ground,\nsplit it before the dependency graph becomes the architecture nobody wants to\nchange.\n\n## References\n\n- [NestJS modules](https://docs.nestjs.com/modules)\n- [NestJS validation](https://docs.nestjs.com/techniques/validation)\n- [NestJS configuration](https://docs.nestjs.com/techniques/configuration)\n- [NestJS lifecycle events](https://docs.nestjs.com/fundamentals/lifecycle-events)"}