docs: update README and troubleshooting guide for flexibility and recent changes

Author: frckbrice

README.md

@@ -1,14 +1,15 @@
-
 # Clean Architecture Node.js REST API Example
 
 <div style="width:100%; text-align:center">
   <img src="public/images/clean-code_arch.jpeg" width="600">
 </div>
 
 **Objective:**
+
 > This project demonstrates how to apply Uncle Bob's Clean Architecture principles in a Node.js REST API. It is designed as an educational resource to help developers structure their projects for maximum testability, maintainability, and scalability. The codebase shows how to keep business logic independent from frameworks, databases, and delivery mechanisms.
 
 ## Stack
+
 - **Node.js** (Express.js) for the REST API
 - **MongoDB** (MongoClient) for persistence
 - **Jest** & **Supertest** for unit and integration testing
@@ -17,6 +18,7 @@
 - **GitHub Actions** for CI/CD
 
 ## Why Clean Architecture?
+
 - **Separation of Concerns:** Each layer has a single responsibility and is independent from others.
 - **Dependency Rule:** Data and control flow from outer layers (e.g., routes/controllers) to inner layers (use cases, domain), never the reverse. Lower layers are unaware of upper layers.
 - **Testability:** Business logic can be tested in isolation by injecting dependencies (e.g., mock DB handlers) from above. No real database is needed for unit tests.
@@ -26,13 +28,15 @@
 > This project demonstrates that your core business logic is never tied to any specific framework, ORM, or database. You can switch from Express to Fastify, MongoDB to PostgreSQL, or even move to a serverless environment—without rewriting your business rules. The architecture ensures your codebase adapts easily to new technologies, making future migrations and upgrades painless. This is true Clean Architecture in action: your app’s heart beats independently of any tool or vendor.
 
 ## How Testing Works
+
 - **Unit tests** inject mocks for all dependencies (DB, loggers, etc.) into use cases and controllers. This means you can test all business logic without a real database or server.
 - **Integration tests** can use a real or in-memory database, but the architecture allows you to swap these easily.
 - **Example:**
   - The product use case receives a `createProductDbHandler` as a parameter. In production, this is the real DB handler; in tests, it's a mock function.
   - Lower layers (domain, use cases) never import or reference Express, MongoDB, or any framework code.
 
 ## Project Structure
+
 ```
 enterprise-business-rules/
   entities/           # Domain models (User, Product, Rating, Blog)
@@ -51,10 +55,12 @@ public/               # Static files and HTML views
 ## Getting Started
 
 ### Prerequisites
+
 - Node.js (v18+ recommended)
 - MongoDB instance (local or cloud)
 
 ### Installation
+
 1. Clone the repository:
    ```bash
    git clone <repo-url>
@@ -78,14 +84,17 @@ public/               # Static files and HTML views
    ```
 
 ## API Endpoints
+
 See the `routes/` directory for all endpoints. Example:
+
 - `POST   /products/` - Create a new product
 - `GET    /products/` - Get all products
 - `POST   /users/register` - Register a new user
 - `POST   /users/login` - User login
 - `GET    /blogs/` - Get all blogs
 
 ## API Documentation & Models (Swagger UI)
+
 - Interactive API docs are available at `/api-docs` when the server is running.
 - All endpoints are documented with request/response schemas using Swagger/OpenAPI.
 - **Models:**
@@ -94,11 +103,10 @@ See the `routes/` directory for all endpoints. Example:
     - **Output Model** (e.g., `User`, `Product`, `Blog`): What the API returns. Includes all fields, including those generated by the server (e.g., `_id`, `role`, etc.).
 - This separation improves security, clarity, and validation.
 - You can view and try all models in the "Schemas" section of Swagger UI.
-- check at http://localhost:5000/api-docs.  /* (:5000 depend on you chosen port) */
-
-
+- check at http://localhost:5000/api-docs. /_ (:5000 depend on you chosen port) _/
 
 ## Testing
+
 - **Unit tests** (Jest): Test business logic in isolation by injecting mocks for all dependencies. No real DB required.
 - **Integration tests** (Supertest): Test the full stack, optionally with a real or in-memory DB.
 - To run all tests:
@@ -108,6 +116,7 @@ See the `routes/` directory for all endpoints. Example:
 - Test files are in the `tests/` directory.
 
 ## Linting & Formatting
+
 - Lint your code:
   ```bash
   yarn lint
@@ -119,6 +128,7 @@ See the `routes/` directory for all endpoints. Example:
 - Prettier and ESLint are enforced on pre-push via Husky and lint-staged.
 
 ## Docker & Docker Compose
+
 - Build and run the app with MongoDB using Docker Compose:
   ```bash
   docker-compose up --build
@@ -131,11 +141,14 @@ See the `routes/` directory for all endpoints. Example:
   ```
 
 ## CI/CD Workflow
+
 - GitHub Actions workflow is set up in `.github/workflows/ci-cd.yml`.
 - On push to `main`, the workflow lints, tests, builds, and pushes a Docker image.
 
 ## Troubleshooting
+
 - See [troubleshooting.md](./troubleshooting.md) for common issues and solutions.
 
 ## License
+
 ISC License. See [LICENSE](LICENSE).

troubleshooting.md

@@ -5,10 +5,12 @@
 ## 0. Express Downgrade & Docker Restart for Compatibility
 
 **Symptom:**
+
 - Swagger UI or other middleware fails with errors related to `path-to-regexp` or route registration after upgrading Express (e.g., Express v5 beta).
 - Docker Compose or MongoDB connection errors after system or Docker Desktop restart.
 
 **Solution:**
+
 - Downgrade Express to v4 (e.g., `npm install express@4` or `yarn add express@4`).
 - Stop Docker Desktop completely (kill all Docker processes if needed), then restart Docker Desktop and wait for it to be fully running.
 - Run `docker-compose up -d` to restart all services.
@@ -19,15 +21,18 @@
 ## 0.1. Swagger UI Not Working
 
 **Symptom:**
+
 - Navigating to `/api-docs` returns a 404, blank page, or error.
 - Swagger UI does not load or shows a path-to-regexp or route registration error.
 
 **Possible Causes:**
+
 - Swagger UI route is registered after a catch-all or error handler route in Express.
 - Express version incompatibility (v5 beta is not supported by swagger-ui-express).
 - Incorrect Swagger JSDoc configuration or missing comments.
 
 **Next Steps:**
+
 - Ensure `app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))` is registered before any catch-all or error handler middleware.
 - Confirm Express is v4, not v5.
 - Check for valid Swagger JSDoc comments above all route definitions.