talyssonoc/node-api-boilerplate

This system is a Node.js API boilerplate built with TypeScript, Clean Architecture, and Domain-Driven Design principles, serving as a scalable foundation for backend services. It provides core infrastructure features including a modular dependency injection system, centralized logging, event-driven communication, and standardized HTTP validation and error handling. The codebase demonstrates these capabilities through a concrete Article and Comment domain module, which implements CRUD operations, optimistic concurrency control, and MongoDB persistence. It also includes tooling for local development via Docker and remote interaction through a TCP-based REPL client.

17 changes.

The project underwent a major architectural overhaul to version 3, migrating from a JavaScript Express/Sequelize setup to a scalable TypeScript application based on Clean Architecture and Domain-Driven Design. This period involved removing all legacy code, including old controllers, infrastructure adapters, and test suites, while introducing new dependencies like Awilix for dependency injection and Docker for development environment consistency.

23 changes.

This period established the foundational Node.js API boilerplate, implementing a modular bootstrapping system, dependency injection, and centralized logging. It introduced the initial Article and Comment modules with DDD-aligned domain models, MongoDB persistence, and HTTP API endpoints, supported by comprehensive integration and unit tests.

A new REPL client tool has been added to the bin directory, allowing users to connect to a remote server via a TCP socket. The client defaults to connecting to localhost on port 2580, but supports custom host and port arguments. It pipes standard input to the server and server output to standard output, enabling interactive command-line usage.

bin · high confidence

A new file, containerAdapters.ts, has been added to the dependency injection library to provide a utility function, toContainerValues. This function simplifies the process of registering static values into an Awilix container by mapping an object of key-value pairs to the appropriate resolver format, reducing boilerplate for developers using the DI system.

_src/\lib/di · high confidence

This change introduces the HTTP interface layer for article management, adding specific request handlers for creating, finding, publishing, and deleting articles. The \CreateArticleHandler\ validates input using Joi and returns the new article ID. The \FindArticlesHandler\ supports filtering by title and date range, as well as pagination and sorting. The \PublishArticleHandler\ and \DeleteArticleHandler\ manage article state changes. These handlers are wired into an Express router in \index.ts\, exposing endpoints at \/articles\ (GET, POST) and \/articles/:articleId\ (PATCH for publish, DELETE). Swagger documentation is included for the list endpoint, and a DTO definition is provided in \definitions.yaml\.

src/article/interface/http · high confidence

This change introduces the foundational structure for the Node.js API boilerplate. It establishes the HTTP layer with an Express-based request handler that integrates with the Awilix dependency injection container, ensuring controllers receive their dependencies. A publish-subscribe event system is added, utilizing Node's EventEmitter for internal messaging, alongside a centralized configuration module that manages environment-specific settings for HTTP, Swagger, and MongoDB. The entry point initializes path aliases and boots the application, while a comprehensive HTTP status code enum standardizes response codes across the codebase.

src · high confidence

This change introduces the core infrastructure for managing comments on articles. It adds a new HTTP endpoint (POST /articles/:articleId/comments) that accepts a comment body and associates it with a specific article. The implementation follows a DDD structure, including domain models for comments (with active/deleted status and versioning), application use cases for creation, and a MongoDB-based repository layer that handles persistence, indexing, and optimistic concurrency control via version numbers.

src/comment · high confidence

This change introduces the core domain entities and persistence contract for the Article module. It defines the Article aggregate root with its lifecycle states (DRAFT, PUBLISHED, DELETED) and enforces business invariants such as non-empty titles and content. Additionally, it establishes the ArticleRepository interface, specifying the capability to retrieve articles by ID, laying the groundwork for data access within the domain layer.

src/article/domain · high confidence

The article module is now fully initialized with dependency injection, registering core use cases (create, delete, publish, find) and infrastructure components (MongoDB collection and repository) via a dedicated module definition. Additionally, an email listener has been added to react to article creation events, providing a basic notification hook when new articles are published.

src/article · high confidence

A new logger module has been added to the library, exporting a pre-configured Pino instance. This provides a consistent, centralized logging mechanism for the application, replacing any ad-hoc console logging or previous logging implementations that may have existed in this location.

_src/\lib/logger · high confidence

Added new event handling abstractions in src/\_lib/events, including Event, Publisher, Subscriber, EventConsumer, and EventProvider types and implementations. This introduces a structured way to publish and subscribe to events within the application, with support for configurable publisher/subscriber keys and event addressing.

_src/\lib/events · high confidence

A new TypeScript declaration file for the FindArticles query has been added to the application layer. This defines the structure for retrieving a paginated list of articles, including filtering by title and publication date range, and returning article details along with their associated comments.

src/article/application/query · high confidence

Developers can now use a standardized Docker Compose setup for local development, featuring a Node 16 Alpine base image with configured user permissions and npm global paths. The change introduces a suite of shell scripts in the dbin directory (such as build, run, shell, and npm) to simplify container interactions, including building images, executing commands within the dev service, and managing the local environment.

dbin, docker · high confidence

Added \makeValidator\ and \makePaginator\ helpers in \src/\_lib/http/validation\ to streamline request handling. The validator uses \types-joi\ to validate and type-safely extract body, params, query, headers, and cookies, throwing structured \ValidationError\s on failure. The paginator extracts and normalizes pagination (page, pageSize), sorting (field, direction), and filtering parameters from requests, applying defaults or throwing \BadRequestError\ when required fields are missing.

_src/\lib/http/validation · high confidence

The library introduces a new Application class that manages the application lifecycle through explicit states (IDLE, STARTING, STARTED, STOPPING, STOPPED) and allows registering hooks for each stage (onBooting, onReady, onRunning, onDisposing). A Context system is added to bootstrap modules, where modules can return a disposal hook that is automatically registered for the onDisposing lifecycle phase. The system also includes utilities for environment configuration, ID generation, MongoDB collection initialization, and basic DDD/CQRS type definitions.

_src/\lib · high confidence

Added three new application-layer use cases for managing articles: CreateArticle, DeleteArticle, and PublishArticle. The CreateArticle use case now integrates with the pub/sub system to enqueue an ArticleCreatedEvent upon successful creation. The PublishArticle use case includes validation to prevent republishing an already published article and logs the action via a provided logger. The DeleteArticle use case implements soft deletion by marking articles as deleted rather than removing them.

src/article/application/useCases · high confidence

The shared kernel now introduces a structured approach to error handling and domain identification. A new \BusinessError\ type allows domain logic to raise specific, typed errors with codes and messages. These errors, along with standard library errors like \ValidationError\, \NotFoundError\, and \UnauthorizedError\, are mapped to appropriate HTTP status codes and response bodies via the new \ErrorConverters\ module. Additionally, a dedicated \ArticleId\ domain type and its provider are added to ensure consistent ID generation and validation for articles.

_src/\sharedKernel · high confidence

The \SequelizeUserAdapter\ and \SequelizeUsersRepository\ files have been deleted from the \src/infra/user\ directory. This removes the previous synchronous adapter and repository implementation that handled user entity mapping and database operations, indicating a shift in how user data persistence is managed within the application.

src/infra/user · high confidence

The legacy application entry point and web server configuration have been removed. This includes the deletion of the main Application class, the base Operation class used for event-driven operations, the Awilix dependency injection container setup, and the Express web server configuration (including middleware for CORS, body parsing, compression, and logging). These changes indicate a shift away from the previous monolithic startup and routing structure.

src/app · high confidence

The legacy database migration scripts, model definitions, and seed data generation logic have been removed, along with the associated data faker utility. Additionally, the previous Express-based web server implementation has been deleted. These changes indicate a significant restructuring of the application's infrastructure, likely in preparation for a new architecture or framework integration.

src/infra/database · high confidence

The \User\ model class and the \CreateUser\ and \GetAllUsers\ operation classes have been removed from the \src/domain/user\ directory. This deletion eliminates the previous implementation of user creation and retrieval logic, which relied on an \Operation\ base class and dependency injection for the \UsersRepository\, as part of an ongoing effort to reorganize the domain layer.

src/domain · high confidence

The \scripts/console.js\ file, which previously provided an interactive Read-Eval-Print Loop (REPL) environment for developers to inspect the database models directly, has been removed. This change eliminates the ability to launch this specific development tool via the scripts directory.

scripts · high confidence

The REPL functionality has been extracted from the main application into a dedicated library module at src/\_lib/repl/index.ts. This new module provides a standardized interface for creating and managing REPL instances, supporting both local CLI usage and remote network connections via configurable ports. Users benefit from a more modular architecture where the REPL logic is now encapsulated, allowing for easier maintenance and potential reuse across different parts of the application.

_src/\lib/repl · high confidence

The application startup process has been restructured into a modular system located in src/\_boot, where distinct lifecycle modules handle database connections (MongoDB), HTTP server configuration (Express with CORS and Helmet), Swagger API documentation, and a REPL interface. The main entry point now orchestrates these modules via a context-based bootstrap, allowing for cleaner separation of concerns and configurable initialization of core infrastructure services.

_src/\boot · high confidence

The project has been upgraded to version 3, introducing a complete structural rewrite from a basic Express/Sequelize setup to a scalable TypeScript application based on Clean Architecture and Domain-Driven Design principles. This change replaces the previous JavaScript entry point and ESLint configuration with a strict TypeScript setup (tsconfig.json), adds a dedicated production build configuration (tsconfig.prod.json), and introduces a new dependency injection system using Awilix. To improve developer experience and environment consistency, the release includes a comprehensive Docker Compose configuration for local development (including MongoDB and Mongo Express), a new \.env.test\ file for test database isolation, and a suite of new documentation files (README, CONTRIBUTING, LICENSE) detailing the new module-based architecture, lifecycle events, and usage instructions.

(repo-wide) · high confidence

The article module now uses MongoDB for storage and retrieval. This change introduces a repository that handles article creation and updates with optimistic concurrency control (versioning), a data mapper for translating between domain entities and MongoDB documents, and a query handler that supports paginated, filtered, and sorted listing of published articles, including an aggregation to join associated comments.

src/article/infrastructure · high confidence

The \src/\_lib/http/middlewares\ directory now includes a comprehensive set of new middleware components: \errorHandler\ for structured error mapping and response generation, \httpLogger\ for request logging with custom levels and request IDs, \gracefulShutdown\ to handle server restarts and connection draining, \requestContainer\ for dependency injection scoping per request, and \statusHandler\ to expose service uptime and start time. These changes introduce new runtime behaviors for error reporting, observability, and service lifecycle management.

_src/\lib/http/middlewares · high confidence

The generic error handler that previously caught unhandled exceptions and returned a standardized 500 Internal Server Error response has been removed from the application. This change eliminates the default fallback mechanism for server-side failures, meaning unhandled errors will no longer be automatically formatted and returned to the client via this specific module.

src/app/errors · high confidence

The UsersController class, which previously handled user listing and creation via an Express router and manual dependency injection from the request container, has been removed from the application. This change eliminates the manual route registration and event-based command execution pattern used in this specific controller, reflecting a shift in the application's architectural organization.

src/app/user · high confidence

The application has removed the legacy \config/database.js.example\ file, which previously contained hardcoded database settings for development, test, and production environments, and the \config/index.js\ file that served as the central entry point for loading environment-specific configurations. This change eliminates the previous mechanism for managing database connections and environment variables through these specific configuration modules, indicating a shift in how the application initializes its configuration state.

config · high confidence

The dedicated configuration files for development, production, and test environments have been deleted. Previously, these files explicitly defined the web server port (3000 for development, process.env.PORT for production, and empty for test). With these files removed, the application no longer loads these specific port settings from the config/environments directory, likely shifting port management to a different configuration source or default behavior.

config/environments · high confidence

The error handling system in src/\_lib/errors has been restructured to use a unified BaseError class that exposes consistent properties (name, code, message, type, and optional meta). New specific error types—BadRequestError, ForbiddenError, NotFoundError, UnauthorizedError, and ValidationError—are now provided, each with a factory create function and a type-predicate is function. ValidationError now carries structured metadata (target and Joi error details) instead of a plain string, enabling more precise error reporting and programmatic handling.

_src/\lib/errors · high confidence

Added integration tests for ArticleController; Added test infrastructure and helpers; Added unit tests for article application use cases; Removed legacy test files for SequelizeUserAdapter and SequelizeUsersRepository; Removed legacy test support utilities; Removed legacy user API test files; Removed outdated domain tests for User and CreateUser operations; Removed test setup and configuration files; Removed test suite for App Operation.

The project has been upgraded to version 3.0.0-beta, shifting from a plain JavaScript boilerplate to a TypeScript-based architecture. This change updates the minimum Node.js engine requirement to 12.0.0 and replaces the entry point with the compiled output in dist/index.js. The dependency list has been significantly modernized: core libraries like Express, Awilix, and Sequelize have been upgraded to newer major versions, while legacy packages such as Bluebird, Method-Override, and Structure have been removed. New dependencies include Helmet for security, Joi for validation, and Swagger tools for API documentation. The build system now uses TypeScript (v4.3.5) with Jest for testing, replacing the previous Mocha/Istanbul setup, and introduces new scripts for building, development, and debugging.

(dependencies) · high confidence

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

• CAI 54 → 50 (-3.6)
• Rubric changed (rubric-2026.08.17 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 94 → 96 (+1.8)
• Architecture 84 → 83 (-0.9)
• Maturity 72 → 56 (-15.7)
• Readiness 25 → 28 (+2.7)
• Security 80 → 82 (+1.8)

• Change coupling: repl.ts ↔ server.ts (src/_boot/repl.ts)
• Coverage not included — suite not readable by the collector
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Dependency hygiene not measured — no supported dependency manifest was read
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• …and 38 more

• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Documentation: no architecture or design documentation (README.md)
• Documentation: no installation or build instructions (README.md)
• High CVE: [CVE redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• …and 47 more

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

talyssonoc/node-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.