hossamgezo/bookstore-api repository overview

⁠📚 Bookstore API (V2)

A professional, high-performance Bookstore system featuring a hybrid RESTful API and MVC architecture, built with Node.js, Express, and TypeScript. This project implements Clean Modular Architecture, robust production security, and a fully automated CI/CD Pipeline.

⁠🔗 Quick Links

• 🚀 Live Website: https://bookstore-api-0fy2.onrender.com/⁠
• 📖 Swagger UI (Interactive API Docs): https://bookstore-api-0fy2.onrender.com/api-docs/⁠
• 💻 GitHub Repository: https://github.com/HossamGezo/ts-bookstore-api-v2⁠

⁠📸 Project Showcase

⁠🏠 Landing Page (MVC with EJS & Tailwind)

Click the image to visit the live home page.

⁠📖 Interactive API Explorer (Swagger UI)

Click the image to test the API endpoints live.

⁠🛠 Tech Stack

Backend & UI	Database & Validation	DevOps & CI/CD	Security & Performance

⁠✨ Key Features & Architecture

⁠🏗️ Architecture & Clean Code

• Modular Design: Fully organized by features (Auth, Users, Books, Authors) for maximum scalability.
• Hybrid Pattern: Combination of REST API for data exchange and MVC (using EJS & Tailwind) for user workflows.
• Service Layer: Business logic is decoupled from controllers using a standardized Result Object Pattern.
• Global Data Transformation: Automated MongoDB _id to id transformation via a custom global plugin.

⁠🔐 Security & Reliability

• Production Hardening: Protected by Helmet, HPP, and Compression.
• Rate Limiting: Throttling requests per IP via express-rate-limit to prevent DDoS attacks.
• Authentication: Secure JWT-based auth with Role-Based Access Control (RBAC).
• Live Reload: Seamless development experience integrated into the ESM workflow.

⁠⚡ Performance & Automation

• CI/CD Pipeline: Fully automated GitHub Actions that build and push Docker images on every push to main.
• Optimized Queries: Advanced Pagination and Filtering helper using Promise.all for high performance.
• Multi-stage Docker: Extremely small and secure production images using Alpine Linux.

⁠🔌 API Endpoints Overview

For a detailed interactive guide and to test the endpoints live, please visit our Swagger Documentation⁠.

⁠🔑 Auth (Authentication)

• POST /api/auth/register - Register a new user.
• POST /api/auth/login - Authenticate user and receive a JWT.

⁠👤 User (Administration)

• GET /api/users - List all users (Admin only).
• GET /api/users/{id} - Get user details (Owner or Admin).
• PUT /api/users/{id} - Update user profile.
• DELETE /api/users/{id} - Delete user account.

⁠🔐 Password (Recovery - MVC)

• GET /password/forgot-password - Render forgot password view.
• POST /password/forgot-password - Send reset password link via email.
• GET /password/reset-password/{id}/{token} - Render reset password form.
• POST /password/reset-password/{id}/{token} - Set a new password in the database.

⁠✍️ Author (Profiles)

• GET /api/authors - Get all authors with pagination.
• POST /api/authors - Create a new author (Admin only).
• GET /api/authors/{id} - Get author by ID.
• PUT /api/authors/{id} - Update author details (Admin only).
• DELETE /api/authors/{id} - Delete author by ID (Admin only).

⁠📚 Book (Catalog Management)

• GET /api/books - Get all books (with Pagination & Price Filtering).
• POST /api/books - Create a new book (Admin only).
• GET /api/books/{id} - Get book details (Populated with Author).
• PUT /api/books/{id} - Update book details (Admin only).
• DELETE /api/books/{id} - Delete book by ID (Admin only).

⁠📂 Upload (Storage Services)

• POST /api/upload - Upload a single image using Multer.

⁠⚙️ Configuration & Environment

To run this project locally, you need to set up the following environment variables. Create a .env file in the root directory and populate it with your values:

# APPLICATION CONFIGURATION
PORT=5001
NODE_ENV=development
BASE_URL=http://localhost:5001

# DATABASE CONFIGURATION
MONGO_URI_DEV=mongodb://localhost/bookStoreDB
MONGO_URI_PRO=your_production_mongodb_uri

# SECURITY & AUTHENTICATION
JWT_SECRET_KEY=your_super_secret_key
JWT_EXPIRES_IN=30d
PASSWORD_RESET_EXPIRES_IN=10m

# FRONTEND INTEGRATION (CORS)
CLIENT_URL=http://localhost:3000

# PAGINATION SETTINGS
BOOKS_PER_PAGE=2
AUTHORS_PER_PAGE=2
USERS_PER_PAGE=5

# NODEMAILER CONFIGURATION (SMTP)
[email protected]
USER_PASS=your_app_specific_password

⁠📂 Project Structure

src/
├── index.ts            # Entry point & Express app configuration
├── models/             # Centralized Mongoose Schemas (User, Book, Author)
├── modules/            # Feature-based modular logic
│   ├── auth/           # Login, Register & JWT Logic
│   ├── user/           # User management & Administration
│   ├── book/           # Catalog management & Price filtering
│   ├── author/         # Author profiles & Data seeding
│   ├── password/       # MVC Password recovery workflow
│   └── upload/         # File storage & Multer integration
│       └── docs/       # Integrated Swagger YAML definitions per module
├── shared/             # Cross-cutting concerns & Infrastructure
│   ├── config/         # DB Connection & Swagger JSDoc Setup
│   ├── helpers/        # Query, Response, and Mongoose utility functions
│   ├── middlewares/    # Auth guards, Error handling, and Logger
│   ├── types/          # Global TypeScript interfaces & Express extensions
│   └── validations/    # Shared Zod validation schemas
└── styles/             # Tailwind input CSS
├── views/              # EJS Templates for MVC views (Welcome & Password Reset)
├── public/             # Static assets (Compiled CSS & Uploaded images)

⁠🚀 Getting Started

⁠🐳 Run with Docker

Launch the entire environment (API + Database) with a single command:

docker-compose up -d

⁠💻 Local Development

npm run dev  # Start API only
npm run mvc  # Start API + Tailwind + Views

⁠👨‍💻 Connect with Me

• LinkedIn: Hossam Gouda⁠
• GitHub: Hossam Gouda⁠
• Email: [email protected]⁠

Developed with precision by Hossam Gouda
Front-End Engineer focused on building scalable and maintainable user interfaces.