NestJS Project Structure Enforcer

Enforces strict NestJS project organization, code quality standards, testing requirements, and automated validation for professional TypeScript backend development.

Project Organization

Source Code Structure

**Root Structure:**

**Required Configuration Files:**

**Validation:** Before starting any work, verify all required files exist. If missing, alert the user and recommend creating them.

Module Structure

Each module in `src/modules/` MUST contain:

**Optional Pattern Files:**

**Rule:** When creating a new module, ALWAYS scaffold all three required files (controller, service, module) together.

Testing Standards

Test Organization

**Test File Pattern:** `**/*.{spec,test,e2e-spec}.ts`

**Configuration Files:**

**Coverage Requirements:**

Testing Rules

1. **ALWAYS require tests** when creating new features

2. Generate test scaffolds automatically for new controllers and services

3. Run tests before allowing commits when `blockOnTestFail: true`

4. Unit tests live alongside source files (`*.spec.ts`)

5. E2E tests live in `test/` directory (`*.e2e-spec.ts`)

**Example Test Scaffold:**

```typescript

describe('UserService', () => {

let service: UserService;

beforeEach(async () => {

const module: TestingModule = await Test.createTestingModule({

providers: [UserService],

}).compile();

service = module.get<UserService>(UserService);

});

it('should be defined', () => {

expect(service).toBeDefined();

});

});

```

Database Management

Prisma Structure

**Schema:** `prisma/schema.prisma` - Single source of truth for database models

**Migrations:** `prisma/migrations/` - Database version control

**Seed:** `prisma/seed.ts` - Initial data population

Database Rules

1. **ALWAYS validate** `schema.prisma` exists before database operations

2. **Auto-migrate disabled** (`autoMigrateDb: false`) - require explicit migration commands

3. **Auto-generate types enabled** - run `prisma generate` after schema changes

4. Validate Prisma client is properly installed and typed

**Migration Workflow:**

```bash

Create migration

npx prisma migrate dev --name <migration-name>

Generate client

npx prisma generate

Apply to production

npx prisma migrate deploy

```

API Documentation

Swagger/OpenAPI

**Configuration Path:** `src/swagger/`

**Output:** `openapi.json`

**Rules:**

1. Auto-update documentation when controllers change (`autoUpdateDocs: true`)

2. Decorate all DTOs with Swagger decorators (`@ApiProperty`)

3. Document all endpoints with `@ApiOperation`, `@ApiResponse`

4. Generate OpenAPI spec on build

**Example Documentation:**

```typescript

@ApiOperation({ summary: 'Create user' })

@ApiResponse({ status: 201, description: 'User created successfully' })

@ApiResponse({ status: 400, description: 'Bad request' })

@Post()

async create(@Body() createUserDto: CreateUserDto) {

// ...

}

```

Code Quality Standards

File Size Limits

**Action:** If limits exceeded, suggest refactoring into smaller modules/functions.

Naming Conventions

Strict Typing

**Example:**

```typescript

// ✅ Good

async findById(id: string): Promise<User | null> {

return this.prisma.user.findUnique({ where: { id } });

}

// ❌ Bad

async findById(id) {

return this.prisma.user.findUnique({ where: { id } });

}

```

Validation Rules

Pre-Flight Checks

Before executing any task, validate:

1. **Environment** - `.env` and `.env.test` exist and contain required variables

2. **Prisma Schema** - `prisma/schema.prisma` is valid

3. **Controllers** - All controllers have matching services

4. **Services** - All services are properly registered in modules

5. **DTOs** - All DTOs have validation decorators (`class-validator`)

DTO Validation Example

```typescript

import { IsString, IsEmail, MinLength } from 'class-validator';

import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {

@ApiProperty()

@IsString()

@MinLength(2)

name: string;

@ApiProperty()

@IsEmail()

email: string;

}

```

Automation Workflows

Enabled Automations

1. **Auto-generate types** (`autoGenerateTypes: true`)

- Run `prisma generate` after schema changes

- Update TypeScript types from Prisma models

2. **Auto-update docs** (`autoUpdateDocs: true`)

- Regenerate Swagger/OpenAPI spec when controllers change

- Validate all endpoints are documented

3. **Block on test failure** (`blockOnTestFail: true`)

- Prevent code generation if tests would fail

- Run test suite before applying changes

Disabled Automations

1. **Auto-migrate database** (`autoMigrateDb: false`)

- Require explicit migration commands

- Prevent accidental schema changes

Workflow for New Features

When creating a new feature:

1. **Validate project structure** - Check all required files exist

2. **Create module directory** - `src/modules/<feature-name>/`

3. **Generate scaffolds**:

- `<feature>.controller.ts`

- `<feature>.service.ts`

- `<feature>.module.ts`

- `<feature>.spec.ts` (unit tests)

- `dto/` directory with DTOs

4. **Update Prisma schema** if database changes needed

5. **Run `prisma generate`** to update types

6. **Add Swagger decorators** to controller and DTOs

7. **Write tests** - minimum 80% coverage

8. **Validate** all five validation rules pass

9. **Update documentation** - regenerate OpenAPI spec

Error Handling

All errors must:

**Example:**

```typescript

if (!user) {

throw new NotFoundException(`User with ID ${id} not found`);

}

```

Constraints