luizomf/clean-architecture-api-boilerplate

This system is a Node.js API built on Clean Architecture principles, providing user management and authentication services. It supports user registration, profile updates, and account deletion, alongside a robust security model featuring JWT-based authentication and role-based access control. The application manages access tokens and refresh tokens to maintain secure, long-lived sessions.

A new RefreshTokenController has been introduced in the presentation layer to handle token refresh requests. The controller validates the incoming request, ensuring the token is present and is a string, then sanitizes the input before passing it to the RefreshTokenUseCase. The implementation includes a corresponding test suite that verifies validation errors for missing or invalid tokens and confirms the controller correctly delegates to the use case and presenter.

src/presentation/controllers/token · high confidence

A new SignInController is introduced to handle sign-in requests, validating that the email and password are present and are strings, throwing UnauthorizedError for empty or invalid inputs. The controller sanitizes the email and password using a generic string sanitizer, passes the sanitized values to the sign-in use case, and returns the resulting token and refresh token via a response presenter.

src/presentation/controllers/sign-in · high confidence

A new file, misc/Insomnia\_2020-12-09, has been added to the repository. This file contains an Insomnia workspace export for a 'Clean Architecture' project, including request groups and environment variables for endpoints such as /users and /sign-in, enabling users to import this configuration directly into the Insomnia tool for API testing.

misc · high confidence

Users can now be retrieved with their associated roles via the new \findOneWithRoles\ method on the SQL user repository. This change introduces a new \UserWithRoles\ model and a \mapUserFields\ helper to aggregate multiple role rows into a single user object containing a \roles\ array. The implementation includes the \UserSqlRepository\ class implementing standard CRUD operations and the new role-enriched query, along with comprehensive unit tests for the repository and the field mapping logic.

src/infrastructure/repositories/user/sql · high confidence

New Knex seed files (01\_users, 02\_roles, 03\_user\_roles) were added to the infrastructure layer. These scripts populate the database with an initial admin user ([e-mail redacted]) and the corresponding 'admin' and 'public' roles, establishing the foundational data for the application's security model.

src/infrastructure/knex/seeds · high confidence

New helper functions were added to the common utilities library: \createFutureDate\ and \formatDateTime\ for date manipulation and formatting, \zeroPadLeft\ for number formatting, \objectKeyExists\ and \removeObjectEmptyKeys\ for object manipulation, and \isString\ for type checking. Each utility is accompanied by its corresponding test suite to ensure correct behavior.

src/common/helpers · high confidence

A new RefreshToken use case has been introduced to handle token refresh logic. This implementation validates the incoming refresh token, verifies it via the JWT adapter, checks the token's existence in the repository, and upon success, generates and stores a new access and refresh token pair. The change is accompanied by comprehensive unit tests covering validation, error handling, and successful flow scenarios.

src/application/use-cases/token · high confidence

A new interface for refreshing authentication tokens has been introduced in the domain layer. This adds the capability to request new access tokens using a refresh token, returning a sign-in response model.

src/domain/use-cases/token · high confidence

New repository interfaces have been introduced to support token management, including creating tokens, and finding or deleting tokens by ID, token string, or user ID.

src/application/ports/repositories/token · medium confidence

The repository is initialized with a Clean Architecture boilerplate for a Node.js/TypeScript API. This includes the core source code organized into domain, application, adapters, infrastructure, and main layers, along with configuration files for ESLint, Jest, Husky, and environment variables. The setup supports PostgreSQL via Knex and includes authentication features such as JWT tokens, refresh tokens, and role-based authorization for user routes.

(repo-wide) · high confidence

A new \JwtToken\ interface has been added to the application's security ports, defining contracts for signing access and refresh tokens as well as verifying JWTs. This establishes the abstraction for token management within the application layer.

src/application/ports/security · high confidence

Added new Knex configuration files (connection.ts, knexfile.ts) that establish database connections for test, development, and production environments. The configuration supports SQLite for test and development, and PostgreSQL for production, with environment variables for database credentials and settings.

src/infrastructure/knex · high confidence

A new Middleware interface is added to define the contract for middleware components, specifically requiring a handleRequest method that accepts a MiddlewareRequestModel. This establishes a standardized way for middlewares to process incoming requests within the application's port layer.

src/application/ports/middlewares · high confidence

The application now provides factory functions to instantiate controllers and middleware, centralizing dependency injection for the sign-in, user management, and authentication flows. A new refresh token route has been added, enabling users to obtain new access tokens without re-authenticating. Additionally, the user update endpoint now requires an authorization token, and the user routes have been refactored to support admin and owner roles for access control.

src/main · medium confidence

The application layer now defines a generic \RequestModel\ interface that standardizes request data with body, params, query, and headers. A new \MiddlewareRequestModel\ interface extends this base to allow middleware to optionally specify an HTTP method. This provides a consistent structure for handling requests and enables middleware-specific request handling.

src/application/ports/requests · high confidence

A new GenericStringSanitizerAdapter has been added to the common adapters layer. This adapter implements the Sanitizer port, providing a generic string sanitization capability that cleans HTML tags from input strings. It handles undefined values by returning an empty string and throws a SanitizerError for non-string inputs.

src/common/adapters/sanitizers · high confidence

Added controllers for creating, finding, updating, and deleting users, each implementing request validation and input sanitization. The CreateUserController and UpdateUserController sanitize string inputs via a generic string sanitizer and validate required fields (body, params) before invoking use cases. The FindUserByIdController and DeleteUserByIdController validate the presence of the user ID parameter. The FindAllUsersController handles optional query parameters for ordering, limiting, and offsetting results. Each controller returns standardized HTTP response models with appropriate status codes (201, 200, 204) and includes corresponding unit tests.

src/presentation/controllers/user · high confidence

A new Sanitizer port interface has been introduced, defining a generic contract for sanitization operations that accept an input of type I and return an output of type O.

src/application/ports/sanitizers · high confidence

The interfaces for user-related use cases (sign-in, create, delete, find-all, update, and find-by-id) have been moved from the application layer to the domain layer. This reorganization clarifies that these interfaces are part of the core domain logic rather than just application ports, providing a more consistent architectural boundary for these capabilities.

src/domain/use-cases/sign-in, src/domain/use-cases/user · high confidence

The Express application now enforces rate limiting on the /users, /sign-in, and /refresh-token routes using a 3-minute window allowing 100 requests. Additionally, the server now applies the helmet middleware to set security-related HTTP headers, and the example middleware has been removed from the /users route.

src/infrastructure/express/setup · high confidence

The sign-in validation has been refactored into a composite validator that enforces email and password requirements for the sign-in request model. The previous separate email validation test suite has been replaced with tests for the new SignInValidation class, which now validates that the email and password fields are present and that the email format is correct.

src/application/validation/sign-in · high confidence

The Controller interface has been updated so that its generic type parameter defaults to 'unknown' if not explicitly specified. This change ensures that controllers without a specific response type default to a generic 'unknown' type, providing a safer default behavior for untyped controllers.

src/application/ports/controllers · high confidence

The application's database schema is now defined via Knex migrations, introducing tables for user accounts, authentication tokens, and a role-based access control system. The 'users' table stores account details and a password hash, while the 'tokens' table manages refresh tokens linked to users. Additionally, a 'roles' table and a 'user\_roles' junction table are introduced to support assigning multiple roles to users, enabling granular permission management.

src/infrastructure/knex/migrations · high confidence

The domain layer has been reorganized to support token refresh functionality and improved user-role associations. New models for authentication requests and responses (SignInRequestModel, SignInResponseModel) and token management (Token, SignedToken, TokenRequestModel) have been introduced. The User model now includes an optional roles field to associate users with roles, and the Role model has been added to the domain. Additionally, user request models have been moved from application ports to the domain models layer, with types renamed to reflect their new location and purpose.

src/domain · medium confidence

The \expressMiddlewareAdapter\ utility was removed, and the Express application instance is now exported for external use. Additionally, the server startup logic was updated to conditionally start the HTTP listener based on the \NODE\_ENV\ environment variable, preventing the server from automatically listening during test execution.

src/infrastructure/express · high confidence

A new default user repository implementation has been added, providing a concrete SQL-based repository that implements all user-related repository interfaces (create, find by ID/email, delete, update, and find with roles). This change simplifies the repository layer by providing a single, easily swappable implementation for user data access.

src/infrastructure/repositories/user · high confidence

The application now includes dedicated error classes for DateTime, Repository, Sanitizer, and Unauthorized scenarios, each extending the base DefaultApplicationError with specific HTTP status codes (500, 400, or 401). Additionally, import paths for the base error class and the ResponseModel have been updated to reflect the new directory structure.

src/application/errors · high confidence

The security adapter now supports both access and refresh tokens, with expiration durations for each being configurable via environment variables (JWT\_SECRET\_EXPIRATION\_SECS and JWT\_SECRET\_REFRESH\_EXPIRATION\_SECS). This allows the system to issue and verify refresh tokens in addition to standard access tokens, providing a mechanism for session management beyond the default 10-minute access token lifetime.

src/common/adapters/security · high confidence

Added new middlewares to handle user authentication and authorization. The \IsAuthenticatedMiddleware\ validates the user's JWT token and attaches the user ID to the request headers. The \LoggedUserIsTargetUserMiddleware\ ensures that a user can only access or modify their own account, unless they have the 'admin' role. Both middlewares now use a \MiddlewareRequestModel\ for the request payload.

src/presentation/middlewares · medium confidence

The Express adapter layer has been reorganized to improve separation of concerns. A new \expressMiddlewareAdapter\ has been introduced to handle middleware execution, wrapping the application's \Middleware\ interface to map Express request objects to the domain model. Additionally, the \expressRouteAdapter\ was moved from the \utils\ directory to \adapters\ and updated to include request headers in the controller input, ensuring consistent data flow for both routes and middleware.

src/infrastructure/express/adapters · medium confidence

The string validation logic has been refactored to specifically handle non-empty string values, moving from a generic request body validation to a focused validator that throws a 400 error if the input is empty or not a string. This change is accompanied by new unit tests that verify the validator correctly accepts non-empty strings and rejects empty ones with a RequestValidationError.

src/application/validation/common · medium confidence

Validation logic for user operations (Create, Update, FindAll) has been moved from the adapters layer to the application layer. The composite validation classes have been renamed (e.g., UserValidationComposite to UserCompositeValidation) and restructured to use specific leaf validators (UserRequiredFieldsValidation, UserEmailValidation, etc.) that now reside in the application/validation/user directory. This change improves separation of concerns by keeping validation rules within the application layer rather than the adapters layer.

src/application/validation/user · high confidence

The generic RequestModel interface, which previously provided a standard structure for request bodies, parameters, and queries, has been removed from the application ports. This change eliminates the shared request model abstraction, requiring consumers to define their own request shapes or use alternative patterns for handling HTTP request data.

src/application/ports/request · medium confidence

The console application scripts for creating a user (create-user.ts) and finding a user by ID (find-user-by-id.ts) have been removed. These files previously served as simulation scripts to test controller factories directly without an HTTP server. Their removal indicates a shift away from these specific console-based testing or demonstration scripts.

src/infrastructure/console-application · high confidence

The in-memory user repository implementation and its associated test suite have been removed from the codebase. This includes the \InMemoryUserRepository\ class, its factory, and the corresponding unit tests. This change eliminates the in-memory data storage mechanism for user data, likely as part of a shift towards persistent storage solutions.

src/application/ports/user, src/infrastructure/repositories/testing-repository · high confidence

The factory for the find-user-by-id controller has been removed from the codebase. This change eliminates the use of an in-memory user repository for this specific controller, likely as part of a broader shift towards using a SQL-based repository (Knex) for user data access. Users will no longer see the in-memory implementation for finding users by ID, which may affect local development or testing environments that relied on the previous in-memory setup.

src/infrastructure/factories · medium confidence

The \src/adapters\ directory has been refactored by removing the old user controller implementations (\CreateUserController\, \FindUserByIdController\) and their associated validation logic (including \CreatedUserPresenter\, \SuccessUserPresenter\, and various validation composites). This change removes the previous user request handling and response formatting code, likely to be replaced by a new main layer or updated controller structure.

src/adapters · high confidence

The \CreateUserRepository\ interface and its associated request model have been removed from the application's repository ports. This change eliminates the legacy repository definition, indicating a shift in how user creation is handled within the application layer.

src/application/ports/repositories · medium confidence

The generic response presenters have been renamed to response handlers (e.g., GenericCreatedPresenter to GenericCreatedResponse) and moved to the presentation/responses directory. This change aligns the naming with the underlying interface (ResponseHandler) and clarifies their role in the application's architecture.

src/presentation/responses · high confidence

The application's response handling interface has been renamed from 'Presenter' to 'ResponseHandler', and the associated model has been moved from the 'response' subdirectory to the 'responses' directory. This change clarifies the purpose of these components by aligning their names with their role in processing and returning responses, while also reorganizing the project structure for better clarity.

src/application/ports/responses · medium confidence

The repository port interfaces for user-related operations (create, delete, find-all, find-one-with-roles, update, find-by-email, and find-by-id) have been moved from the generic \src/application/ports/repositories/\ directory into a new \src/application/ports/repositories/user/\ subdirectory. This change groups all user-specific repository contracts together, improving code organization and making it easier to locate and maintain the interfaces that define how the application layer interacts with user data storage.

src/application/ports/repositories/user · high confidence

The email validator adapter and its associated test file have been moved from the common/validators directory to the common/adapters/validators directory. Additionally, the import path for the EmailValidator interface has been updated to reflect the new location of the validation ports.

src/common/adapters/validators · medium confidence

The email and validation-composite files have been moved from src/application/ports/validators to src/application/ports/validation. Additionally, the ValidationComposite class now accepts a generic type parameter T and its validate method signature has been updated to return Promise\<void\> \| never.

src/application/ports/validation · medium confidence

The token persistence layer now uses a SQL-based repository (TokenSqlRepository) that implements interfaces for finding tokens by token string, ID, and user ID, as well as creating and deleting tokens by user ID. This replaces any prior in-memory or default implementations, ensuring that token lookups filter out expired entries and that new tokens are created in a transaction that removes any existing tokens for the same user. A default repository instance is exported for dependency injection.

src/infrastructure/repositories/token · high confidence

The sign-in use case has been updated to return a response object containing both an access token and a refresh token, rather than just the access token. This change supports token refresh flows by persisting the refresh token in the database upon successful authentication.

src/application/use-cases/sign-in · high confidence

The user management routes have been refactored to enforce authentication and target-user validation on all endpoints except user creation. GET, PUT, and DELETE requests to /users/:id and /users now require a valid authorization token and verify that the logged-in user is the target of the request. Additionally, a new route has been added to allow users to delete their own account, and a new /refresh-token endpoint has been introduced to handle token refresh logic.

src/infrastructure/express/routes · high confidence

All user use cases (Create, Find, Update, Delete) now validate their inputs using a ValidationComposite before executing business logic. This ensures that invalid requests are rejected early with appropriate errors, improving data integrity and user feedback.

src/application/use-cases/user · high confidence

The project's Babel tooling has been upgraded to version 7.12.10, with associated dependencies like @babel/core, @babel/generator, and @babel/parser updated to their latest 7.12.x releases. Additionally, new production dependencies have been added: knex for SQL repository support, express-rate-limit and helmet for security and rate limiting, jsonwebtoken for authentication, and sanitize-html for input sanitization. Development dependencies have also been updated, including eslint, prettier, and typescript, while some packages were moved to devDependencies.

(dependencies) · high confidence

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

• CAI 55 → 55 (+0.7)
• Rubric changed (rubric-2026.08.18 → rubric-2026.08.19) — scores are not directly comparable.

• Code Health 96 → 96 (+0.5)
• Architecture 97 → 97 (+0.0)
• Maturity 62 → 62 (+0.0)
• Readiness 35 → 37 (+1.5)
• Security 63 → 63 (+0.0)
• Domain Modelling 100 → 100 (+0.0)

• Critical CVE: [GHSA redacted] (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] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• The Clean Architecture Layers outline lists 'domain', 'application', 'adapters/presentation', 'infrastructure', 'main', and a visual guide but the visible text does not show how to create or use any of these components. (README.md)
• …and 1 more

• Critical CVE: [GHSA redacted] (package-lock.json)
• Critical CVE: [GHSA redacted] (package-lock.json)
• Critical CVE: [GHSA redacted] (package-lock.json)
• Critical CVE: [GHSA redacted] (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] (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] (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] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)

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

luizomf/clean-architecture-api-boilerplate 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.