# NestJS Structure Standard

Use this standard for NestJS implementation chunks.

For backend, Runtime Node, GraphQL, Socket.IO, service-status, and Runtime
bridge architecture boundaries, also apply
`ai/standards/backend-node-nestjs-architecture.md`.

## Source Guidance

This project follows current NestJS modular architecture: feature behavior is
organized through modules, injected providers/services, resolvers/controllers,
and code-first GraphQL types/inputs.

Before NestJS, Node.js, TypeScript, or Socket.IO implementation work, consult
the local pinned references in `ai/references/backend-frameworks/` and the
usage rules in `ai/references/framework-reference-policy.md`. Browse official
docs only when the pinned reference is missing, stale for the installed version,
or the chunk explicitly asks for current/latest documentation.

## Module And Provider Boundaries

- Feature logic belongs in focused services, resolvers, modules, types, and inputs.
- Feature modules should use predictable subdirectories where useful: `services/`, `resolvers/`, `models/`, `inputs/`, `types/`, `guards/`, and `decorators/`.
- Injectable services should live under feature-local `services/` directories when a feature has more than a trivial module file.
- GraphQL resolvers should live under feature-local `resolvers/` directories.
- GraphQL code-first object types/models and inputs should be separated from resolver/service implementation in `models/` and `inputs/` directories where practical.
- Root module/app files stay thin and explicit.
- Avoid large root files and backend dumping grounds.
- Do not bypass Nest dependency injection.
- Do not construct Prisma clients inside feature services.
- Use `PrismaService` for database access.
- Avoid giant shared service dumping grounds; shared providers should represent real shared behavior.
- Keep feature boundaries clear enough that tests can target services/resolvers directly.

## GraphQL

- Use NestJS GraphQL code-first decorators for types, inputs, queries, and mutations.
- Keep GraphQL inputs/models close to the feature that owns them.
- Resolvers should translate GraphQL operations to service calls and avoid owning complex business logic.
- Services should own business rules, authorization-sensitive data operations, and integration with Prisma or other providers.

## Tests

- Add focused service/resolver tests when backend behavior changes.
- Keep e2e/API tests for GraphQL/auth/database boundaries and regression-sensitive flows.
- Regenerate committed GraphQL schema artifacts when GraphQL behavior changes, and avoid committing generated churn when behavior did not change.