---
name: nestjs-architect
description: "Modular NestJS apps: DI, decorators, guards, GraphQL or REST, Prisma — enterprise Node done well. Scaffolds NestJS modules with proper dependency injection, guards/interceptors, OpenAPI generation, and Prisma integration."
license: MIT
---

# NestJS Architect

NestJS Architect helps you build and extend NestJS backends the way the framework intends — feature modules wired through dependency injection, request handling layered with guards and interceptors, and a data layer backed by Prisma. It's aimed at TypeScript developers building production APIs who want consistent structure across REST and GraphQL surfaces rather than ad-hoc controllers glued together by hand.

## When to use it

- Standing up a new service and you want a clean module boundary (`UsersModule`, `AuthModule`) instead of dumping everything in `AppModule`.
- Adding a resource end to end: entity, DTOs with validation, service, and controller or resolver.
- Introducing cross-cutting concerns — JWT auth guards, role-based `CanActivate` checks, logging or transform interceptors, exception filters.
- Wiring Prisma into the DI container and exposing a typed `PrismaService`.
- Generating OpenAPI/Swagger docs from existing decorators, or designing a code-first GraphQL schema.

## What it does

It scaffolds against the real Nest building blocks. Modules use `@Module({ imports, controllers, providers, exports })`; providers are injected via constructor parameters and `@Injectable()`. For HTTP it generates controllers with `@Controller()`, route decorators (`@Get`, `@Post`, `@Param`, `@Body`), and DTOs validated by `class-validator` decorators plus a global `ValidationPipe`. Guards implement `CanActivate`; interceptors implement `NestInterceptor`; filters use `@Catch()`.

For GraphQL it favors the code-first approach with `@ObjectType`, `@Resolver`, `@Query`, `@Mutation`, and `@Field`, emitting `schema.gql`. OpenAPI generation uses `@nestjs/swagger` (`DocumentBuilder`, `SwaggerModule.setup`) and `@ApiProperty`. Prisma integration produces a `PrismaService extends PrismaClient` that hooks `onModuleInit`, registered in a shared `PrismaModule`.

## Example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/nestjs-architect/SKILL.md https://claudeskil.com/skills/nestjs-architect/SKILL.md

# then, in your project:
"Add a billing module with a REST controller, a Prisma-backed
service, a JWT auth guard, and Swagger docs for the endpoints."
```

Resulting service sketch:

```ts
@Injectable()
export class BillingService {
  constructor(private readonly prisma: PrismaService) {}

  findAll() {
    return this.prisma.invoice.findMany();
  }
}
```

## Tips & gotchas

- Providers are singleton-scoped by default. Only reach for `Scope.REQUEST` when you truly need per-request state — it forces the whole resolution chain to become request-scoped and hurts throughput.
- Register `ValidationPipe` globally with `whitelist: true` and `transform: true`, otherwise extra payload fields slip through and DTO types stay plain objects.
- A guard that depends on another provider must live in a module that can resolve it; export shared providers or use `APP_GUARD` for app-wide guards.
- Run `prisma generate` after schema changes so the injected client stays typed; the skill won't migrate your database for you.

## FAQ

**REST or GraphQL — can I mix them?** Yes. Nest supports both in one app; the skill keeps resolvers and controllers in their own modules so they share the same services.

**Does it run migrations?** No. It generates code and Prisma schema/service wiring; you still run `prisma migrate dev` yourself.

**Code-first or schema-first GraphQL?** It defaults to code-first with decorators, but can target an existing `.graphql` SDL if you prefer schema-first.