v-checha/nestjs-template

This system is a secure, clean-architecture backend service built on NestJS that manages user authentication, role-based access control, and file storage. It implements a CQRS pattern to handle complex domain logic for users, roles, and permissions, supported by a Prisma/PostgreSQL data layer. The application provides comprehensive REST APIs for public authentication flows, user profile management, and administrative operations, all protected by JWT and permission guards.

New CQRS query handlers have been introduced to support admin operations and file storage retrieval. Admin users can now check system health and fetch user details via dedicated query handlers. For file storage, the application now supports retrieving all files with pagination, fetching a specific file with permission checks, and listing files for a specific user. These changes implement the application layer for these capabilities using the CQRS pattern.

src/application/queries/storage · high confidence

The auth module now includes an EmailProvider that sends verification, password reset, and welcome emails using Nodemailer, and a TokenProvider that generates JWT access and refresh tokens. These providers enable the application to handle user verification, password recovery, and authentication token management.

src/presentation/modules/auth/providers · high confidence

New CQRS query handlers have been introduced for retrieving health status, specifically for database health, general health, liveness, and readiness checks. Each handler delegates to the corresponding method in the HealthService, enabling the application to expose distinct health check endpoints via the CQRS pattern.

src/application/queries/health · high confidence

New query handlers have been introduced for fetching role data: GetRoleQuery retrieves a single role by ID, and GetRolesQuery retrieves all roles. Both handlers use the RoleMapper to convert domain entities into response DTOs, implementing the CQRS pattern for role retrieval.

src/application/queries/role · medium confidence

A new JWT authentication strategy has been introduced to handle bearer token validation. This strategy verifies the token's signature, checks if the user still exists and is active, and injects the full user entity into the request object, ensuring that downstream components like permission guards have access to all user methods and properties.

src/presentation/modules/auth/strategies · high confidence

The src/core/services directory now includes new implementations for authentication (AuthService with OTP, 2FA, and refresh tokens), user management (UserService with password handling and role assignment), role and permission management (RoleService), user authorization logic (UserAuthorizationService using specifications), health monitoring (HealthService with readiness/liveness probes), and storage abstraction (StorageService). These services introduce the underlying business logic and domain interactions for the application's core features.

src/core/services · high confidence

The Prisma schema and initial migration have been introduced, defining models for User, Role, Permission, Otp, RefreshToken, EmailVerification, PasswordReset, and File. The seed script populates default roles (admin, user) and a comprehensive set of permissions (user, role, storage, audit) with specific access levels, establishing the foundation for role-based access control and file management.

prisma · high confidence

Added new exception filters in the presentation layer to standardize error handling and logging. The AllExceptionsFilter provides a fallback for all unhandled exceptions, logging structured error details and returning a consistent JSON response. The DomainExceptionsFilter specifically handles DomainException instances, ensuring that domain-level errors are also logged and formatted consistently. Both filters integrate with the LoggerService to capture request context and user information.

src/presentation/filters · high confidence

Introduced two new interceptors in the presentation layer: a LoggingInterceptor that records request and response details (including processing time) via a LoggerService, and a TransformInterceptor that standardizes API responses into a consistent envelope format (status code, data, timestamp, and optional message) while preserving the Accept-Language header for i18n support.

src/presentation/interceptors · high confidence

New repository interfaces have been introduced to define the data access layer for key domain entities, including User, Role, Permission, PasswordReset, OTP, EmailVerification, RefreshToken, and File. These interfaces specify the contract for data operations such as find, create, update, and delete, enabling the implementation of specific storage backends (e.g., Prisma/PostgreSQL) while keeping the core logic decoupled from the underlying database technology.

src/core/repositories · high confidence

The user profile module now exposes a new REST API for managing the current user's profile. Users can retrieve their profile, update their name and email, change their password, and verify their current password via dedicated endpoints. These operations are protected by JWT authentication and a permissions guard, ensuring that only authenticated and authorized users can access or modify their own data.

src/presentation/modules/user · high confidence

The application now initializes with a comprehensive set of global middleware and providers. Security is enforced via Helmet headers, CORS configuration, and a global JWT authentication guard. Input validation is handled by a global ValidationPipe that whitelists and transforms data. The framework supports internationalization (i18n) with generated translation types and language headers. Additionally, Swagger documentation is configured with basic authentication protection in production environments, and a global exception filter ensures consistent error handling.

src · high confidence

The project is initialized with a comprehensive set of configuration files and documentation that define the development environment and project structure. This includes an .editorconfig for consistent coding styles, .env.example with all required environment variables (database, JWT, SMTP, MinIO, Swagger), and linting/formatting tools (Prettier, ESLint, lint-staged). The repository also contains a Dockerfile and docker-compose.yml for containerized development with PostgreSQL, MailHog, and MinIO. Documentation files (README.md, CONTRIBUTING.md, README-ADMIN.md) and a LICENSE file are added to guide users on setup, architecture, and contribution.

(repo-wide) · high confidence

A new \domain-exceptions.ts\ file has been added to \src/core/exceptions\, establishing a structured exception hierarchy for the application. This includes a base \DomainException\ class and specific subclasses for entity not found, conflicts, invalid input, authentication, OTP, throttling, user, role, authentication, file, validation, and health check scenarios. This change provides a consistent way to handle and report domain-level errors across the system.

src/core/exceptions · high confidence

This change adds a new \src/application/dtos\ module that defines the data transfer objects for the application's API contracts. It introduces request DTOs for authentication (login, register, password reset, OTP verification), user management (update user, change password, assign roles), role management (create/update roles), and file access updates. It also defines response DTOs for authentication tokens, user details, role details, permissions, file metadata, and system health/liveness/readiness checks. These DTOs standardize input validation and API documentation for the backend.

src/application/dtos · high confidence

The core module now includes new domain entities for managing users, roles, and permissions, alongside a specification pattern to enforce business rules. The \User\ entity supports two-factor authentication, account activation, and role assignment. The \Role\ entity manages permissions and enforces rules like preventing deletion of default roles. The \Permission\ entity tracks resource-action pairs. New specification classes (\ActiveUserSpecification\, \CanAssignRoleSpecification\, \CanAssignPermissionToRoleSpecification\, etc.) encapsulate validation logic for user and role states, ensuring that actions like assigning roles or permissions adhere to system constraints.

src/core/entities · high confidence

The application now includes a comprehensive set of CQRS command handlers for authentication (login, register, logout, password reset, email verification, 2FA setup/verification, OTP generation/verification, and token refresh), admin user management (update user, change password), role and permission management (create, update, delete roles; assign/remove permissions), and file storage (upload, delete, and update file access). These commands implement the core user-facing flows for signing up, logging in, managing account security, and handling file uploads and permissions.

src/application/commands · high confidence

The admin panel has been rebuilt using the Refine framework, providing a complete set of pages for managing users and roles, including list, show, create, and edit views. Users can now be created, edited, and activated or deactivated directly from the admin interface. Role management includes creating and editing roles with granular permission assignments via a transfer component. Additionally, a new Health Monitor page displays the status of the database, API, and overall system health with auto-refreshing status indicators.

admin · high confidence

The admin module now exposes a complete set of RESTful endpoints for managing users, roles, and system health. Administrators can log in, refresh tokens, and perform CRUD operations on users and roles (create, update, delete, assign permissions). The admin dashboard provides statistics, while separate endpoints expose system, database, readiness, and liveness health checks. All admin endpoints require admin privileges, enforced via guards and decorators, ensuring that only authorized users can access sensitive administrative functions.

src/presentation/modules/admin · high confidence

A new \AuthModule\ has been introduced to the application, providing a comprehensive set of authentication and account management endpoints. The \AuthController\ exposes routes for user registration, login, OTP verification, token refresh, and logout. It also includes endpoints for email verification (sending and verifying codes), password reset requests, and retrieving the current user's profile information. The module integrates with the CQRS pattern via command handlers for each operation, manages JWT strategies, and wires up various repositories and providers to support these features.

src/presentation/modules/auth · high confidence

Added three new NestJS guards in the presentation layer: JwtAuthGuard for standard JWT-based authentication with public route support, PermissionsGuard for role- and resource-based authorization checks, and ThrottlerGuard for configurable rate limiting with IP/user identification and header injection. These guards introduce new request-handling behaviors for security and access control.

src/presentation/guards · high confidence

Added new decorators to the shared layer to support enhanced security and user experience features. The \RequiresAdmin\, \RequiresSensitive\, and \RequiresResourceAction\ decorators enable fine-grained permission checks via the \PermissionsGuard\. The \Public\ decorator allows endpoints to bypass authentication requirements. The \CurrentUser\ decorator simplifies retrieving the authenticated user from the request context. Additionally, \Throttle\ and \SkipThrottle\ decorators provide route-level control over rate limiting behavior.

src/shared/decorators · high confidence

Added a suite of value objects and immutable collections to the core domain layer. This includes \PermissionsCollection\ and \RolesCollection\ for managing domain entities, along with specific value objects for \Email\, \Password\, \Token\, \VerificationCode\, and various IDs (\UserId\, \RoleId\, \PermissionId\, \FileId\). The update also introduces \ThrottleLimit\ for rate limiting configuration, \ResourceAction\ for defining access rules, and \Name\ types for user identity. These components provide strict validation and business logic for authentication, authorization, and user data.

src/core/value-objects · high confidence

The application now includes dedicated infrastructure modules for configuration management, Prisma database integration, internationalization (i18n) with English and Arabic translations, structured logging, and repository implementations for user, role, permission, OTP, email verification, password reset, and file storage. These changes provide the underlying data access and configuration layers required for the application's core features.

src/infrastructure · high confidence

Added new mapper classes in the application layer to convert domain entities into specific response DTOs. The FileMapper handles public and private file URL generation, the RoleMapper maps roles and permissions to detail responses, and the UserMapper converts user entities into base, detail, and auth responses.

src/application/mappers · high confidence

A new storage module has been introduced, providing endpoints to upload, retrieve, list, delete, and update access permissions for files. The controller exposes RESTful routes for these operations, enforcing role-based access control via a permissions guard and JWT authentication, while delegating business logic to CQRS command and query handlers.

src/presentation/modules/storage · high confidence

A new file, src/shared/constants/tokens.ts, has been added to define Symbol-based injection tokens for dependency injection. This includes repository tokens for User, Role, Permission, RefreshToken, OTP, EmailVerification, PasswordReset, and File repositories, as well as a token for the ThrottlerService.

src/shared/constants · high confidence

New CQRS query handlers have been introduced to fetch user and permission data. The \GetUserQuery\ retrieves a single user by ID, throwing a \NotFoundException\ if the user does not exist, while the \GetUsersQuery\ supports paginated, filtered retrieval of users with search capabilities. Additionally, a \GetPermissionsQuery\ was added to fetch all permissions. All handlers utilize a \UserMapper\ to convert domain entities into response DTOs, aligning with the project's clean architecture and CQRS patterns.

src/application/queries/user · high confidence

The repository now enforces code quality and testing automatically. A pre-commit hook runs lint-staged to check staged files, and a pre-push hook executes the npm test suite, ensuring that code quality checks and tests run before changes are committed or pushed.

.husky · high confidence

Added authentication and user test fixtures; Added end-to-end tests for authentication, user, and role management; Added mock implementations for testing.

The admin interface and the NestJS backend have been updated to use newer versions of their respective dependencies. The admin package now relies on Refine v5.47.0, Ant Design v5.27.4, and React 18.3.1. The main NestJS template has been upgraded to NestJS v11.0.x, Prisma v6.18.0, and various other libraries including AWS SDK, Passport, and testing tools.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 61 → 64 (+2.9)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 80 → 83 (+2.6)
• Architecture 56 → 64 (+8.3)
• Maturity 80 → 74 (-6.3)
• Readiness 56 → 57 (+1.4)
• Security 66 → 77 (+10.5)

• Coverage not included — suite not readable by the collector
• Critical CVE: [GHSA redacted] (package-lock.json)
• Critical CVE: [GHSA redacted] (admin/package-lock.json)
• Critical CVE: [GHSA redacted] (package-lock.json)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• …and 52 more

• Critical CVE: [GHSA redacted] (package-lock.json)
• Critical CVE: [GHSA redacted] (admin/package-lock.json)
• Critical CVE: [GHSA redacted] (package-lock.json)
• Dependency advisory scan runs only on code events
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• FunctionTooLong: App.App (admin/src/App.tsx)
• FunctionTooLong: edit.RoleEdit (admin/src/pages/roles/edit.tsx)
• FunctionTooLong: edit.UserEdit (admin/src/pages/users/edit.tsx)
• FunctionTooLong: index.HealthMonitor (admin/src/pages/health/index.tsx)
• FunctionTooLong: list.UserList (admin/src/pages/users/list.tsx)
• FunctionTooLong: show.UserShow (admin/src/pages/users/show.tsx)
• FunctionTooLong: verify-email.VerifyEmail (admin/src/pages/auth/verify-email.tsx)
• High CVE: [CVE redacted] (package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (admin/package-lock.json)
• …and 143 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

v-checha/nestjs-template was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.