# Design and Review NestJS Architecture

Unclear module boundaries make NestJS changes harder to test and coordinate. This skill guides evidence-based architecture decisions, explicit ownership, and incremental boundary repairs.

## Install

```bash
npx skillstore add amirtaherkhani/nestjs-architecture-principles
```

## Metadata

- Status: approved
- Slug: amirtaherkhani-nestjs-architecture-principles
- Version: 1.1.2
- Author version: 1.1.2
- Skillstore revision: r1
- Version status: valid
- Tree hash: 4af59f36093980615450618f5344063c94b2b93767c91925ef306592672ce137
- Author: amirtaherkhani
- GitHub username: amirtaherkhani
- License: MIT
- Repository: https://github.com/amirtaherkhani/nestjs-skills/tree/b82cdf0312e1c1bcaf871bb67473e91b2a1befad/skills/nestjs-architecture-principles
- Ref: c97a1862d1bc82763903ee068cd15acab35d638c
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: env\_access, external\_commands
- Quality score: 79
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/amirtaherkhani-nestjs-architecture-principles
- Manifest: https://skillstore.pages.dev/api/skills/amirtaherkhani-nestjs-architecture-principles/manifest

## Capabilities

- Guide architecture selection across feature modules, selective layering, hexagonal boundaries, CQRS, and independently deployed services.
- Review module imports, provider exports, dependency direction, and circular dependencies against repository evidence.
- Define application-owned ports, runtime provider tokens, adapter wiring, and appropriate provider lifetimes.
- Assess data ownership, transaction scope, migration compatibility, and reliable event publication boundaries.
- Produce architecture reviews with evidence, impact, minimal remedies, migration steps, and validation checks.
- Evaluate service extraction using deployment, ownership, scaling, data, and failure requirements.

## Use Cases

- Plan a new backend: Choose cohesive feature modules, public operations, and data owners before adding layers or separate services.
- Review an existing system: Identify cross-feature write leaks, broad exports, and dependency cycles, then recommend focused repairs with regression checks.
- Evaluate service extraction: Compare worker scaling with business-service extraction and define ownership, contracts, consistency, and operational requirements.

## Prompt Templates

### Plan feature modules

```
Design a NestJS order-management API for one team and one deployment. Recommend module boundaries, public APIs, data ownership, and validation.
```

### Review module boundaries

```
Review this NestJS repository without editing files. Map imports and exports, identify ownership violations, and report evidence, impact, minimal remedies, and tests.
```

### Plan a cycle repair

```
OrdersModule and PaymentsModule depend on each other. Trace the workflow and propose an incremental cycle repair that preserves contracts and required consistency.
```

### Evaluate distributed boundaries

```
Evaluate extracting reporting from our NestJS monolith. Compare worker deployment and microservices using ownership, scaling, data, failure, contracts, migration, and validation.
```

## Limitations

- Targets NestJS backends rather than frontend applications or unrelated backend frameworks.
- Provides instructions and reference examples, not a standalone architecture scanner or migration runner.
- Requires repository access and concrete requirements to support evidence-based recommendations.
- Does not prove runtime correctness, database behavior, or performance without relevant tests and measurements.

## Best Practices

- Inspect installed versions, module wiring, callers, tests, and concrete change pressures before choosing an architecture.
- Assign clear capability and write ownership, then add only boundaries justified by current requirements.
- Make changes incrementally, preserve public contracts, and verify boundaries with existing lint, module, integration, or contract tests.

## Anti Patterns

- Introduce CQRS, microservices, or strict layering only to match a preferred diagram.
- Export every provider or let features directly write another capability's tables.
- Treat forwardRef as the default cycle repair or create interfaces for every stable local helper.

## Security Audit

- Audited at: 2026-10-04T20:29:35.104\+00:00
- Summary: All 19 static findings are false positives involving architecture guidance, Markdown formatting, or illustrative configuration access. The payment example passes configuration to an adapter without logging or exporting credentials. No evidence found of malicious intent, prompt injection, reconnaissance, or shell execution in the reviewed files.

## Stats

- Views: 0
- Downloads: 0
- Favorites: 0
- Popularity score: 0