nodejs-quickstart-structure 1.15.1 → 1.16.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.16.0] - 2026-03-14
+
+### Added
+- **Robust Kafka Singleton Implementation**: Refactored `KafkaService` to a strict singleton pattern across all architectures with `connectionPromise` and automated retry logic for resilient messaging.
+- **BaseConsumer Standards**: Implemented constructor guards in `BaseConsumer` to prevent direct instantiation of abstract messaging classes.
+- **Professional Docker Log Hygiene**: Added `NPM_CONFIG_UPDATE_NOTIFIER=false` to both builder and production stages to suppress non-essential npm upgrade notifications.
+
+### Fixed
+- **Docker Build & Type Safety**: Resolved a critical build failure in MVC TypeScript projects using EJS/Pug by addressing missing Express `Request` and `Response` type imports.
+- **Network Resilience**: Removed redundant `npm install -g npm@latest` from the `Dockerfile` template to fix `ECONNRESET` failures during project verification on unstable networks.
+- **Controller Testing Modernization**: Refactored `userController` spec templates (TS and JS) to correctly mock and verify the shared Kafka singleton, fixing persistent unit test failures.
+- **Database Mocking Refinement**: Resolved a data flow bug in the "None" database mock where generated IDs were being overwritten, and enhanced TypeScript types to eliminate `any` in repository patterns.
+
 ## [1.15.1] - 2026-03-12
 
 ### Added

package/lib/modules/app-setup.js

@@ -165,8 +165,8 @@ export const renderDynamicComponents = async (templatePath, targetDir, config) =
         }
     }
 
-    // Cleanup REST routes if GraphQL or Kafka is selected
-    if (config.communication !== 'REST APIs') {
+    // Cleanup REST routes if neither REST APIs nor Kafka is selected
+    if (config.communication !== 'REST APIs' && config.communication !== 'Kafka') {
         if (architecture === 'MVC') {
             await fs.remove(path.join(targetDir, 'src/routes'));
         } else if (architecture === 'Clean Architecture') {
@@ -280,7 +280,7 @@ export const renderSwaggerConfig = async (templatesDir, targetDir, config) => {
     }
     await fs.ensureDir(configDir);
 
-    if (communication === 'REST APIs') {
+    if (communication === 'REST APIs' || communication === 'Kafka') {
         const swaggerYmlTemplateSource = path.join(templatesDir, 'common', 'swagger.yml.ejs');
         if (await fs.pathExists(swaggerYmlTemplateSource)) {
             const ymlContent = ejs.render(await fs.readFile(swaggerYmlTemplateSource, 'utf-8'), { projectName });

package/lib/modules/config-files.js

@@ -97,10 +97,10 @@ export const renderTestSample = async (templatesDir, targetDir, config) => {
             "extends": "../tsconfig.json",
             "compilerOptions": {
                 "types": ["jest", "node"],
-                "rootDir": "../tests",
+                "rootDir": "..",
                 "noEmit": true
             },
-            "include": ["**/*.ts"]
+            "include": ["**/*.ts", "../src/**/*.ts"]
         };
         await fs.writeFile(path.join(targetDir, 'tests', 'tsconfig.json'), JSON.stringify(testsTsConfig, null, 4));
     }

package/lib/modules/kafka-setup.js

@@ -8,7 +8,14 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
 
     const langExt = language === 'TypeScript' ? 'ts' : 'js';
     const kafkaSource = path.join(templatesDir, 'common', 'kafka', langExt);
-    await fs.copy(kafkaSource, path.join(targetDir, 'src'));
+    
+    // 1. Copy necessary directories individually (to avoid orphaned templates in src)
+    if (await fs.pathExists(path.join(kafkaSource, 'services'))) {
+        await fs.copy(path.join(kafkaSource, 'services'), path.join(targetDir, 'src/services'));
+    }
+    if (await fs.pathExists(path.join(kafkaSource, 'config'))) {
+        await fs.copy(path.join(kafkaSource, 'config'), path.join(targetDir, 'src/config'));
+    }
 
     // Render Kafka Service with dynamic logger path
     const kafkaServiceFileName = `kafkaService.${langExt}`;
@@ -16,7 +23,7 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
     // Render Kafka Service Spec
     const kafkaSpecFileName = `kafkaService.spec.${langExt}`;
     const kafkaSpecTemplate = path.join(targetDir, 'src', 'services', `${kafkaSpecFileName}.ejs`);
-
+   
     if (await fs.pathExists(kafkaServiceTemplate)) {
         let serviceLoggerPath, serviceConfigPath;
         if (language === 'TypeScript') {
@@ -39,10 +46,9 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
             specConfigPath = architecture === 'Clean Architecture' ? '@/infrastructure/config/kafka' : '@/config/kafka';
             specServicePath = architecture === 'Clean Architecture' ? '@/infrastructure/messaging/kafkaClient' : '@/services/kafkaService';
         } else {
-            // For JS tests, we use @/ to ensure resolution after move to tests/
-            specLoggerPath = architecture === 'Clean Architecture' ? '@/infrastructure/log/logger' : '@/utils/logger';
-            specConfigPath = architecture === 'Clean Architecture' ? '@/infrastructure/config/kafka' : '@/config/kafka';
-            specServicePath = architecture === 'Clean Architecture' ? '@/infrastructure/messaging/kafkaClient' : '@/services/kafkaService';
+            specLoggerPath = architecture === 'Clean Architecture' ? '../../infrastructure/log/logger' : '../utils/logger';
+            specConfigPath = architecture === 'Clean Architecture' ? '../../infrastructure/config/kafka' : '../config/kafka';
+            specServicePath = architecture === 'Clean Architecture' ? '../../infrastructure/messaging/kafkaClient' : '../services/kafkaService';
         }
 
         const specContent = ejs.render(await fs.readFile(kafkaSpecTemplate, 'utf-8'), { ...config, loggerPath: specLoggerPath, configPath: specConfigPath, servicePath: specServicePath });
@@ -64,7 +70,6 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
         await fs.ensureDir(path.dirname(specTarget));
         await fs.writeFile(specTarget, specContent);
         
-        // Remove the template from src in targetDir to avoid double processing by processAllTests
         const targetSpecTemplate = path.join(targetDir, 'src', 'config', `${kafkaConfigSpecFileName}.ejs`);
         if (await fs.pathExists(targetSpecTemplate)) {
             await fs.remove(targetSpecTemplate);
@@ -79,14 +84,12 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
 
         const serviceExt = language === 'TypeScript' ? 'ts' : 'js';
         
-        // Move Service to Infrastructure/Messaging
         await fs.move(
             path.join(targetDir, `src/services/kafkaService.${serviceExt}`), 
             path.join(targetDir, `src/infrastructure/messaging/kafkaClient.${serviceExt}`),
             { overwrite: true }
         );
 
-        // Move Spec to Tests/Infrastructure/Messaging
         if (await fs.pathExists(path.join(targetDir, `src/services/kafkaService.spec.${serviceExt}`))) {
             await fs.move(
                 path.join(targetDir, `src/services/kafkaService.spec.${serviceExt}`),
@@ -95,8 +98,6 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
             );
         }
 
-        // Move Config to Infrastructure/Config
-        // Note: Check if config path exists before moving, though copy above should have put it there
         if (await fs.pathExists(path.join(targetDir, `src/config/kafka.${serviceExt}`))) {
             await fs.move(
                 path.join(targetDir, `src/config/kafka.${serviceExt}`),
@@ -105,18 +106,68 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
             );
         }
 
-        // Cleanup old services folder
         await fs.remove(path.join(targetDir, 'src/services'));
+
+        // Messaging Infrastructure Enhancement
+        const messagingDir = path.join(targetDir, 'src/interfaces/messaging');
+        await fs.ensureDir(path.join(messagingDir, 'consumers/instances'));
+        await fs.ensureDir(path.join(messagingDir, 'schemas'));
+
+        const loggerPath = language === 'TypeScript' ? '@/infrastructure/log/logger' : '../../infrastructure/log/logger';
+        const messagingTemplates = [
+            { src: 'baseConsumer', dest: 'interfaces/messaging/baseConsumer' },
+            { src: 'userEventSchema', dest: 'interfaces/messaging/schemas/userEventSchema' },
+            { src: 'welcomeEmailConsumer', dest: 'interfaces/messaging/consumers/instances/welcomeEmailConsumer' }
+        ];
+
+        for (const t of messagingTemplates) {
+            const templateSource = path.join(templatesDir, 'common', 'kafka', langExt, 'messaging', `${t.src}.${langExt}.ejs`);
+            if (await fs.pathExists(templateSource)) {
+                const content = ejs.render(await fs.readFile(templateSource, 'utf-8'), { ...config, loggerPath });
+                await fs.writeFile(path.join(targetDir, 'src', `${t.dest}.${langExt}`), content);
+            }
+
+            // Render Specs for messaging components
+            const specTemplateSource = path.join(templatesDir, 'common', 'kafka', langExt, 'messaging', `${t.src}.spec.${langExt}.ejs`);
+            if (await fs.pathExists(specTemplateSource)) {
+                const specContent = ejs.render(await fs.readFile(specTemplateSource, 'utf-8'), { ...config, loggerPath });
+                const specDest = path.join(targetDir, 'tests', `${t.dest}.spec.${langExt}`);
+                await fs.ensureDir(path.dirname(specDest));
+                await fs.writeFile(specDest, specContent);
+            }
+        }
         
-        // Remove REST-specific folders (Interfaces) - Note: routes is kept for health endpoint
-        await fs.remove(path.join(targetDir, 'src/interfaces/controllers'));
-        await fs.remove(path.join(targetDir, 'tests/interfaces/controllers'));
-        
-        // Original logic removed src/config entirely, but now we use it for Zod env validation in TS.
-        // We will no longer delete it.
     } else if (architecture === 'MVC') {
         const serviceExt = language === 'TypeScript' ? 'ts' : 'js';
-        // Move Spec to Tests/Services
+        
+        const messagingDir = path.join(targetDir, 'src/messaging');
+        await fs.ensureDir(path.join(messagingDir, 'consumers/instances'));
+        await fs.ensureDir(path.join(messagingDir, 'schemas'));
+
+        const loggerPath = language === 'TypeScript' ? '@/utils/logger' : '../utils/logger';
+        const messagingTemplates = [
+            { src: 'baseConsumer', dest: 'messaging/baseConsumer' },
+            { src: 'userEventSchema', dest: 'messaging/schemas/userEventSchema' },
+            { src: 'welcomeEmailConsumer', dest: 'messaging/consumers/instances/welcomeEmailConsumer' }
+        ];
+
+        for (const t of messagingTemplates) {
+            const templateSource = path.join(templatesDir, 'common', 'kafka', langExt, 'messaging', `${t.src}.${langExt}.ejs`);
+            if (await fs.pathExists(templateSource)) {
+                const content = ejs.render(await fs.readFile(templateSource, 'utf-8'), { ...config, loggerPath });
+                await fs.writeFile(path.join(targetDir, 'src', `${t.dest}.${langExt}`), content);
+            }
+
+            // Render Specs for messaging components
+            const specTemplateSource = path.join(templatesDir, 'common', 'kafka', langExt, 'messaging', `${t.src}.spec.${langExt}.ejs`);
+            if (await fs.pathExists(specTemplateSource)) {
+                const specContent = ejs.render(await fs.readFile(specTemplateSource, 'utf-8'), { ...config, loggerPath });
+                const specDest = path.join(targetDir, 'tests', `${t.dest}.spec.${langExt}`);
+                await fs.ensureDir(path.dirname(specDest));
+                await fs.writeFile(specDest, specContent);
+            }
+        }
+
         if (await fs.pathExists(path.join(targetDir, `src/services/kafkaService.spec.${serviceExt}`))) {
             await fs.ensureDir(path.join(targetDir, 'tests/services'));
             await fs.move(
@@ -126,11 +177,6 @@ export const setupKafka = async (templatesDir, targetDir, config) => {
             );
         }
 
-        if (!config.viewEngine || config.viewEngine === 'None') {
-            // MVC Cleanup for Kafka Worker (No views) - Note: routes is kept for health endpoint
-            await fs.remove(path.join(targetDir, 'src/controllers'));
-            await fs.remove(path.join(targetDir, 'tests/controllers'));
-        }
     }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-quickstart-structure",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "type": "module",
   "description": "The ultimate nodejs quickstart structure CLI to scaffold Node.js microservices with MVC or Clean Architecture",
   "main": "bin/index.js",

package/templates/clean-architecture/js/src/index.js.ejs

@@ -1,7 +1,7 @@
 const startServer = require('./infrastructure/webserver/server');
 const logger = require('./infrastructure/log/logger');
 <% if (communication === 'Kafka') { -%>
-const { connectKafka, sendMessage } = require('./infrastructure/messaging/kafkaClient');
+const { connectKafka } = require('./infrastructure/messaging/kafkaClient');
 <% } -%>
 
 <%_ if (database !== 'None') { -%>
@@ -24,7 +24,6 @@ const syncDatabase = async () => {
             // Connect Kafka
             connectKafka().then(async () => {
               logger.info('Kafka connected');
-              await sendMessage('test-topic', 'Hello Kafka from Clean Arch JS!');
             }).catch(err => {
               logger.error('Failed to connect to Kafka:', err);
             });
@@ -45,7 +44,6 @@ startServer();
 // Connect Kafka
 connectKafka().then(async () => {
   logger.info('Kafka connected');
-  await sendMessage('test-topic', 'Hello Kafka from Clean Arch JS!');
 }).catch(err => {
   logger.error('Failed to connect to Kafka:', err);
 });

package/templates/clean-architecture/js/src/infrastructure/webserver/server.js.ejs

@@ -4,7 +4,7 @@ const logger = require('../log/logger');
 const morgan = require('morgan');
 const { errorMiddleware } = require('./middleware/errorMiddleware');
 const healthRoutes = require('../../interfaces/routes/healthRoute');
-<%_ if (communication === 'REST APIs') { -%>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 const apiRoutes = require('../../interfaces/routes/api');
 const swaggerUi = require('swagger-ui-express');
 const swaggerSpecs = require('./swagger');
@@ -29,10 +29,10 @@ const startServer = async () => {
     app.use(cors());
     app.use(express.json());
     app.use(morgan('combined', { stream: { write: message => logger.info(message.trim()) } }));
-    <%_ if (communication === 'REST APIs') { -%>
+    <%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
     app.use('/api', apiRoutes);
     <%_ } -%>
-    <%_ if (communication === 'REST APIs') { -%>
+    <%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
     app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecs));
     <%_ } -%>
     <%_ if (communication === 'GraphQL') { -%>
@@ -71,13 +71,14 @@ const startServer = async () => {
     const server = app.listen(port, () => {
         logger.info(`Server running on port ${port}`);
 <%_ if (communication === 'Kafka') { -%>
-        const { connectKafka, sendMessage } = require('../../infrastructure/messaging/kafkaClient');
-        connectKafka().then(() => {
-          logger.info('Kafka connected');
-          sendMessage('test-topic', 'Hello Kafka from Clean Arch JS!');
-        }).catch(err => {
-          logger.error('Failed to connect to Kafka:', err);
-        });
+        const { connectKafka } = require('../../infrastructure/messaging/kafkaClient');
+        connectKafka()
+            .then(async () => {
+                logger.info('Kafka connected');
+            })
+            .catch(err => {
+                logger.error('Failed to connect to Kafka after retries:', err.message);
+            });
 <%_ } -%>
     });
 

package/templates/clean-architecture/js/src/interfaces/controllers/userController.js.ejs

@@ -26,7 +26,15 @@ class UserController {
     async createUser(data) {
         const { name, email } = data;
         try {
-            return await this.createUserUseCase.execute(name, email);
+            const user = await this.createUserUseCase.execute(name, email);
+<%_ if (communication === 'Kafka') { -%>
+            const { sendMessage } = require('../../infrastructure/messaging/kafkaClient');
+            await sendMessage('user-topic', JSON.stringify({
+                action: 'USER_CREATED',
+                payload: { id: user.id || user._id, email: user.email }
+            }));
+<%_ } -%>
+            return user;
         } catch (error) {
             logger.error('Error creating user:', error);
             throw error;
@@ -47,6 +55,13 @@ class UserController {
         const { name, email } = req.body;
         try {
             const user = await this.createUserUseCase.execute(name, email);
+<%_ if (communication === 'Kafka') { -%>
+            const { sendMessage } = require('../../infrastructure/messaging/kafkaClient');
+            await sendMessage('user-topic', JSON.stringify({
+                action: 'USER_CREATED',
+                payload: { id: user.id || user._id, email: user.email }
+            }));
+<%_ } -%>
             res.status(HTTP_STATUS.CREATED).json(user);
         } catch (error) {
             logger.error('Error creating user:', error);

package/templates/clean-architecture/js/src/interfaces/controllers/userController.spec.js.ejs

@@ -4,6 +4,12 @@ const GetAllUsers = require('@/usecases/GetAllUsers');
 
 jest.mock('@/usecases/CreateUser');
 jest.mock('@/usecases/GetAllUsers');
+<%_ if (communication === 'Kafka') { -%>
+jest.mock('@/infrastructure/messaging/kafkaClient', () => ({
+    sendMessage: jest.fn().mockResolvedValue(undefined)
+}));
+<%_ } -%>
+
 
 describe('UserController (Clean Architecture)', () => {
     let userController;
@@ -81,7 +87,12 @@ describe('UserController (Clean Architecture)', () => {
             expect(result).toEqual(expectedUser);
 <%_ } else { -%>
             await userController.createUser(mockRequest, mockResponse, mockNext);
+<%_ if (communication === 'Kafka') { -%>
+            const { sendMessage } = require('@/infrastructure/messaging/kafkaClient');
+            expect(sendMessage).toHaveBeenCalled();
+<%_ } -%>
             expect(mockResponse.status).toHaveBeenCalledWith(201);
+
             expect(mockResponse.json).toHaveBeenCalledWith(expectedUser);
 <%_ } -%>
             expect(mockCreateUserUseCase.execute).toHaveBeenCalledWith(payload.name, payload.email);
@@ -98,5 +109,30 @@ describe('UserController (Clean Architecture)', () => {
             expect(mockNext).toHaveBeenCalledWith(error);
 <%_ } -%>
         });
+
+<%_ if (communication === 'Kafka') { -%>
+        it('should successfully create a new user with _id for Kafka (Happy Path)', async () => {
+            const payload = { name: 'Bob', email: 'bob@example.com' };
+<% if (communication === 'GraphQL') { -%>
+            const dataArg = payload;
+<% } else { -%>
+            mockRequest.body = payload;
+<% } -%>
+            const expectedUser = { _id: '2', ...payload };
+            
+            mockCreateUserUseCase.execute.mockResolvedValue(expectedUser);
+
+<% if (communication === 'GraphQL') { -%>
+            await userController.createUser(dataArg);
+<% } else { -%>
+            await userController.createUser(mockRequest, mockResponse, mockNext);
+<% } -%>
+            const { sendMessage } = require('@/infrastructure/messaging/kafkaClient');
+            expect(sendMessage).toHaveBeenCalledWith(
+                'user-topic',
+                expect.stringContaining('"id":"2"')
+            );
+        });
+<%_ } -%>
     });
 });

package/templates/clean-architecture/ts/src/config/swagger.ts.ejs

@@ -1,4 +1,4 @@
-<% if (communication === 'REST APIs') { %>import path from 'path';
+<% if (communication === 'REST APIs' || communication === 'Kafka') { %>import path from 'path';
 import YAML from 'yamljs';
 
 const swaggerDocument = YAML.load(path.join(__dirname, 'swagger.yml'));

package/templates/clean-architecture/ts/src/index.ts.ejs

@@ -8,11 +8,11 @@ import morgan from 'morgan';
 import { errorMiddleware } from '@/utils/errorMiddleware';
 import { setupGracefulShutdown } from '@/utils/gracefulShutdown';
 import healthRoutes from '@/interfaces/routes/healthRoute';
-<% if (communication === 'REST APIs') { -%>
+<% if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 import userRoutes from '@/interfaces/routes/userRoutes';
 import swaggerUi from 'swagger-ui-express';
-import swaggerSpecs from '@/config/swagger';<% } -%>
-<%_ if (communication === 'Kafka') { -%>import { KafkaService } from '@/infrastructure/messaging/kafkaClient';<%_ } -%>
+import swaggerSpecs from '@/config/swagger';<% } %>
+<%_ if (communication === 'Kafka') { -%>import { kafkaService } from '@/infrastructure/messaging/kafkaClient';<%_ } -%>
 <%_ if (communication === 'GraphQL') { -%>
 import { ApolloServer } from '@apollo/server';
 import { expressMiddleware } from '@apollo/server/express4';
@@ -52,10 +52,10 @@ app.use(limiter);
 app.use(express.json());
 app.use(morgan('combined', { stream: { write: (message) => logger.info(message.trim()) } }));
 
-<%_ if (communication === 'REST APIs') { -%>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 app.use('/api/users', userRoutes);
 <%_ } -%>
-<%_ if (communication === 'REST APIs') { -%>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecs));
 <%_ } -%>
 app.use('/health', healthRoutes);
@@ -92,18 +92,16 @@ const startServer = async () => {
     app.use('/graphql', expressMiddleware(apolloServer, { context: gqlContext }));
 <%_ } -%>
     app.use(errorMiddleware);
-<%_ if (communication === 'Kafka') { -%>
-    const kafkaService = new KafkaService();
-<%_ } -%>
     const server = app.listen(port, () => {
         logger.info(`Server running on port ${port}`);
 <%_ if (communication === 'Kafka') { -%>
-        kafkaService.connect().then(() => {
-          logger.info('Kafka connected');
-          kafkaService.sendMessage('test-topic', 'Hello Kafka from Clean Arch TS!');
-        }).catch(err => {
-          logger.error('Failed to connect to Kafka:', err);
-        });
+        kafkaService.connect()
+            .then(async () => {
+                logger.info('Kafka connected');
+            })
+            .catch(err => {
+                logger.error('Failed to connect to Kafka after retries:', (err as Error).message);
+            });
 <%_ } -%>
     });
 

package/templates/clean-architecture/ts/src/infrastructure/log/logger.spec.ts.ejs

@@ -56,7 +56,6 @@ describe('Logger', () => {
         const winston = require('winston');
         jest.resetModules();
         process.env.NODE_ENV = 'production';
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
         require('<% if (architecture === "MVC") { %>@/utils/logger<% } else { %>@/infrastructure/log/logger<% } %>');
         expect(winston.format.json).toHaveBeenCalled();
         process.env.NODE_ENV = 'test';

package/templates/clean-architecture/ts/src/interfaces/controllers/userController.spec.ts.ejs

@@ -11,6 +11,20 @@ jest.mock('@/infrastructure/repositories/UserRepository');
 jest.mock('@/usecases/createUser');
 jest.mock('@/usecases/getAllUsers');
 jest.mock('@/infrastructure/log/logger');
+<%_ if (communication === 'Kafka') { -%>
+jest.mock('@/infrastructure/messaging/kafkaClient', () => {
+    const mockSendMessage = jest.fn().mockResolvedValue(undefined);
+    return {
+        kafkaService: {
+            sendMessage: mockSendMessage
+        },
+        KafkaService: jest.fn().mockImplementation(() => ({
+            sendMessage: mockSendMessage
+        }))
+    };
+});
+<%_ } -%>
+
 
 describe('UserController (Clean Architecture)', () => {
     let userController: UserController;
@@ -115,7 +129,12 @@ describe('UserController (Clean Architecture)', () => {
             await userController.createUser(mockRequest as Request, mockResponse as Response, mockNext);
 
             // Assert
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = require('@/infrastructure/messaging/kafkaClient');
+            expect(kafkaService.sendMessage).toHaveBeenCalled();
+<%_ } -%>
             expect(mockResponse.status).toHaveBeenCalledWith(HTTP_STATUS.CREATED);
+
             expect(mockResponse.json).toHaveBeenCalledWith(expectedUser);
 <% } -%>
             expect(mockCreateUserUseCase.execute).toHaveBeenCalledWith(payload.name, payload.email);

package/templates/clean-architecture/ts/src/interfaces/controllers/userController.ts.ejs

@@ -22,6 +22,14 @@ export class UserController {
         try {
             const { name, email } = data;
             const user = await this.createUserUseCase.execute(name, email);
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = await import('@/infrastructure/messaging/kafkaClient');
+            await kafkaService.sendMessage('user-topic', JSON.stringify({
+                action: 'USER_CREATED',
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                payload: { id: (user as any).id || (user as any)._id, email: user.email }
+            }));
+<%_ } -%>
             return user;
         } catch (error: unknown) {
             const message = error instanceof Error ? error.message : 'Unknown error';
@@ -45,6 +53,14 @@ export class UserController {
         try {
             const { name, email } = req.body;
             const user = await this.createUserUseCase.execute(name, email);
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = await import('@/infrastructure/messaging/kafkaClient');
+            await kafkaService.sendMessage('user-topic', JSON.stringify({
+                action: 'USER_CREATED',
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                payload: { id: (user as any).id || (user as any)._id, email: user.email }
+            }));
+<%_ } -%>
             res.status(HTTP_STATUS.CREATED).json(user);
         } catch (error: unknown) {
             const message = error instanceof Error ? error.message : 'Unknown error';

package/templates/common/Dockerfile

@@ -4,6 +4,7 @@
 FROM node:22-alpine AS builder
 
 WORKDIR /app
+ENV NPM_CONFIG_UPDATE_NOTIFIER=false
 
 COPY package*.json ./
 COPY tsconfig*.json ./
@@ -24,6 +25,7 @@ FROM node:22-alpine AS production
 WORKDIR /app
 
 ENV NODE_ENV=production
+ENV NPM_CONFIG_UPDATE_NOTIFIER=false
 
 COPY package*.json ./
 

package/templates/common/README.md.ejs

@@ -115,6 +115,29 @@ mutation CreateUser {
 API is exposed via **REST**.
 A Swagger UI for API documentation is available at:
 - **URL**: `http://localhost:3000/api-docs` (Dynamic based on PORT)
+<%_ } -%>
+
+<% if (communication === 'Kafka') { -%>
+## 📡 Testing Kafka Asynchronous Flow
+This project demonstrates a production-ready Kafka flow:
+1. **Producer**: When a user is created via the API, a `USER_CREATED` event is sent to `user-topic`.
+2. **Consumer**: `WelcomeEmailConsumer` listens to `user-topic` and simulates sending an email.
+
+### How to verify:
+1. Ensure infrastructure is running: `docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> zookeeper kafka<% } %>`
+2. Start the app: `npm run dev`
+3. Trigger an event by creating a user (via Postman or curl):
+   ```bash
+   curl -X POST http://localhost:3000/api/users \
+     -H "Content-Type: application/json" \
+     -d '{"name": "Kafka Tester", "email": "kafka@example.com"}'
+   ```
+4. Observe the logs:
+   ```text
+   [Kafka] Producer: Sent USER_CREATED event for 'kafka@example.com'
+   [Kafka] Consumer: Received USER_CREATED. 
+   [Kafka] Consumer: 📧 Sending welcome email to 'kafka@example.com'... Done!
+   ```
 <% } -%>
 
 <% if (caching === 'Redis') { -%>
@@ -227,4 +250,4 @@ This project is "AI-Ready" out of the box. We have pre-configured industry-leadi
 - **Magic Defaults**: We've automatically tailored your AI context to focus on **<%= projectName %>** and its specific architectural stack (<%= architecture %>, <%= database %>, etc.).
 - **Use Cursor?** We've configured **`.cursorrules`** at the root. It enforces project standards (70% coverage, MVC/Clean) directly within the editor. 
   - *Pro-tip*: You can customize the `Project Goal` placeholder in `.cursorrules` to help the AI understand your specific business logic!
-- **Use ChatGPT/Gemini/Claude?** Check the **`prompts/`** directory. It contains highly-specialized Agent Skill templates. You can copy-paste these into any LLM to give it a "Senior Developer" understanding of your codebase immediately.
+- **Use ChatGPT/Gemini/Claude?** Check the **`prompts/`** directory. It contains highly-specialized Agent Skill templates. You can copy-paste these into any LLM to give it a "Senior Developer" understanding of your codebase immediately.

package/templates/common/database/js/models/User.js.ejs

@@ -11,7 +11,8 @@ class UserModel {
   }
 
   static async create(data) {
-    const newUser = { id: String(this.mockData.length + 1), ...data };
+    const { id, ...rest } = data;
+    const newUser = { id: String(this.mockData.length + 1), ...rest };
     this.mockData.push(newUser);
     return newUser;
   }

package/templates/common/database/ts/models/User.ts.ejs

@@ -16,10 +16,11 @@ export default class UserModel {
     return this.mockData;
   }
 
-  static async create(data: Omit<User, 'id'>) {
-    const newUser = { id: String(this.mockData.length + 1), ...data };
+  static async create(data: Omit<User, 'id'> & { id?: string | number | null }) {
+    const { id, ...rest } = data;
+    const newUser: User = { id: String(this.mockData.length + 1), ...rest };
     this.mockData.push(newUser);
-    return newUser as User;
+    return newUser;
   }
 }
 <% } else { -%>