Skip to content

README.md

Latest commit

 

History

History
287 lines (237 loc) · 7.34 KB

README.md

File metadata and controls

287 lines (237 loc) · 7.34 KB

EssadaJS

EssadaJS Icon

A modern, scalable Node.js boilerplate with Express.js, featuring a well-structured architecture, built-in authentication, database integration, and comprehensive helper utilities.

🚀 Features

Core Architecture

  • Modular Structure: Clean separation of concerns with controllers, services, repositories, validators, and middlewares
  • Multi-threading: Built-in cluster support for better performance
  • API Versioning: Organized route structure with version control
  • Environment Configuration: Easy environment variable management

Authentication & Security

  • JWT Authentication: Secure token-based authentication
  • Password Hashing: BCrypt integration for secure password storage
  • SHA256 Utilities: Additional cryptographic helpers
  • Authorization Middleware: Role-based access control

Database Integration

  • Sequelize ORM: Full database support with MySQL
  • Model Handler: Centralized database connection management
  • Query Logging: Built-in SQL query logging for debugging

File Management

  • AWS S3 Integration: Cloud file storage capabilities
  • File System Helper: Local file operations utilities
  • File Type Detection: Automatic file type recognition

Communication

  • Email Service: Nodemailer integration for email functionality
  • QR Code Generation: Built-in QR code utilities

AI Integration

  • Gemini AI Helper: Google Gemini AI integration
  • AI-powered Features: Ready-to-use AI capabilities

Development Tools

  • Comprehensive Logging: Structured logging system
  • Response Presets: Standardized API response formats
  • Validation: AJV schema validation
  • CORS Support: Cross-origin resource sharing
  • Morgan Logging: HTTP request logging

📁 Project Structure

EssadaJS/
├── src/
│   ├── controllers/          # Request handlers
│   │   └── primary/v1/
│   │       ├── Auth.controller.js
│   │       └── index.js
│   ├── helpers/             # Utility functions
│   │   ├── FileSystem.helper.js
│   │   ├── GeminiAI.helper.js
│   │   ├── JWT.helper.js
│   │   ├── Logger.helper.js
│   │   ├── Mailer.helper.js
│   │   ├── ResponsePreset.helper.js
│   │   ├── SHA256.helper.js
│   │   └── index.js
│   ├── middlewares/         # Request processing
│   │   ├── Handler.middleware.js
│   │   ├── primary/v1/
│   │   │   └── Authorization.middleware.js
│   │   └── index.js
│   ├── models/              # Database models
│   │   ├── Handler.model.js
│   │   ├── Users.model.example.js
│   │   └── index.js
│   ├── repositories/        # Data access layer
│   │   └── primary/v1/
│   │       ├── User.repository.js
│   │       └── index.js
│   ├── routes/              # API endpoints
│   │   ├── Handler.route.js
│   │   └── primary/v1/
│   │       ├── Auth.route.js
│   │       ├── Handler.route.js
│   │       └── index.js
│   ├── services/            # Business logic
│   │   └── primary/v1/
│   │       ├── Auth.service.js
│   │       └── index.js
│   ├── validators/          # Request validation
│   │   └── primary/v1/
│   │       ├── Auth.validator.js
│   │       └── index.js
│   └── Main.js             # Application entry point
├── storage/                 # File storage
│   ├── app/
│   └── configs/
├── package.json
└── README.md

🛠️ Installation

  1. Clone the repository

    git clone <repository-url>
cd EssadaJS

  2. Install dependencies

    npm install

  3. Environment Setup Create a .env file in the root directory:

    # Server Configuration
PORT=3000
IP=0.0.0.0
SERVER_THREADS=4

# Database Configuration
DB_ENABLE=true
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_DATABASE=your_database
DB_DIALECT=mysql
DB_LOGGING=true

# JWT Configuration
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=24h

# Email Configuration
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password

# Gemini AI Configuration (optional)
GEMINI_API_KEY=your_gemini_api_key

🚀 Usage

Development Mode

npm run dev

Production Mode

npm start

📚 Example API Response

Response:

{
  "status": 200,
  "message": "OK",
  "data": {
    "token": "jwt_token_here",
    "user": {
      "id": 1,
      "email": "user@example.com",
      "name": "User Name"
    }
  }
}

Response Format

All API responses follow a standardized format:

Success Response:

{
  "status": 200,
  "message": "Success message",
  "data": { /* response data */ }
}

Error Response:

{
  "status": 400,
  "message": "Error message",
  "err": {
    "type": "validation",
    "data": { /* error details */ }
  }
}

🔧 Configuration

Database Models

Create your database models in src/models/ following the Sequelize pattern:

// Example: src/models/Users.model.js
import { DataTypes } from 'sequelize';

export default (sequelize) => {
  const User = sequelize.define('User', {
    id: {
      type: DataTypes.INTEGER,
      primaryKey: true,
      autoIncrement: true
    },
    email: {
      type: DataTypes.STRING,
      unique: true,
      allowNull: false
    },
    password: {
      type: DataTypes.STRING,
      allowNull: false
    }
  });
  
  return User;
};

Adding New Routes

  1. Create controller in src/controllers/primary/v1/
  2. Create service in src/services/primary/v1/
  3. Create validator in src/validators/primary/v1/
  4. Create repository in src/repositories/primary/v1/
  5. Add route in src/routes/primary/v1/

🛡️ Security Features

  • JWT Token Authentication
  • Password Hashing with BCrypt
  • CORS Protection
  • Request Validation with AJV
  • SQL Injection Protection (Sequelize)
  • Environment Variable Security

📦 Dependencies

Core Dependencies

  • Express.js: Web framework
  • Sequelize: ORM for database operations
  • MySQL2: MySQL database driver
  • JWT: JSON Web Token authentication
  • BCrypt: Password hashing

Development Dependencies

  • Nodemon: Development server with auto-reload
  • Morgan: HTTP request logger

Utility Dependencies

  • Axios: HTTP client
  • Nodemailer: Email functionality
  • QRCode: QR code generation
  • AWS SDK: Cloud storage integration
  • Moment: Date/time utilities

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the ISC License.

🆘 Support

For support and questions, please open an issue in the repository.

EssadaJS - A modern Node.js boilerplate for building scalable applications.