docs: update README and Swagger UI docs for input/output models and improved API documentation

Author: frckbrice

.husky/pre-push

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-yarn lint && yarn format 
+yarn lint && yarn format && yarn test

README.md

@@ -1,70 +1,57 @@
-![Clean Architecture Diagram](public/clean-architecture.png)
 
-# Digital Market Place API
+# Clean Architecture Node.js REST API Example
 
-A Node.js REST API for a digital marketplace, structured according to Uncle Bob's Clean Architecture principles. This project demonstrates separation of concerns, testability, and scalability by organizing code into distinct layers: Enterprise Business Rules, Application Business Rules, Interface Adapters, and Frameworks & Drivers.
+<div style="width:100%; text-align:center">
+  <img src="public/images/clean-code_arch.jpeg" width="600">
+</div>
 
-## Table of Contents
+**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.
 
-- [Introduction](#introduction)
-- [Architecture Overview](#architecture-overview)
-- [Features](#features)
-- [Getting Started](#getting-started)
-- [Project Structure](#project-structure)
-- [API Endpoints](#api-endpoints)
-- [Testing](#testing)
-- [Linting & Formatting](#linting--formatting)
-- [Docker & Docker Compose](#docker--docker-compose)
-- [CI/CD Workflow](#cicd-workflow)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
+## Stack
+- **Node.js** (Express.js) for the REST API
+- **MongoDB** (native driver) for persistence
+- **Jest** & **Supertest** for unit and integration testing
+- **ESLint** & **Prettier** for linting and formatting
+- **Docker** & **Docker Compose** for containerization
+- **GitHub Actions** for CI/CD
 
-## Introduction
+## 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.
+- **Security & Flexibility:** Infrastructure (DB, frameworks) can be swapped without touching business logic.
 
-This backend API allows users to register, authenticate, and interact with products, blogs, and ratings. It is designed for maintainability and extensibility, following Clean Architecture best practices.
-
-## Architecture Overview
-
-The project is organized into the following layers:
-
-- **Enterprise Business Rules**: Core business logic and domain models (`enterprise-business-rules/`).
-- **Application Business Rules**: Use cases and application-specific logic (`application-business-rules/`).
-- **Interface Adapters**: Controllers, database access, adapters, and middlewares (`interface-adapters/`).
-- **Frameworks & Drivers**: Express.js, MongoDB, and other external libraries.
+## 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)
   validate-models/    # Validation logic for domain models
 application-business-rules/
-  use-cases/          # Application use cases (products, user)
+  use-cases/          # Application use cases (products, user, blog)
 interface-adapters/
-  controllers/        # Route controllers for products, users
+  controllers/        # Route controllers for products, users, blogs
   database-access/    # DB connection and data access logic
   adapter/            # Adapters (e.g., request/response)
   middlewares/        # Auth, logging, error handling
 routes/               # Express route definitions
 public/               # Static files and HTML views
 ```
 
-## Features
-
-- User registration and authentication (JWT)
-- Product CRUD operations
-- Blog and rating management
-- Role-based access control (admin, blocked users)
-- Input validation and error handling
-- Modular, testable codebase
-
 ## Getting Started
 
 ### Prerequisites
-
 - Node.js (v18+ recommended)
 - MongoDB instance (local or cloud)
 
 ### Installation
-
 1. Clone the repository:
    ```bash
    git clone <repo-url>
@@ -74,10 +61,10 @@ public/               # Static files and HTML views
    ```bash
    yarn install
    ```
-3. Create a `.env` file in the root with your environment variables (see `.env.example` if available):
+3. Create a `.env` file in the root with your environment variables:
    ```env
    PORT=5000
-   MONGODB_URI=mongodb://localhost:27017/your-db
+   MONGO_URI=mongodb://localhost:27017/your-db
    JWT_SECRET=your_jwt_secret
    ```
 4. Start the server:
@@ -87,52 +74,34 @@ public/               # Static files and HTML views
    yarn start
    ```
 
-The server will run at [http://localhost:5000](http://localhost:5000).
-
-## Project Structure
-
-- `index.js` - Main entry point, sets up Express, routes, and middleware
-- `routes/` - Express route definitions for products, users, blogs
-- `interface-adapters/` - Controllers, DB access, adapters, and middleware
-- `application-business-rules/` - Use cases for products and users
-- `enterprise-business-rules/` - Domain models and validation logic
-- `public/` - Static HTML views (landing page, 404)
-
 ## API Endpoints
-
-### Products
-
+See the `routes/` directory for all endpoints. Example:
 - `POST   /products/` - Create a new product
 - `GET    /products/` - Get all products
-- `GET    /products/:productId` - Get a product by ID
-- `PUT    /products/:productId` - Update a product
-- `DELETE /products/:productId` - Delete a product
-- `POST   /products/:productId/:userId/rating` - Rate a product
-
-### Users & Auth
-
 - `POST   /users/register` - Register a new user
 - `POST   /users/login` - User login
-- `GET    /users/profile` - Get user profile (auth required)
-
-### Blogs
-
 - `GET    /blogs/` - Get all blogs
-- `POST   /blogs/` - Create a new blog
 
-> More endpoints and details can be found in the route files under `routes/`.
+## 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:**
+  - Each resource (User, Product, Blog) has two main schemas:
+    - **Input Model** (e.g., `UserInput`, `ProductInput`, `BlogInput`): What the client sends when creating or updating a resource. Only includes fields the client can set (e.g., no `_id`, no server-generated fields).
+    - **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.
 
 ## Testing
-
-- Tests are written using [Jest](https://jestjs.io/) and [Supertest](https://github.com/visionmedia/supertest).
+- **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:
   ```bash
   yarn test
   ```
-- Test files are located in the `tests/` directory.
+- Test files are in the `tests/` directory.
 
 ## Linting & Formatting
-
 - Lint your code:
   ```bash
   yarn lint
@@ -144,33 +113,23 @@ The server will run at [http://localhost:5000](http://localhost:5000).
 - 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
   ```
 - The app will be available at [http://localhost:5000](http://localhost:5000).
-- The MongoDB service runs at `mongodb://localhost:27017/cleanarchdb`.
+- The MongoDB service runs at `mongodb://mongo:27017/cleanarchdb` (inside Docker) or `localhost:27017` (locally).
 - To stop and remove containers, networks, and volumes:
   ```bash
   docker-compose down -v
   ```
 
 ## CI/CD Workflow
-
 - GitHub Actions workflow is set up in `.github/workflows/ci-cd.yml`.
-- On push to `main`, the workflow:
-  - Installs dependencies
-  - Lints and formats code
-  - Runs tests
-  - Builds a Docker image
-  - Pushes the image to Docker Hub (update credentials and repo in workflow and GitHub secrets)
+- On push to `main`, the workflow lints, tests, builds, and pushes a Docker image.
 
 ## Troubleshooting
-
-- Common issues and solutions are documented in [troubleshooting.md](./troubleshooting.md).
-- Please add new issues and solutions as you encounter them.
+- See [troubleshooting.md](./troubleshooting.md) for common issues and solutions.
 
 ## License
-
-This project is licensed under the ISC License. See the [LICENSE](LICENSE) file for details.
+ISC License. See [LICENSE](LICENSE).

enterprise-business-rules/entities/blog-model.js

@@ -1,19 +1,19 @@
 const blogValidation = require('../validate-models/blog-validation');
 
 module.exports = {
-  makeBlogModel: ({ blogValidation, logEvents }) => {
-    return async function makeBlog({ blogData }) {
-      try {
-        const validatedBlog = await blogValidation.blogPostValidation({
-          blogPostData: blogData,
-          errorHandlers: blogValidation,
-        });
-        // Add normalization or additional logic if needed
-        return Object.freeze(validatedBlog);
-      } catch (error) {
-        logEvents && logEvents(`${error.message}`, 'blog-model.log');
-        throw error;
-      }
-    };
-  },
+    makeBlogModel: ({ blogValidation, logEvents }) => {
+        return async function makeBlog({ blogData }) {
+            try {
+                const validatedBlog = await blogValidation.blogPostValidation({
+                    blogPostData: blogData,
+                    errorHandlers: blogValidation,
+                });
+                // Add normalization or additional logic if needed
+                return Object.freeze(validatedBlog);
+            } catch (error) {
+                logEvents && logEvents(`${error.message}`, 'blog-model.log');
+                throw error;
+            }
+        };
+    },
 };

index.js

@@ -7,10 +7,50 @@ const { dbconnection } = require('./interface-adapters/database-access/db-connec
 const errorHandler = require('./interface-adapters/middlewares/loggers/errorHandler.js');
 const { logger } = require('./interface-adapters/middlewares/loggers/logger.js');
 const createIndexFn = require('./interface-adapters/database-access/db-indexes.js');
+const swaggerUi = require('swagger-ui-express');
+const swaggerJSDoc = require('swagger-jsdoc');
+
+const PORT = process.env.PORT || 5000;
+
+const swaggerDefinition = {
+  openapi: '3.0.0',
+  info: {
+    title: 'Clean Architecture REST API',
+    version: '1.0.0',
+    description: 'API documentation for the Clean Architecture Node.js REST API',
+    contact: {
+      name: 'Avom Brice',
+      email: 'bricefrkc@gmail.com',
+    },
+  },
+  servers: [
+    {
+      url: `http://localhost:${PORT}`,
+      description: 'Local server API documentation',
+    },
+  ],
+  components: {
+    securitySchemes: {
+      bearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+      },
+    },
+  },
+  security: [{ bearerAuth: [] }],
+};
+
+const options = {
+  swaggerDefinition,
+  apis: [
+    './routes/*.js',
+  ],
+};
+const swaggerSpec = swaggerJSDoc(options);
 
 const app = express();
 
-const PORT = process.env.PORT || 5000;
 var cookieParser = require('cookie-parser');
 const corsOptions = require('./interface-adapters/middlewares/config/corsOptions.Js');
 
@@ -26,14 +66,20 @@ app.use(express.json());
 app.use(cookieParser());
 app.use(express.urlencoded({ extended: false }));
 
+// Register Swagger UI BEFORE any static or catch-all routes
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+
 // Use the new single entry point for all routes
 const mainRouter = require('./routes');
-app.use('/', mainRouter);
 
-app.use('/', (_, res) => {
+// Only serve index.html for the root path
+app.get('/', (_, res) => {
   res.sendFile(path.join(__dirname, 'public', 'views', 'index.html'));
 });
 
+app.use('/', mainRouter);
+
+
 //for no specified endpoint that is not found. this must after all the middlewares
 app.all('*', (req, res) => {
   res.status(404);

interface-adapters/controllers/products/index.js

@@ -1,28 +1,26 @@
-const { dbProductHandler } = require('../../database-access');
-
 const {
   createProductController,
-  deleteProductController,
-  updateProductController,
   findAllProductController,
   findOneProductController,
+  updateProductController,
+  deleteProductController,
   rateProductController,
   // findBestUserRaterController
-} = require('./product-controller')();
+} = require('./product-controller');
 
 const {
   createProductUseCaseHandler,
-  updateProductUseCaseHandler,
-  deleteProductUseCaseHandler,
   findAllProductUseCaseHandler,
   findOneProductUseCaseHandler,
+  updateProductUseCaseHandler,
+  deleteProductUseCaseHandler,
   rateProductUseCaseHandler,
-  // findBestUserRaterUseCaseHandler
 } = require('../../../application-business-rules/use-cases/products');
 const { makeHttpError } = require('../../validators-errors/http-error');
 
 const errorHandlers = require('../../validators-errors/errors');
 const { logEvents } = require('../../middlewares/loggers/logger');
+const { dbProductHandler } = require('../../database-access');
 
 const createProductControllerHandler = createProductController({
   createProductUseCaseHandler,
@@ -68,11 +66,9 @@ const rateProductControllerHandler = rateProductController({
 
 module.exports = {
   createProductControllerHandler,
-
-  updateProductControllerHandler,
-  deleteProductControllerHandler,
   findAllProductControllerHandler,
   findOneProductControllerHandler,
+  updateProductControllerHandler,
+  deleteProductControllerHandler,
   rateProductControllerHandler,
-  // findBestUserRaterControllerHandler
 };