From 67015e37e8a20832cb530b17117586da49d0142b Mon Sep 17 00:00:00 2001 From: KariMuhammad Date: Fri, 31 Jul 2026 16:34:05 +0300 Subject: [PATCH] docs: refresh project README --- README.md | 475 ++++++++++++++++++------------------------------------ 1 file changed, 154 insertions(+), 321 deletions(-) diff --git a/README.md b/README.md index 6f27c97..42d9a0a 100644 --- a/README.md +++ b/README.md @@ -1,348 +1,181 @@ -# eCommerceTS +# eCommerceTS API -[![Stars](https://img.shields.io/github/stars/KariMuhammad/eCommerceTS?style=social)](https://github.com/KariMuhammad/eCommerceTS) -[![Forks](https://img.shields.io/github/forks/KariMuhammad/eCommerceTS?style=social)](https://github.com/KariMuhammad/eCommerceTS) -[![Primary Language](https://img.shields.io/github/languages/top/KariMuhammad/eCommerceTS)](https://github.com/KariMuhammad/eCommerceTS) -[![License](https://img.shields.io/github/license/KariMuhammad/eCommerceTS)](https://github.com/KariMuhammad/eCommerceTS) +A modular e-commerce REST API built with Express, TypeScript, and MongoDB. The project models the core domains of an online store and separates each domain into routes, validation, controllers, services, repositories, models, and types. -## Description +[API documentation](https://documenter.getpostman.com/view/23054100/2sAXqv61r7) ยท [Repository](https://github.com/KariMuhammad/eCommerceTS) -This project is a scalable backend API for an e-commerce platform, built with Node.js and TypeScript. It provides a comprehensive set of RESTful endpoints to manage users, authentication, products, brands, categories, blogs, wishlists, ratings, coupons, orders, and more. It leverages technologies like JWT for authentication, MongoDB for data storage, and Cloudinary for file uploads. (Under Development...) - -## Table of Contents - -- [Description](#description) -- [Features](#features) -- [Tech Stack](#tech-stack) -- [Installation](#installation) -- [Usage](#usage) -- [Project Structure](#project-structure) -- [API Endpoints](#api-endpoints) -- [Contributing](#contributing) -- [License](#license) -- [Important Links](#important-links) -- [Footer](#footer) +> The API is under active development. The default GitHub branch is `goal`. ## Features -- ๐Ÿ” **Secure Authentication and Authorization:** JWT-based authentication for users and administrators. -- ๐Ÿ‘ค **User Management:** Comprehensive endpoints for managing users, including registration, login, profile updates, and password management. -- ๐Ÿ›๏ธ **Product Catalog:** APIs to manage products, categories, and brands with advanced filtering capabilities. -- ๐Ÿ›’ **Shopping Cart and Order Management:** Functionality for managing shopping carts, applying coupons, and processing orders. -- โค๏ธ **Wishlist and Ratings:** Support for wishlists and product ratings to enhance the user experience. -- ๐Ÿ“ **Blog Management:** APIs for creating, updating, and managing blog posts and categories. -- ๐ŸŽ **Coupon System:** Implementation of coupons and discounts with usage limits and expiration dates. -- โ˜๏ธ **File Uploads:** Integration with Cloudinary for handling file uploads. -- โœ‰๏ธ **Email Sending:** Email service for sending password reset links and other notifications. -- โš™๏ธ **Query Features:** Advanced filtering, sorting, pagination, and search capabilities. -- ๐Ÿ›๏ธ **Modular Design:** Well-organized code structure for maintainability and scalability. -- ๐Ÿ›ก๏ธ **Error Handling:** Centralized error handling for consistent error responses. - -## Tech Stack - -- **TypeScript**: Primary language for type safety and maintainability. -- **Node.js**: Runtime environment for the backend. -- **Express**: Web framework for building the API. -- **Mongoose**: ODM for MongoDB. -- **JWT**: For authentication and authorization. -- **Cloudinary**: Cloud storage for image uploads. -- **bcrypt**: For password hashing. -- **nodemailer**: For sending emails. -- **express-validator**: For request validation. -- **dotenv**: For managing environment variables. -- **cors**: For handling Cross-Origin Resource Sharing. -- **morgan**: For request logging. -- **cookie-parser**: For parsing cookies. -- **sharp**: For image processing. -- **slugify**: For generating URL-friendly slugs. - -## Installation - -1. **Clone the repository:** - - ```bash - git clone https://github.com/KariMuhammad/eCommerceTS.git - cd eCommerceTS - ``` - -2. **Install dependencies:** - - ```bash - npm install - # or - yarn install - ``` - -3. **Configure environment variables:** - - Create a `.env` file based on `.env.example` and fill in the necessary values, such as: - - ``` - SERVER_DOMAIN=http://localhost - SERVER_PORT=5000 - DB_ATLAS_URI=mongodb+srv://:@/?retryWrites=true&w=majority - DB_NAME=ecommerce - SECRET_KEY=your-secret-key - REFRESH_TOKEN_KEY=your-refresh-token-key - MAIL_ACCOUNT=your-email@gmail.com - MAIL_PASSWORD_APP=your-email-app-password - CLOUDINARY_CLOUD_NAME=your-cloud-name - CLOUDINARY_API_KEY=your-api-key - CLOUDINARY_API_SECRET=your-api-secret - CLOUDINARY_RESOURCE_LINK=your-resource-link - CORS_ORIGIN=http://localhost:3000 - ``` - -4. **Set up the database:** - - Ensure MongoDB is running and the connection URI in `.env` is correct. You can use a local MongoDB instance or a cloud-based service like MongoDB Atlas. - -5. **Run the development server:** - - ```bash - npm run dev - # or - yarn dev - ``` - -6. **Build for production:** - - ```bash - npm run build - ``` - -7. **Start the production server:** - - ```bash - npm start - ``` - -## Usage - -### Real-World Use Cases - -- **Building an E-commerce Platform:** - This project provides a robust backend API for managing products, users, orders, and more, making it suitable for building a complete e-commerce solution. - -- **Developing a Mobile Shopping App:** - The API can be used to power a mobile shopping app, allowing users to browse products, add items to their cart, and place orders. - -- **Creating a Blog for an Online Store:** - The blog management feature can be used to create a blog for an online store, allowing you to share news, promotions, and other content with your customers. - -### How to Use the Project - -1. **Start the server:** - Run the development server using `npm run dev2` or the production server using `npm start`. - -2. **Access the API endpoints:** - Use tools like Postman or Insomnia to send requests to the API endpoints. The base URL will be something like `http://localhost:5000` (depending on your `.env` configuration). +- Access and refresh-token authentication with password recovery +- Role-aware authorization for customers, vendors, and administrators +- Product, category, brand, color, and image management +- Filtering, search, sorting, field selection, and pagination through a shared query layer +- Shopping carts, quantity updates, coupons, discounts, and checkout calculation +- Orders and refund domain scaffolding +- Product reviews and ratings +- Wishlists +- Blog posts and blog categories +- Contact messages +- Cloudinary-backed image processing and uploads +- Centralized API errors, validation, logging, and CORS configuration + +## Architecture + +Feature code lives under `src/features/`: + +```text +src/ +โ”œโ”€โ”€ common/ # Errors, query helpers, router, storage, email +โ”œโ”€โ”€ features/ +โ”‚ โ”œโ”€โ”€ auth/ +โ”‚ โ”œโ”€โ”€ products/ +โ”‚ โ”œโ”€โ”€ category/ +โ”‚ โ”œโ”€โ”€ brands/ +โ”‚ โ”œโ”€โ”€ colors/ +โ”‚ โ”œโ”€โ”€ carts/ +โ”‚ โ”œโ”€โ”€ coupons/ +โ”‚ โ”œโ”€โ”€ orders/ +โ”‚ โ”œโ”€โ”€ reviews/ +โ”‚ โ”œโ”€โ”€ wishlist/ +โ”‚ โ”œโ”€โ”€ blogs/ +โ”‚ โ”œโ”€โ”€ blog-category/ +โ”‚ โ”œโ”€โ”€ contact/ +โ”‚ โ””โ”€โ”€ user/ +โ”œโ”€โ”€ app.ts # Express application and middleware +โ””โ”€โ”€ server.ts # HTTP server entry point +``` -3. **Authentication:** - - Register a new user: `POST /auth/register` - - Login a user: `POST /auth/login` +Most domains use the following flow: - After successful login, you will receive an access token. Include this token in the `Authorization` header of subsequent requests. +```text +HTTP route -> validation/middleware -> controller -> service -> repository -> Mongoose model +``` -4. **Product Management:** - - Get all products: `GET /products` - - Create a new product (Admin only): `POST /products` +Shared abstractions in `src/common/` provide resource routing, reusable persistence operations, query features, file storage, and consistent errors. -5. **Cart Management:** - - Add an item to the cart: `POST /cart/add` - - Apply a coupon to the cart: `POST /cart/apply-discount` +## Tech Stack -6. **Password Reset** - - Forgot Password: `POST /auth/forgot-password` - - Reset Password: `POST /auth/reset-password` +- Node.js and Express 4 +- TypeScript +- MongoDB and Mongoose +- JSON Web Tokens and bcrypt +- Express Validator +- Multer, Sharp, and Cloudinary +- Nodemailer +- Morgan, CORS, and cookie-parser -7. **User Profile** - - Accessing user profile: `GET /auth/profile` +## Getting Started -8. **Coupon Management** - - Creating a new coupon (Admin only): `POST /coupons` +### Prerequisites -9. **Product Ratings** - - Adding a product rating: `POST /products/:productId/ratings` +- Node.js 18+ +- npm +- MongoDB locally or a MongoDB Atlas database +- Cloudinary credentials for image uploads +- An SMTP/app-password account for email flows -## Project Structure +### Installation -``` -โ”œโ”€โ”€ .env.example # Example environment variables -โ”œโ”€โ”€ .vscode # VS Code configuration -โ”œโ”€โ”€ config.ts # Configuration settings -โ”œโ”€โ”€ database # Database connection -โ”œโ”€โ”€ src -โ”‚ โ”œโ”€โ”€ @types # Custom TypeScript definitions -โ”‚ โ”œโ”€โ”€ common # Common utilities and middleware -โ”‚ โ”œโ”€โ”€ features # Feature modules -โ”‚ โ”‚ โ”œโ”€โ”€ auth # Authentication feature -โ”‚ โ”‚ โ”œโ”€โ”€ blogs # Blog feature -โ”‚ โ”‚ โ”œโ”€โ”€ brands # Brand feature -โ”‚ โ”‚ โ”œโ”€โ”€ carts # Cart feature -โ”‚ โ”‚ โ”œโ”€โ”€ category # Category feature -โ”‚ โ”‚ โ”œโ”€โ”€ colors # Color feature -โ”‚ โ”‚ โ”œโ”€โ”€ coupons # Coupon feature -โ”‚ โ”‚ โ”œโ”€โ”€ products # Product feature -โ”‚ โ”‚ โ”œโ”€โ”€ reviews # Reviews feature -โ”‚ โ”‚ โ”œโ”€โ”€ user # User feature -โ”‚ โ”‚ โ”œโ”€โ”€ wishlist # Wishlist feature -โ”‚ โ”‚ โ””โ”€โ”€ ... # Other features -โ”‚ โ”œโ”€โ”€ app.ts # Express application setup -โ”‚ โ””โ”€โ”€ server.ts # Server entry point -โ”œโ”€โ”€ package.json # Project dependencies and scripts -โ”œโ”€โ”€ tsconfig.json # TypeScript configuration -โ””โ”€โ”€ README.md # Project documentation +```bash +git clone https://github.com/KariMuhammad/eCommerceTS.git +cd eCommerceTS +npm install +cp .env.example .env ``` -## API Endpoints - -You can find the API documentation on Postman: - -[API Documentation](https://documenter.getpostman.com/view/23054100/2sAXqv61r7) - -Here's a brief overview of the available endpoints: - -### Authentication - -| Method | Endpoint | Description | -| :----- | :--------------------- | :------------------------------- | -| POST | `/auth/register` | Register a new user | -| POST | `/auth/login` | Log in an existing user | -| POST | `/auth/logout` | Log out the current user | -| POST | `/auth/refresh` | Refresh the access token | -| POST | `/auth/forgot-password` | Request a password reset | -| POST | `/auth/reset-password` | Reset the user's password | -| PATCH | `/auth/change-password` | Change the user's password | -| GET | `/auth/profile` | Get the user's profile | - -### Users - -| Method | Endpoint | Description | -| :----- | :--------------- | :----------------------- | -| GET | `/users` | Get all users | -| GET | `/users/:id` | Get a specific user | -| PUT | `/users/:id` | Update a user | -| DELETE | `/users/:id` | Delete a user | - -### Brands - -| Method | Endpoint | Description | -| :----- | :--------------- | :--------------------- | -| GET | `/brands` | Get all brands | -| GET | `/brands/:id` | Get a specific brand | -| POST | `/brands` | Create a new brand | -| PATCH | `/brands/:id` | Update a brand | -| DELETE | `/brands/:id` | Delete a brand | - -### Categories - -| Method | Endpoint | Description | -| :----- | :------------------ | :------------------------ | -| GET | `/category` | Get all categories | -| GET | `/category/:id` | Get a specific category | -| POST | `/category` | Create a new category | -| PATCH | `/category/:id` | Update a category | -| DELETE | `/category/:id` | Delete a category | - -### Products - -| Method | Endpoint | Description | -| :----- | :---------------- | :---------------------- | -| GET | `/products` | Get all products | -| GET | `/products/:id` | Get a specific product | -| POST | `/products` | Create a new product | -| PATCH | `/products/:id` | Update a product | -| DELETE | `/products/:id` | Delete a product | -| POST | `/products/:productId/ratings` | Add a product rating | - -### Blogs - -| Method | Endpoint | Description | -| :----- | :-------------- | :-------------------- | -| GET | `/blogs` | Get all blogs | -| GET | `/blogs/:id` | Get a specific blog | -| POST | `/blogs` | Create a new blog | -| PATCH | `/blogs/:id` | Update a blog | -| DELETE | `/blogs/:id` | Delete a blog | -| PATCH | `/blogs/:id/like` | Like a blog | -| PATCH | `/blogs/:id/unlike` | Unlike a blog | - -### Wishlist - -| Method | Endpoint | Description | -| :----- | :------------------ | :-------------------------------- | -| GET | `/wishlist` | Get all wishlist items | -| POST | `/wishlist/add` | Add product to wishlist | -| POST | `/wishlist/remove` | Remove product from wishlist | - -### Coupons - -| Method | Endpoint | Description | -| :----- | :--------------- | :--------------------- | -| GET | `/coupons` | Get all coupons | -| GET | `/coupons/:id` | Get a specific coupon | -| POST | `/coupons` | Create a new coupon | -| PATCH | `/coupons/:id` | Update a coupon | -| DELETE | `/coupons/:id` | Delete a coupon | -| POST | `/coupons/apply` | Apply a coupon | - -### Cart - -| Method | Endpoint | Description | -| :----- | :---------------- | :----------------------------- | -| GET | `/cart` | Get the user's cart | -| POST | `/cart/add` | Add item to the cart | -| POST | `/cart/remove` | Remove item from the cart | -| POST | `/cart/clear` | Clear the cart | -| PATCH | `/cart/increase` | Increase item quantity in cart | -| PATCH | `/cart/decrease` | Decrease item quantity in cart | -| POST | `/cart/apply-discount` | Apply a discount to cart | -| GET | `/cart/checkout` | Checkout | - -## Contributing - -Contributions are welcome! Please follow these steps: - -1. Fork the repository. -2. Create a new branch for your feature or bug fix. -3. Make your changes and commit them with descriptive messages. -4. Push your changes to your fork. -5. Submit a pull request to the main repository. +Configure these values in `.env`: + +| Variable | Purpose | +| --- | --- | +| `NODE_ENV` | Runtime mode, for example `development` | +| `SERVER_DOMAIN` | Server origin, for example `http://localhost` | +| `SERVER_PORT` | HTTP port, for example `5000` | +| `DB_ATLAS_URI` | MongoDB connection URI | +| `DB_NAME` | Database name | +| `SECRET_KEY` | Access-token signing secret | +| `REFRESH_TOKEN_KEY` | Refresh-token signing secret | +| `MAIL_ACCOUNT` | Sender email address | +| `MAIL_PASSWORD_APP` | Sender app password | +| `CLOUDINARY_CLOUD_NAME` | Cloudinary cloud name | +| `CLOUDINARY_API_KEY` | Cloudinary API key | +| `CLOUDINARY_API_SECRET` | Cloudinary API secret | +| `CLOUDINARY_RESOURCE_LINK` | Cloudinary delivery base URL | +| `CORS_ORIGIN` | Allowed frontend origin | + +Use long, unique values for token secrets and never commit the completed `.env` file. + +Start the development server: + +```bash +npm run dev2 +``` -## License +The API listens at `SERVER_DOMAIN:SERVER_PORT`. + +## API Overview + +The current application mounts feature routes at the server root. + +| Domain | Base path | Access | +| --- | --- | --- | +| Authentication | `/auth` | Public and authenticated actions | +| Users | `/users` | Administrator | +| Products | `/products` | Public reads; vendor/admin writes | +| Categories | `/category` | Public reads; admin writes | +| Brands | `/brands` | Public reads; admin writes | +| Colors | `/colors` | Resource operations | +| Reviews | `/products/:productId/reviews` | Product-scoped | +| Wishlist | `/wishlist` | Authenticated | +| Cart | `/cart` | Authenticated | +| Coupons | `/coupons` | Admin management and cart usage | +| Orders | `/orders` | Authenticated | +| Blogs | `/blogs` | Public reads and protected writes | +| Blog categories | `/blog-category` | Resource operations | +| Contact | `/contact` | Contact-message operations | + +Representative authentication routes: + +```text +POST /auth/register +POST /auth/login +POST /auth/refresh +POST /auth/logout +POST /auth/forgot-password +POST /auth/reset-password +PATCH /auth/change-password +GET /auth/profile +``` -This project has no license. +Representative cart routes: + +```text +GET /cart +POST /cart/add +POST /cart/remove +POST /cart/clear +PATCH /cart/increase +PATCH /cart/decrease +POST /cart/apply-discount +GET /cart/checkout +``` -## Important Links +See the [Postman documentation](https://documenter.getpostman.com/view/23054100/2sAXqv61r7) for request bodies and response examples. When the Postman collection and source code differ, the route files under `src/features/*/route/` are the source of truth. -- API Documentation: [https://documenter.getpostman.com/view/23054100/2sAXqv61r7](https://documenter.getpostman.com/view/23054100/2sAXqv61r7) -- GitHub Repository: [https://github.com/KariMuhammad/eCommerceTS](https://github.com/KariMuhammad/eCommerceTS) +## Scripts -## Footer +| Command | Description | +| --- | --- | +| `npm run dev` | Run through Nodemon using `nodemon.json` | +| `npm run dev2` | Run with `ts-node-dev` and automatic restart | +| `npm run build` | Compile the TypeScript sources to `dist/` | +| `npm start` | Run the compiled server entry point | -``` +## Project Status +The main catalog, authentication, cart, coupon, wishlist, blog, user, and review modules are present. Orders, refunds, automated tests, and the production build path remain areas for continued development. -``` +## License -```html -
-

- eCommerceTS - | Repository URL: https://github.com/KariMuhammad/eCommerceTS -

-

- Author: Karim Muhammad -

-

- Contact: kimoomar005@gmail.com -

-

- โญ๏ธ Consider giving the project a star on GitHub! โญ๏ธ -

-

- Fork the project | Like the project | Raise issues -

-
-``` +The package metadata declares the ISC license. No standalone license file is currently included in the repository.