nestjs-architecture

Files (7)

• SKILL.md
• ddd-nestjs.md · references/
• module-structure.md · references/
• nestjs-cqrs.md · references/
• nestjs-deployment.md · references/
• nestjs-modules.md · references/
• nestjs-testing.md · references/

SKILL.md (first lines)

# NestJS Architecture

## Purpose
Structure NestJS applications with module-based architecture — domain modules, shared modules, dynamic modules, monorepo projects, and provider scoping.

## Agent Protocol

### Trigger
User request includes: `NestJS module structure`, `NestJS architecture`, `NestJS project layout`, `NestJS DI`, `NestJS modules`, `NestJS monorepo`, `NestJS providers`.

### Input Context
- NestJS version (10+)
- Architecture style (modular, monorepo, microservices)
- Database (TypeORM, Prisma, MikroORM, Mongoose)
- Transport (HTTP, WebSocket, TCP, RabbitMQ)

### Output Artifact
Module structure, provider registration, module exports, monorepo layout, DI setup.

### Response Format
Produce artifact directly. No preamble, no postamble, no explanations.

### Completion Criteria
- Root module imports feature modules
- Each domain has its own module with controllers, services, repositories
- Modules export only what other modules need
- Global modules registered sparingly (shared infra only)
- Dynamic modules configured with forRoot/forFeature

### Max Response Length
4096 tokens

## Architecture Decision Trees

### Module Organization: Feature vs Shared vs Core

| Module Type | Contains | Export Strategy | Example |
|-------------|----------|----------------|---------|
| Feature | Controllers, Services, Repositories | Only what others need | UsersModule, OrdersModule |
| Shared | Reusable utilities, guards, filters | Everything | CommonModule |
| Core | Singletons (DB, config, logger) | Global | DatabaseModule, ConfigModule |

Decision: Domain logic → Feature Module. Cross-cutting concern → Shared Module. Infrastructure singleton → Global Core Module.

### Provider Scope Decision

| Scope | Lifetime | Use Case |
|-------|----------|----------|
| DEFAULT (singleton) | One per app | Services, repositories, DB connections |
| TRANSIENT | New per injection | Stateful validators, per-request cache |
| REQUEST | New per HTTP request | Request-scoped data (tenant, user) |

Decision: Stateless service → DEFAULT. Stateful per-instance → TRANSIENT. Per-request data → REQUEST.

## Workflow

### Step 1: Project Structure

```
src/
  main.ts                              # Bootstrap
  app.module.ts                        # Root module
  app.controller.ts                    # Health check
  common/
    decorators/
      current-user.decorator.ts
      roles.decorator.ts
    guards/
      auth.guard.ts
      roles.guard.ts
    filters/
      http-exception.filter.ts
    interceptors/
      logging.interceptor.ts
      transform.interceptor.ts
    pipes/
      validation.pipe.ts
    interfaces/
      user-request.interface.ts
  modules/
    users/
      user.module.ts
      user.controller.ts
      user.service.ts
      user.repository.ts
      user.entity.ts
      dto/
        create-user.dto.ts
        update-user.dto.ts
    orders/
      order.module.ts
      order.controller.ts
      order.service.ts
      order.entity.ts
      dto/
  config/
    database.config.ts
    app.config.ts
```

### Step 2: Feature Module

```typescript
// modules/users/user.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { UserController } from './user.controller';
import { UserService } from './user.service';
import { UserRepository } from './user.repository';
import { User } from './user.entity';

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UserController],
  providers: [UserService, UserRepository],
  exports: [UserService],
})
export class UsersModule {}

From j4flmao/agent-skills, MIT.

More from j4flmao/agent-skills