# Indian Books Worldwide (IBW) - Enterprise E-Commerce Platform

## Project Overview

**Indian Books Worldwide** is a full-stack single-vendor e-commerce platform for Indian books, serving global audiences directly from the official store. It features:
- Customer Storefront (browse, search, buy books)
- Admin Store Management (manage book catalog, inventory stock, order fulfillment, analytics)
- JWT + Refresh Token Authentication with Role-Based Access Control (`CUSTOMER`, `ADMIN`)
- Meilisearch powered real-time search
- Redis caching layer
- AWS S3 asset storage integration
- Complete Docker + PM2 + Nginx deployment pipeline

---

## 📐 Architecture & Monorepo Structure

This project is structured as an **npm workspace monorepo**:

```
Indian Books Worldwide/
├── apps/
│   ├── backend/          # Node.js / Express / TypeScript API service
│   └── frontend/         # Next.js / React / TypeScript web app
├── packages/
│   └── shared/           # @ibw/shared - Shared TypeScript types & DTOs
├── docker/
│   ├── mysql/
│   │   └── init.sql      # Database initialization schema and seed data
│   └── nginx/
│       └── nginx.conf    # Nginx reverse proxy configuration
├── scripts/
│   ├── setup.sh          # One-click environment setup script
│   ├── dev.sh            # Starts local development environment
│   ├── build.sh          # Compiles all packages & apps
│   └── deploy.sh         # Production deployment script
├── .env.example          # Environment variables template
├── docker-compose.yml    # Docker Compose setup for Local Development
├── docker-compose.prod.yml # Docker Compose setup for Production
└── package.json          # Root workspace configuration
```

---

## 🛠 Tech Stack

- **Frontend**: Next.js, React, Tailwind CSS, TypeScript
- **Backend**: Node.js, Express, TypeScript, TypeORM / Prisma
- **Database**: MySQL 8.0
- **Caching & Queues**: Redis 7
- **Search Engine**: Meilisearch v1.6
- **Reverse Proxy**: Nginx (Alpine)
- **Containerization**: Docker & Docker Compose

---

## 🚀 Quick Start (Development)

### Prerequisites
- Node.js >= 18.0.0
- npm >= 9.0.0
- Docker Desktop & Docker Compose

### 1. Environment Setup
Run the setup script to copy environment variables and install dependencies:
```bash
npm run setup
# or
bash ./scripts/setup.sh
```

### 2. Run Development Environment
Start database services (MySQL, Redis, Meilisearch) and application servers:
```bash
npm run dev
# or
bash ./scripts/dev.sh
```

---

## ⚡ Available NPM Scripts

| Command | Description |
| :--- | :--- |
| `npm run setup` | Copies `.env.example` -> `.env`, installs npm dependencies, builds shared package |
| `npm run dev` | Boots Docker dev containers and runs frontend & backend in dev mode |
| `npm run build` | Builds `@ibw/shared` package and all workspace applications |
| `npm run deploy` | Triggers production deployment via `docker-compose.prod.yml` |
| `npm run lint` | Runs code linting across all workspace packages |
| `npm run format` | Formats all code files with Prettier |

---

## 🔌 API Endpoints Summary

Base URL: `http://localhost:5000/api/v1`

### Authentication (`/api/v1/auth`)
- `POST /auth/register` - User registration
- `POST /auth/login` - User authentication
- `POST /auth/refresh` - Refresh access token
- `GET /auth/me` - Fetch authenticated user profile

### Books & Catalog (`/api/v1/books`)
- `GET /books` - Paginated list of books (supports filtering, sorting, search)
- `GET /books/:id` - Fetch detailed book information
- `POST /books` - Create new book (Admin/Seller)
- `PUT /books/:id` - Update book details (Admin/Seller)
- `DELETE /books/:id` - Soft delete/deactivate book (Admin)

### Categories (`/api/v1/categories`)
- `GET /categories` - List all book categories
- `GET /categories/:slug` - Category details with associated books

### Cart (`/api/v1/cart`)
- `GET /cart` - Retrieve active user or guest cart
- `POST /cart/items` - Add item to cart
- `PUT /cart/items/:id` - Update item quantity
- `DELETE /cart/items/:id` - Remove item from cart

### Orders & Checkout (`/api/v1/orders`)
- `POST /orders` - Create order from active cart
- `GET /orders` - List user orders
- `GET /orders/:id` - Order details & status
- `POST /orders/:id/payment` - Initiate payment process

### Health Check (`/api/v1/health`)
- `GET /health` - System health status (Database, Redis, Meilisearch)

---

## 🐳 Docker Deployment

### Local Multi-Container Setup
```bash
docker-compose up -d --build
```
Access endpoints:
- Frontend Web App: http://localhost:3000
- Backend REST API: http://localhost:5000/api/v1
- Nginx Gateway: http://localhost:80
- Meilisearch Dashboard: http://localhost:7700

### Production Deployment
```bash
bash ./scripts/deploy.sh
```

---

## 📄 License

Copyright © 2026 Indian Books Worldwide. All rights reserved.
