nodejs-quickstart-structure 1.14.0 → 1.15.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.15.1] - 2026-03-12
+
+### Added
+- **Magic AI Scaffolding**: Automated AI context generation ( `.cursorrules`, `prompts/`) by intelligently inferring project goals from the project name, removing the need for manual business domain prompts.
+- **Enhanced README**: Added specialized guidance for AI-native development with Cursor and LLMs.
+
+### Fixed
+- **GitHub Actions Compliance**: Fully resolved Node.js 20 deprecation warnings by moving `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` to global workflow scope.
+- **CI Modernization**: Upgraded daily audit and GitLab CI runners to Node.js 22.
+- **CI Enforcement**: Updated all CI/CD templates (GitHub, GitLab, Jenkins) to strictly enforce the >70% test coverage gate.
+
+## [1.15.0] - 2026-03-12
+### Added
+- **AI-Native Scaffolding & Agent Skill Templates:**
+  - Added a new CLI prompt for `businessDomain` to inject custom domain knowledge into generated templates.
+  - Generates a `.cursorrules` file at the root to enforce >70% Test coverage and Architecture patterns automatically for AI Code Editors.
+  - Scaffolds a `prompts/` directory with specialized Agent Skill templates (`project-context.md`, `add-feature.md`, `troubleshoot.md`) designed to provide deep structural understanding to LLMs like ChatGPT or Claude.
+  - Added an "AI-Native Development" section to the generated `README.md` and prominent print messages in the CLI upon successful completion.
+
 ## [1.14.0] - 2026-03-09
 ### Added
 - **Unit test:**

package/bin/index.js

@@ -1,81 +1,85 @@
 #!/usr/bin/env node
-
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { getProjectDetails } from '../lib/prompts.js';
-import { generateProject } from '../lib/generator.js';
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
-
-const program = new Command();
-
-program
-    .name('nodejs-quickstart')
-    .description('🚀 CLI to scaffold production-ready Node.js microservices.\n\nGenerates projects with:\n- MVC or Clean Architecture\n- REST or Kafka\n- MySQL, PostgreSQL, or MongoDB\n- Docker, Flyway & Mongoose support')
-    .version(pkg.version, '-v, --version', 'Output the current version')
-    .addHelpText('after', `
-\n${chalk.yellow('Example:')}
-  $ nodejs-quickstart init   ${chalk.gray('# Start the interactive setup')}
-`);
-
-program
-    .command('init')
-    .description('Initialize a new Node.js project')
-    .option('-n, --project-name <name>', 'Project name')
-    .option('-l, --language <language>', 'Language (JavaScript, TypeScript)')
-    .option('-a, --architecture <architecture>', 'Architecture (MVC, Clean Architecture)')
-    .option('--view-engine <view>', 'View Engine (None, EJS, Pug) - MVC only')
-    .option('-d, --database <database>', 'Database (MySQL, PostgreSQL)')
-    .option('--db-name <name>', 'Database name')
-    .option('-c, --communication <communication>', 'Communication (REST APIs, GraphQL, Kafka)')
-    .option('--ci-provider <provider>', 'CI/CD Provider (None, GitHub Actions, Jenkins)')
-    .option('--caching <type>', 'Caching Layer (None/Redis)')
-    .action(async (options) => {
-        // Fix for Commander camelCase conversion
-        if (options.ciProvider) {
-            options.ciProvider = options.ciProvider;
-        }
-
-        console.log(chalk.blue('Welcome to the Node.js Quickstart Generator!'));
-
-        try {
-            const answers = await getProjectDetails(options);
-            console.log(chalk.green('\nConfiguration received:'));
-            console.log(JSON.stringify(answers, null, 2));
-
-            console.log(chalk.yellow('\nGenerating project...'));
-            await generateProject(answers);
-
-            console.log(chalk.green('\n✔ Project generated successfully!'));
-            
-            let manualStartInstructions = `\n${chalk.yellow('Development:')}\n  cd ${answers.projectName}\n  npm install`;
-            
-            const needsInfrastructure = answers.database !== 'None' || answers.caching === 'Redis' || answers.communication === 'Kafka';
-            
-            if (needsInfrastructure) {
-                let servicesToStart = '';
-                if (answers.database !== 'None') servicesToStart += ' db';
-                if (answers.caching === 'Redis') servicesToStart += ' redis';
-                if (answers.communication === 'Kafka') servicesToStart += ' zookeeper kafka';
-                
-                manualStartInstructions += `\n  docker-compose up -d${servicesToStart}  # Start infrastructure first\n  npm run dev`;
-            } else {
-                manualStartInstructions += `\n  npm run dev`;
-            }
-            
-            console.log(chalk.cyan(`\nNext steps:\n  cd ${answers.projectName}\n  npm install\n  docker-compose up\n-----------------------${manualStartInstructions}\n\n${chalk.yellow('Production (PM2):')}\n  npm run build\n  npm run deploy\n  npx pm2 logs`));
-
-        } catch (error) {
-            console.error(chalk.red('Error generating project:'), error);
-            process.exit(1);
-        }
-    });
-program.parse(process.argv);
-
-if (!process.argv.slice(2).length) {
-    program.outputHelp();
-}
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getProjectDetails } from '../lib/prompts.js';
+import { generateProject } from '../lib/generator.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+    .name('nodejs-quickstart')
+    .description('🚀 CLI to scaffold production-ready Node.js microservices.\n\nGenerates projects with:\n- MVC or Clean Architecture\n- REST or Kafka\n- MySQL, PostgreSQL, or MongoDB\n- Docker, Flyway & Mongoose support')
+    .version(pkg.version, '-v, --version', 'Output the current version')
+    .addHelpText('after', `\n${chalk.yellow('Example:')}\n  $ nodejs-quickstart init   ${chalk.gray('# Start the interactive setup')}\n`);
+
+program
+    .command('init')
+    .description('Initialize a new Node.js project')
+    .option('-n, --project-name <name>', 'Project name')
+    .option('-l, --language <language>', 'Language (JavaScript, TypeScript)')
+    .option('-a, --architecture <architecture>', 'Architecture (MVC, Clean Architecture)')
+    .option('--view-engine <view>', 'View Engine (None, EJS, Pug) - MVC only')
+    .option('-d, --database <database>', 'Database (MySQL, PostgreSQL)')
+    .option('--db-name <name>', 'Database name')
+    .option('-c, --communication <communication>', 'Communication (REST APIs, GraphQL, Kafka)')
+    .option('--ci-provider <provider>', 'CI/CD Provider (None, GitHub Actions, Jenkins)')
+    .option('--caching <type>', 'Caching Layer (None/Redis)')
+    .action(async (options) => {
+        // Fix for Commander camelCase conversion
+        if (options.ciProvider) {
+            options.ciProvider = options.ciProvider;
+        }
+
+        console.log(chalk.blue('Welcome to the Node.js Quickstart Generator!'));
+
+        try {
+            const answers = await getProjectDetails(options);
+            console.log(chalk.green('\nConfiguration received:'));
+            console.log(JSON.stringify(answers, null, 2));
+
+            console.log(chalk.yellow('\nGenerating project...'));
+            await generateProject(answers);
+
+            console.log(chalk.green('\n✔ Project generated successfully!'));
+            
+            console.log(chalk.magenta('\n🚀 Project is AI-Ready!'));
+            console.log(chalk.magenta('-----------------------------------------'));
+            console.log(chalk.magenta('🤖 We detected you are using AI tools.'));
+            console.log(chalk.magenta(`📍 Use Cursor? We've configured '.cursorrules' for you.`));
+            console.log(chalk.magenta(`📍 Use ChatGPT/Gemini? Check the 'prompts/' folder for Agent Skills.`));
+            console.log(chalk.magenta('-----------------------------------------'));
+
+            let manualStartInstructions = `\n${chalk.yellow('Development:')}\n  cd ${answers.projectName}\n  npm install`;
+            
+            const needsInfrastructure = answers.database !== 'None' || answers.caching === 'Redis' || answers.communication === 'Kafka';
+            
+            if (needsInfrastructure) {
+                let servicesToStart = '';
+                if (answers.database !== 'None') servicesToStart += ' db';
+                if (answers.caching === 'Redis') servicesToStart += ' redis';
+                if (answers.communication === 'Kafka') servicesToStart += ' zookeeper kafka';
+                
+                manualStartInstructions += `\n  docker-compose up -d${servicesToStart}  # Start infrastructure first\n  npm run dev`;
+            } else {
+                manualStartInstructions += `\n  npm run dev`;
+            }
+            
+            console.log(chalk.cyan(`\nNext steps:\n  cd ${answers.projectName}\n  npm install\n  docker-compose up\n-----------------------${manualStartInstructions}\n\n${chalk.yellow('Production (PM2):')}\n  npm run build\n  npm run deploy\n  npx pm2 logs`));
+
+        } catch (error) {
+            console.error(chalk.red('Error generating project:'), error);
+            process.exit(1);
+        }
+    });
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}

package/lib/generator.js

@@ -1,7 +1,7 @@
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { setupProjectDirectory, copyBaseStructure, copyCommonFiles } from './modules/project-setup.js';
-import { renderPackageJson, renderDockerCompose, renderReadme, renderDockerfile, renderProfessionalConfig, setupCiCd, renderTestSample, renderEnvExample, renderPm2Config } from './modules/config-files.js';
+import { renderPackageJson, renderDockerCompose, renderReadme, renderDockerfile, renderProfessionalConfig, setupCiCd, renderTestSample, renderEnvExample, renderPm2Config, renderAiNativeFiles } from './modules/config-files.js';
 import { renderIndexFile, renderEnvConfig, renderErrorMiddleware, renderDynamicComponents, renderSwaggerConfig, setupViews as setupSrcViews, processAllTests } from './modules/app-setup.js';
 import { setupDatabase } from './modules/database-setup.js';
 import { setupKafka, setupViews } from './modules/kafka-setup.js';
@@ -81,6 +81,9 @@ export const generateProject = async (config) => {
     await renderProfessionalConfig(templatesDir, targetDir, config);
     await renderTestSample(templatesDir, targetDir, config);
 
+    // 13.5 AI-Native Scaffolding
+    await renderAiNativeFiles(templatesDir, targetDir, config);
+
     // 14. CI/CD
     await setupCiCd(templatesDir, targetDir, config);
 
@@ -114,6 +117,13 @@ export const generateProject = async (config) => {
       ✅  Docker: Production-ready multi-stage build
       ${config.ciProvider !== 'None' ? `✅  CI/CD: ${config.ciProvider} Workflow ready` : '❌  CI/CD: Skipped (User preferred)'}
 
+      ----------------------------------------------------
+      🚀  Project is AI-Ready!
+      ----------------------------------------------------
+      🤖  We detected you are using AI tools. 
+      📍  Use Cursor? We've configured '.cursorrules' for you.
+      📍  Use ChatGPT/Gemini? Check the 'prompts/' folder for Agent Skills.
+
       ----------------------------------------------------
       👉  Next Steps:
       ----------------------------------------------------

package/lib/modules/config-files.js

@@ -49,6 +49,31 @@ export const renderProfessionalConfig = async (templatesDir, targetDir, config)
     await fs.writeFile(path.join(targetDir, 'jest.config.js'), jestContent);
 };
 
+export const renderAiNativeFiles = async (templatesDir, targetDir, config) => {
+    // 1. .cursorrules
+    const cursorRulesPath = path.join(targetDir, '.cursorrules');
+    const cursorRulesTemplate = await fs.readFile(path.join(templatesDir, 'common', '.cursorrules.ejs'), 'utf-8');
+    const cursorRulesContent = ejs.render(cursorRulesTemplate, { ...config });
+    await fs.writeFile(cursorRulesPath, cursorRulesContent);
+
+    // 2. prompts/
+    const promptsDirTarget = path.join(targetDir, 'prompts');
+    await fs.ensureDir(promptsDirTarget);
+    
+    const promptsSourceDir = path.join(templatesDir, 'common', 'prompts');
+    const promptFiles = await fs.readdir(promptsSourceDir);
+    
+    for (const file of promptFiles) {
+        if (file.endsWith('.ejs')) {
+            const templatePath = path.join(promptsSourceDir, file);
+            const targetFilePath = path.join(promptsDirTarget, file.replace('.ejs', ''));
+            const templateContent = await fs.readFile(templatePath, 'utf-8');
+            const renderedContent = ejs.render(templateContent, { ...config });
+            await fs.writeFile(targetFilePath, renderedContent);
+        }
+    }
+};
+
 export const setupCiCd = async (templatesDir, targetDir, config) => {
     const { ciProvider } = config;
     if (ciProvider === 'GitHub Actions') {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nodejs-quickstart-structure",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "type": "module",
-  "description": "A CLI to scaffold Node.js microservices with MVC or Clean Architecture",
+  "description": "The ultimate nodejs quickstart structure CLI to scaffold Node.js microservices with MVC or Clean Architecture",
   "main": "bin/index.js",
   "bin": {
     "nodejs-quickstart": "./bin/index.js"
@@ -16,12 +16,17 @@
   },
   "keywords": [
     "nodejs",
+    "node",
+    "quickstart",
+    "structure",
     "cli",
     "scaffold",
     "mvc",
     "clean-architecture",
     "microservices",
-    "backend"
+    "backend",
+    "generator",
+    "boilerplate"
   ],
   "author": "Pau Dang <[EMAIL_ADDRESS]>",
   "repository": {

package/templates/common/.cursorrules.ejs

@@ -0,0 +1,60 @@
+# Cursor AI Coding Rules for <%= projectName %>
+
+## Project Context
+You are an expert working on **<%= projectName %>**.
+- **Project Goal**: [Replace this with your business logic, e.g., E-commerce API]
+- **Language**: <%= language %>
+- **Architecture**: <%= architecture %>
+- **Database**: <%= database %>
+- **Communication**: <%= communication %>
+
+## Excluded Files/Folders
+When indexing or searching the workspace, ignore the following paths to prevent context pollution:
+- `node_modules/`
+- `dist/`
+- `build/`
+- `coverage/`
+- `.git/`
+
+## Strict Rules
+
+### 1. Testing First
+- Every new service or controller method MUST have a test file in `tests/`.
+- **Coverage Gate**: Aim for > 70% coverage (Statement/Line/Function/Branch).
+- **Format**: Use Jest with the AAA (Arrange, Act, Assert) pattern.
+- **Isolation**: Mock external dependencies (DB, Redis, etc.) using `jest.mock()`.
+
+### 2. Error Handling
+- Do NOT use generic `Error`.
+- Use custom classes from `src/errors/` (e.g., `ApiError`, `NotFoundError`, `BadRequestError`).
+<% if (language === 'TypeScript') { -%>
+- Use `HTTP_STATUS` constants from `@/utils/httpCodes` for status codes.
+<% } else { -%>
+- Use `HTTP_STATUS` constants from `../utils/httpCodes.js` for status codes.
+<% } -%>
+
+### 3. File Naming & Style
+- **Controllers**: camelCase (e.g., `userController.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+- **Services**: camelCase (e.g., `userService.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+- **Routes**: camelCase (e.g., `userRoutes.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+<% if (language === 'TypeScript') { -%>
+- **Imports**: Use path aliases (e.g., `@/services/...`) instead of relative paths.
+- **Typing**: Ensure strong typing for interfaces and DTOs. Do not use `any` unless absolutely necessary.
+<% } else { -%>
+- **Imports**: Use relative paths as dictated by the directory structure.
+<% } -%>
+
+### 4. Architecture Standards
+<% if (architecture === 'Clean Architecture') { -%>
+- Enforce strict separation of concerns:
+  - `domain`: Entities and enterprise business rules.
+  - `usecases`: Application business rules.
+  - `interfaces`: Controllers and Routes.
+  - `infrastructure`: Frameworks, Database, Caching, and Web Server.
+- Dependencies point inward toward the `domain`.
+<% } else { -%>
+- Enforce MVC standards:
+  - `models`: Data layer.
+  - `controllers`: Request handlers and business logic.
+  - `routes`: Define endpoints routing to controllers.
+<% } -%>

package/templates/common/.dockerignore

@@ -8,3 +8,5 @@ README.md
 docker-compose.yml
 test_results.log
 flyway/sql
+.cursorrules
+prompts

package/templates/common/.gitlab-ci.yml.ejs

@@ -12,24 +12,24 @@ cache:
 
 install_dependencies:
   stage: .pre
-  image: node:18-alpine
+  image: node:22-alpine
   script:
     - npm ci
 
 lint_code:
   stage: lint
-  image: node:18-alpine
+  image: node:22-alpine
   script:
     - npm run lint
 
 run_tests:
   stage: test
-  image: node:18-alpine
+  image: node:22-alpine
   script:
-    - npm test
+    - npm run test:coverage
 
 build_app:
   stage: build
-  image: node:18-alpine
+  image: node:22-alpine
   script:
     - npm run build --if-present

package/templates/common/Jenkinsfile.ejs

@@ -21,7 +21,7 @@ pipeline {
 
         stage('Test') {
             steps {
-                sh 'npm test'
+                sh 'npm run test:coverage'
             }
         }
 

package/templates/common/README.md.ejs

@@ -217,4 +217,14 @@ docker-compose down
 -   **Helmet**: Sets secure HTTP headers.
 -   **CORS**: Configured for cross-origin requests.
 -   **Rate Limiting**: Protects against DDoS / Brute-force.
--   **HPP**: Prevents HTTP Parameter Pollution attacks.
+-   **HPP**: Prevents HTTP Parameter Pollution attacks.
+
+
+## 🤖 AI-Native Development
+
+This project is "AI-Ready" out of the box. We have pre-configured industry-leading AI context files to bridge the gap between "Generated Code" and "AI-Assisted Development."
+
+- **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.

package/templates/common/_github/workflows/ci.yml

@@ -1,5 +1,8 @@
 name: Node.js CI
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+
 on:
   push:
     branches: [ "main" ]
@@ -13,13 +16,13 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x]
+        node-version: [20.x, 22.x]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
         cache: 'npm'
@@ -31,7 +34,7 @@ jobs:
       run: npm run lint
       
     - name: Run Tests
-      run: npm test
+      run: npm run test:coverage
       
     - name: Build
       run: npm run build --if-present

package/templates/common/prompts/add-feature.md.ejs

@@ -0,0 +1,26 @@
+# Add New Feature
+
+I want to add a new feature to the existing application. 
+Please follow the strict standards defined in the project context.
+
+## Feature Description
+[INSERT EXPLANATION OF WHAT YOU WANT TO ADD HERE]
+
+## Implementation Guidelines
+
+Please provide the code implementation following these steps:
+
+1. **Plan first**: Outline the files you need to create/modify and the logic they'll contain.
+<% if (architecture === 'Clean Architecture') { -%>
+2. **Domain/Entity**: Define the core entity structure or interfaces if applicable.
+3. **Use Case**: Implement the business logic handling the feature.
+4. **Adapter (Controller & Route)**: Create the necessary endpoints and validate input.
+5. **Infrastructure (Repository)**: Implement database queries or external service calls.
+<% } else { -%>
+2. **Model**: Define the database schema/model if applicable.
+3. **Controller**: Implement the business logic and request handling.
+4. **Route**: Create the API endpoints and wire them to the controller.
+<% } -%>
+6. **Testing**: Write comprehensive Jest unit tests covering the "Happy Path" and "Edge Cases/Errors" (AAA pattern). Remember, our coverage requirement is > 70%!
+
+Please provide the plan first so I can review it before we write the code.

package/templates/common/prompts/project-context.md.ejs

@@ -0,0 +1,43 @@
+# Project Context
+
+Hello AI! I am working on a Node.js project. Here is the context to help you understand the architecture, domain, and standards.
+
+## Domain Overview
+**Project Name**: <%= projectName %>
+You are an expert working on **<%= projectName %>**.
+**Project Goal**: [Replace this with your business logic, e.g., E-commerce API]
+*(Keep this goal in mind when writing business logic, proposing data schemas, or considering edge cases like security and performance.)*
+
+## Tech Stack
+- **Language**: <%= language %>
+- **Architecture**: <%= architecture %>
+- **Database**: <%= database %>
+- **Communication Protocol**: <%= communication %>
+<% if (caching !== 'None') { -%>
+- **Caching**: <%= caching %>
+<% } -%>
+
+## High-Level Architecture
+<% if (architecture === 'Clean Architecture') { -%>
+We use Clean Architecture. The project separates concerns into:
+- `src/domain`: Core entities and rules. No external dependencies.
+- `src/usecases`: Application business logic.
+- `src/interfaces`: Adapters (Controllers, Routes) that mediate between the outside world and use cases.
+- `src/infrastructure`: External tools (Database, Web Server, Config, Caching).
+<% } else { -%>
+We use the MVC (Model-View-Controller) pattern.
+- `src/models`: Database schemas/models.
+- `src/controllers`: Handling incoming requests and implementing business logic.
+- `src/routes`: API endpoints mapped to controllers.
+<% } -%>
+
+## Core Standards
+1. **Testing**: We enforce > 70% coverage. Tests use Jest and the AAA (Arrange, Act, Assert) pattern.
+2. **Error Handling**: We use centralized custom errors (e.g., `ApiError`) and global error middleware. Status codes come from standard constants, not hardcoded numbers.
+3. **Paths & Naming**:
+<% if (language === 'TypeScript') { -%>
+   - We use `@/` path aliases for internal imports.
+<% } -%>
+   - Files are mostly `camelCase`.
+
+Please acknowledge you understand this context by saying "Context loaded successfully! How can I help you build the <%= projectName %>?"

package/templates/common/prompts/troubleshoot.md.ejs

@@ -0,0 +1,28 @@
+# Troubleshoot Error
+
+I am encountering an error in the <%= projectName %> application. Please help me diagnose and fix it based on our architectural standards.
+
+## The Error Log / Issue Description
+\`\`\`
+[PASTE YOUR ERROR LOG OR DESCRIBE THE ISSUE HERE]
+\`\`\`
+
+## Context Variables
+- **Architecture**: <%= architecture %>
+- **Language**: <%= language %>
+
+## Guidelines for Fixing
+
+When analyzing this error, please keep these project standards in mind:
+
+1. **Centralized Error Handling**: 
+   - Ensure the error uses the standard custom error classes from `src/errors/` (e.g., `ApiError`, `NotFoundError`, `BadRequestError`).
+   - If an error occurs in a controller, it should be passed to the global error middleware via `throw` (for async handlers, or `next(error)` in MVC).
+2. **Standard Status Codes**:
+   - Verify that appropriate status codes from `httpCodes` are being used correctly, rather than generic 500s unless unexpected.
+3. **Dependencies**:
+   - Check if this is a connection issue (e.g., Database, Kafka, Redis) and see if our standard configuration or health checks provide hints.
+4. **Fix Suggestion**:
+   - Explain *why* the error happened.
+   - Provide a targeted code fix matching our coding style (<%= language %>, <%= architecture %>).
+   - Only modify what is strictly necessary to solve the issue.