From c55b4348ece02a6a4e9934806c5e0f4950b4fe5f Mon Sep 17 00:00:00 2001 From: Sanjana Date: Sun, 16 Nov 2025 01:16:49 +0530 Subject: [PATCH 1/2] Enhance README with features and usage details Expanded README with detailed features, installation instructions, API documentation, and security features. --- README.md | 367 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 356 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index baa2870..d5b2ce1 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,359 @@ -# root-template-express +# Root Template Express -Backend template for Root Kings Express Applications +A secure Express.js backend template with MongoDB integration, featuring password hashing, input validation, and JWT authentication. -## Required `env` variables +![Node.js](https://img.shields.io/badge/Node.js-v14+-green) +![Express](https://img.shields.io/badge/Express-4.17-blue) +![MongoDB](https://img.shields.io/badge/MongoDB-5.9-green) +![License](https://img.shields.io/badge/License-MIT-yellow) -1. `PORT` -2. `MONGODB_URI` -3. `NODE_ENV` -4. `JWT_EXPIRES` -5. `JWT_ISSUER` -6. `JWT_SECRET` -7. `UPLOADS_DIR` -8. `PUBLIC_DIR` +## ๐ŸŽฏ Features + +- ๐Ÿ” **Password Security** - Bcrypt hashing (10 salt rounds) +- โœ… **Input Validation** - Joi validation for emails, passwords, and user data +- ๐Ÿ”‘ **JWT Authentication** - Secure token-based auth +- ๐Ÿ“ฆ **MongoDB Integration** - Mongoose ORM with pagination +- ๐Ÿ›ก๏ธ **CORS Protection** - Cross-origin request handling +- ๐Ÿ“ **Request Logging** - Morgan HTTP request logger +- ๐Ÿ“ง **Email Support** - SendGrid integration ready +- ๐Ÿš€ **Production Ready** - Error handling and security best practices + +## ๐Ÿ“ธ Demo + +Here's how the API works: + +``` +POST /api/users - Create User +POST /api/auth/login - Login +GET /api/users - List Users (requires token) +``` + +## ๐Ÿ› ๏ธ Tech Stack + +| Technology | Purpose | +|-----------|---------| +| **Express.js** | Web framework | +| **MongoDB** | Database | +| **Mongoose** | ODM | +| **JWT** | Authentication | +| **Bcrypt** | Password hashing | +| **Joi** | Data validation | +| **Multer** | File uploads | +| **Socket.io** | Real-time communication (optional) | + +## โš™๏ธ Installation + +### Prerequisites +- Node.js (v14 or higher) +- MongoDB (local or cloud) +- npm or yarn + +### Steps + +```bash +# Clone the repository +git clone https://github.com/sanjana2505006/template-express-mongodb.git + +# Navigate to directory +cd template-express-mongodb + +# Install dependencies +npm install + +# Create .env file +cp .env.example .env + +# Start the server +npm run dev +``` + +## ๐Ÿ”ง Environment Variables + +Create a `.env` file in the root directory: + +```env +# Server +PORT=3000 +NODE_ENV=development + +# Database +MONGODB_URI=mongodb://localhost:27017/root_kings + +# JWT +JWT_EXPIRES=7d +JWT_ISSUER=root-kings +JWT_SECRET=your_super_secret_key_here + +# File Upload +UPLOADS_DIR=uploads +PUBLIC_DIR=public +``` + +## ๐Ÿš€ Running the App + +```bash +# Development mode (auto-reload with nodemon) +npm run dev + +# Production mode +npm start + +# Linting +npm run lint +``` + +Server runs on: `http://localhost:3000` + +## ๐Ÿ“š API Documentation + +### Authentication Endpoints + +#### Login +```http +POST /api/auth/login +Content-Type: application/json + +{ + "email": "user@example.com", + "password": "MyPass@123", + "type": "root" +} +``` + +**Response:** +```json +{ + "status": true, + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "user": { + "_id": "123456", + "name": "John Doe", + "email": "user@example.com", + "type": "root" + } +} +``` + +#### Check Login Status +```http +GET /api/auth/login/status +Authorization: Bearer +``` + +--- + +### User Endpoints + +#### Create User +```http +POST /api/users +Content-Type: application/json + +{ + "name": "John Doe", + "email": "john@example.com", + "password": "MyPass@123", + "type": "root", + "phone": "1234567890" +} +``` + +**Password Requirements:** +- Minimum 8 characters +- 1 uppercase letter +- 1 lowercase letter +- 1 number +- 1 special character (!@#$%^&*) + +#### Get All Users +```http +GET /api/users?type=root +Authorization: Bearer +``` + +#### Get User Details +```http +GET /api/users/:userid +Authorization: Bearer +``` + +#### Delete User +```http +DELETE /api/users/:userid +Authorization: Bearer +``` + +--- + +### Utility Endpoints + +#### Check Email Availability +```http +GET /api/utils/checkEmailAvailability?email=user@example.com +``` + +#### Check Username Availability +```http +GET /api/utils/checkUsernameAvailability?username=johndoe +``` + +--- + +## ๐Ÿ“ Project Structure + +``` +. +โ”œโ”€โ”€ controllers/ # Business logic for routes +โ”‚ โ”œโ”€โ”€ auth.js # Authentication logic +โ”‚ โ”œโ”€โ”€ user.js # User management logic +โ”‚ โ””โ”€โ”€ util.js # Utility functions +โ”œโ”€โ”€ models/ # Mongoose schemas +โ”‚ โ””โ”€โ”€ user.js # User schema +โ”œโ”€โ”€ routes/ # API route definitions +โ”‚ โ”œโ”€โ”€ index.js # Main router +โ”‚ โ”œโ”€โ”€ auth.js # Auth routes +โ”‚ โ”œโ”€โ”€ user.js # User routes +โ”‚ โ””โ”€โ”€ util.js # Utility routes +โ”œโ”€โ”€ middlewares/ # Custom middleware +โ”‚ โ”œโ”€โ”€ validateToken.js # JWT validation +โ”‚ โ””โ”€โ”€ allowRoot.js # Role-based access +โ”œโ”€โ”€ utils/ # Utility functions +โ”‚ โ”œโ”€โ”€ validators.js # Joi validation schemas +โ”‚ โ”œโ”€โ”€ generate.js # Key/secret generation +โ”‚ โ”œโ”€โ”€ asyncForEach.js # Async helpers +โ”‚ โ”œโ”€โ”€ mkdirSync.js # Directory creation +โ”‚ โ””โ”€โ”€ unlinkSync.js # File deletion +โ”œโ”€โ”€ data/ # Test data +โ”‚ โ””โ”€โ”€ test.http # HTTP client requests +โ”œโ”€โ”€ server.js # Main server file +โ”œโ”€โ”€ package.json # Dependencies +โ””โ”€โ”€ README.md # This file +``` + +## ๐Ÿ”’ Security Features + +โœ… **Password Security** +- Bcrypt hashing with 10 salt rounds +- Passwords never returned in API responses +- Passwords never included in JWT tokens + +โœ… **Input Validation** +- Email format validation +- Password strength requirements +- User data validation +- Request sanitization + +โœ… **Authentication** +- JWT-based token authentication +- Token expiration (configurable) +- Secure token verification + +โœ… **Authorization** +- Role-based access control (RBAC) +- Token validation middleware +- Protected routes + +โœ… **Other** +- CORS protection +- HTTP request logging +- Error handling +- Database connection pooling + +## ๐Ÿงช Testing + +### Using REST Client (VS Code) + +Open `data/test.http` and test endpoints: + +```http +### Create User +POST http://localhost:3000/api/users +Content-Type: application/json + +{ + "name": "Test User", + "email": "test@example.com", + "password": "TestPass@123", + "type": "root" +} + +### Login +POST http://localhost:3000/api/auth/login +Content-Type: application/json + +{ + "email": "test@example.com", + "password": "TestPass@123", + "type": "root" +} +``` + +### Using cURL + +```bash +# Create user +curl -X POST http://localhost:3000/api/users \ + -H "Content-Type: application/json" \ + -d '{"name":"John","email":"john@test.com","password":"TestPass@123","type":"root"}' + +# Login +curl -X POST http://localhost:3000/api/auth/login \ + -H "Content-Type: application/json" \ + -d '{"email":"john@test.com","password":"TestPass@123","type":"root"}' +``` + +## ๐Ÿ“ Scripts + +| Command | Description | +|---------|-------------| +| `npm start` | Start production server | +| `npm run dev` | Start with auto-reload (nodemon) | +| `npm run lint` | Run ESLint | + +## ๐Ÿค Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feat/amazing-feature`) +3. Commit changes (`git commit -m 'feat: add amazing feature'`) +4. Push to branch (`git push origin feat/amazing-feature`) +5. Open a Pull Request + +### Before Submitting PR +- Run linter: `npm run lint` +- Test your changes thoroughly +- Update documentation if needed +- Follow the existing code style + +## ๐Ÿ› Issues & Bugs + +Found a bug? [Open an issue](https://github.com/root-kings/template-express-mongodb/issues) with: +- Clear description of the problem +- Steps to reproduce +- Expected vs actual behavior +- Your environment (Node version, OS, etc.) + +## ๐Ÿ“„ License + +MIT License - see LICENSE file for details + +## ๐Ÿ‘จโ€๐Ÿ’ป Author + +**Root Kings** +- GitHub: [@root-kings](https://github.com/root-kings) + +## ๐Ÿ™ Acknowledgments + +- Express.js team for the amazing framework +- MongoDB for the database +- All contributors and users + +## ๐Ÿ“ž Support + +For issues, questions, or suggestions: +- Open an issue on GitHub +- Check existing documentation +- Review the code comments + +--- + +**Made with โค๏ธ by Root Kings** From e21cd658c9cb015e3899a31a1ce4e1936a21c69a Mon Sep 17 00:00:00 2001 From: Sanjana Date: Sat, 22 Nov 2025 18:36:32 +0530 Subject: [PATCH 2/2] docs: minor formatting update --- README.md | 207 +++++++++++------------------------------------------- 1 file changed, 41 insertions(+), 166 deletions(-) diff --git a/README.md b/README.md index d5b2ce1..f7bb5a3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Root Template Express +# root-template-express A secure Express.js backend template with MongoDB integration, featuring password hashing, input validation, and JWT authentication. @@ -7,41 +7,18 @@ A secure Express.js backend template with MongoDB integration, featuring passwor ![MongoDB](https://img.shields.io/badge/MongoDB-5.9-green) ![License](https://img.shields.io/badge/License-MIT-yellow) -## ๐ŸŽฏ Features +## Features -- ๐Ÿ” **Password Security** - Bcrypt hashing (10 salt rounds) -- โœ… **Input Validation** - Joi validation for emails, passwords, and user data -- ๐Ÿ”‘ **JWT Authentication** - Secure token-based auth -- ๐Ÿ“ฆ **MongoDB Integration** - Mongoose ORM with pagination -- ๐Ÿ›ก๏ธ **CORS Protection** - Cross-origin request handling -- ๐Ÿ“ **Request Logging** - Morgan HTTP request logger -- ๐Ÿ“ง **Email Support** - SendGrid integration ready -- ๐Ÿš€ **Production Ready** - Error handling and security best practices +- **Password Security** - Bcrypt hashing (10 salt rounds) +- **Input Validation** - Joi validation for emails, passwords, and user data +- **JWT Authentication** - Secure token-based auth +- **MongoDB Integration** - Mongoose ORM with pagination +- **CORS Protection** - Cross-origin request handling +- **Request Logging** - Morgan HTTP request logger +- **Email Support** - SendGrid integration ready +- **Production Ready** - Error handling and security best practices -## ๐Ÿ“ธ Demo - -Here's how the API works: - -``` -POST /api/users - Create User -POST /api/auth/login - Login -GET /api/users - List Users (requires token) -``` - -## ๐Ÿ› ๏ธ Tech Stack - -| Technology | Purpose | -|-----------|---------| -| **Express.js** | Web framework | -| **MongoDB** | Database | -| **Mongoose** | ODM | -| **JWT** | Authentication | -| **Bcrypt** | Password hashing | -| **Joi** | Data validation | -| **Multer** | File uploads | -| **Socket.io** | Real-time communication (optional) | - -## โš™๏ธ Installation +## Installation ### Prerequisites - Node.js (v14 or higher) @@ -52,7 +29,7 @@ GET /api/users - List Users (requires token) ```bash # Clone the repository -git clone https://github.com/sanjana2505006/template-express-mongodb.git +git clone https://github.com/root-kings/template-express-mongodb.git # Navigate to directory cd template-express-mongodb @@ -67,7 +44,7 @@ cp .env.example .env npm run dev ``` -## ๐Ÿ”ง Environment Variables +## Environment Variables Create a `.env` file in the root directory: @@ -89,7 +66,7 @@ UPLOADS_DIR=uploads PUBLIC_DIR=public ``` -## ๐Ÿš€ Running the App +## Running the App ```bash # Development mode (auto-reload with nodemon) @@ -104,162 +81,59 @@ npm run lint Server runs on: `http://localhost:3000` -## ๐Ÿ“š API Documentation +## API Documentation -### Authentication Endpoints +Interactive API documentation is available when running the server in development: -#### Login -```http -POST /api/auth/login -Content-Type: application/json - -{ - "email": "user@example.com", - "password": "MyPass@123", - "type": "root" -} ``` - -**Response:** -```json -{ - "status": true, - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", - "user": { - "_id": "123456", - "name": "John Doe", - "email": "user@example.com", - "type": "root" - } -} -``` - -#### Check Login Status -```http -GET /api/auth/login/status -Authorization: Bearer +http://localhost:3000/api-docs ``` ---- +Please use the interactive docs for up-to-date endpoint details and examples. -### User Endpoints +## Project Structure -#### Create User -```http -POST /api/users -Content-Type: application/json +Top-level folders: -{ - "name": "John Doe", - "email": "john@example.com", - "password": "MyPass@123", - "type": "root", - "phone": "1234567890" -} ``` - -**Password Requirements:** -- Minimum 8 characters -- 1 uppercase letter -- 1 lowercase letter -- 1 number -- 1 special character (!@#$%^&*) - -#### Get All Users -```http -GET /api/users?type=root -Authorization: Bearer -``` - -#### Get User Details -```http -GET /api/users/:userid -Authorization: Bearer -``` - -#### Delete User -```http -DELETE /api/users/:userid -Authorization: Bearer -``` - ---- - -### Utility Endpoints - -#### Check Email Availability -```http -GET /api/utils/checkEmailAvailability?email=user@example.com -``` - -#### Check Username Availability -```http -GET /api/utils/checkUsernameAvailability?username=johndoe -``` - ---- - -## ๐Ÿ“ Project Structure - -``` -. -โ”œโ”€โ”€ controllers/ # Business logic for routes -โ”‚ โ”œโ”€โ”€ auth.js # Authentication logic -โ”‚ โ”œโ”€โ”€ user.js # User management logic -โ”‚ โ””โ”€โ”€ util.js # Utility functions -โ”œโ”€โ”€ models/ # Mongoose schemas -โ”‚ โ””โ”€โ”€ user.js # User schema -โ”œโ”€โ”€ routes/ # API route definitions -โ”‚ โ”œโ”€โ”€ index.js # Main router -โ”‚ โ”œโ”€โ”€ auth.js # Auth routes -โ”‚ โ”œโ”€โ”€ user.js # User routes -โ”‚ โ””โ”€โ”€ util.js # Utility routes -โ”œโ”€โ”€ middlewares/ # Custom middleware -โ”‚ โ”œโ”€โ”€ validateToken.js # JWT validation -โ”‚ โ””โ”€โ”€ allowRoot.js # Role-based access -โ”œโ”€โ”€ utils/ # Utility functions -โ”‚ โ”œโ”€โ”€ validators.js # Joi validation schemas -โ”‚ โ”œโ”€โ”€ generate.js # Key/secret generation -โ”‚ โ”œโ”€โ”€ asyncForEach.js # Async helpers -โ”‚ โ”œโ”€โ”€ mkdirSync.js # Directory creation -โ”‚ โ””โ”€โ”€ unlinkSync.js # File deletion -โ”œโ”€โ”€ data/ # Test data -โ”‚ โ””โ”€โ”€ test.http # HTTP client requests -โ”œโ”€โ”€ server.js # Main server file -โ”œโ”€โ”€ package.json # Dependencies -โ””โ”€โ”€ README.md # This file +controllers/ +models/ +routes/ +middlewares/ +utils/ +data/ ``` -## ๐Ÿ”’ Security Features +## Security Features -โœ… **Password Security** +**Password Security** - Bcrypt hashing with 10 salt rounds - Passwords never returned in API responses - Passwords never included in JWT tokens -โœ… **Input Validation** +**Input Validation** - Email format validation - Password strength requirements - User data validation - Request sanitization -โœ… **Authentication** +**Authentication** - JWT-based token authentication - Token expiration (configurable) - Secure token verification -โœ… **Authorization** +**Authorization** - Role-based access control (RBAC) - Token validation middleware - Protected routes -โœ… **Other** +**Other** - CORS protection - HTTP request logging - Error handling - Database connection pooling -## ๐Ÿงช Testing +## Testing ### Using REST Client (VS Code) @@ -302,7 +176,7 @@ curl -X POST http://localhost:3000/api/auth/login \ -d '{"email":"john@test.com","password":"TestPass@123","type":"root"}' ``` -## ๐Ÿ“ Scripts +## Scripts | Command | Description | |---------|-------------| @@ -310,7 +184,7 @@ curl -X POST http://localhost:3000/api/auth/login \ | `npm run dev` | Start with auto-reload (nodemon) | | `npm run lint` | Run ESLint | -## ๐Ÿค Contributing +## Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feat/amazing-feature`) @@ -324,7 +198,7 @@ curl -X POST http://localhost:3000/api/auth/login \ - Update documentation if needed - Follow the existing code style -## ๐Ÿ› Issues & Bugs +## Issues & Bugs Found a bug? [Open an issue](https://github.com/root-kings/template-express-mongodb/issues) with: - Clear description of the problem @@ -332,22 +206,22 @@ Found a bug? [Open an issue](https://github.com/root-kings/template-express-mong - Expected vs actual behavior - Your environment (Node version, OS, etc.) -## ๐Ÿ“„ License +## License MIT License - see LICENSE file for details -## ๐Ÿ‘จโ€๐Ÿ’ป Author +## Author **Root Kings** - GitHub: [@root-kings](https://github.com/root-kings) -## ๐Ÿ™ Acknowledgments +## Acknowledgments - Express.js team for the amazing framework - MongoDB for the database - All contributors and users -## ๐Ÿ“ž Support +## Support For issues, questions, or suggestions: - Open an issue on GitHub @@ -356,4 +230,5 @@ For issues, questions, or suggestions: --- + **Made with โค๏ธ by Root Kings**