📚 Book-Shelf - E-Commerce Bookstore

A modern, serverless e-commerce bookstore built with Next.js 15, TypeScript, MongoDB Atlas, and Stripe. Features comprehensive book management, secure authentication, shopping cart functionality, and administrative tools for managing inventory and orders.

✨ Features

🛍️ Customer Features

• Browse & Search: Advanced book discovery with filtering by category, author, price, and ratings
• Shopping Cart: Persistent cart with real-time updates and quantity management
• Secure Checkout: Stripe-powered payment processing with multiple payment methods
• Order Tracking: Complete order history and status tracking
• User Accounts: Registration, authentication, and profile management
• Wishlist: Save books for later purchase
• Reviews & Ratings: Rate and review purchased books
• Responsive Design: Optimized for desktop, tablet, and mobile devices

🔧 Admin Features

• Dashboard Analytics: Real-time insights into sales, orders, and inventory
• Book Management: Full CRUD operations for book catalog
• Category Management: Hierarchical category system with drag-and-drop organization
• Author & Publisher Management: Comprehensive database of authors and publishers
• Order Management: Order fulfillment, status updates, and customer communication
• User Administration: Manage customer accounts and admin roles
• File Uploads: Cloudinary integration for book covers and images
• Inventory Tracking: Stock levels, bestsellers, and featured book management

🚀 Technical Features

• Serverless Architecture: Built for Vercel deployment with optimized cold starts
• JWT Authentication: Secure token-based authentication with role-based access control
• MongoDB Atlas: Cloud database with connection pooling and caching
• Stripe Integration: Secure payment processing with webhook handling
• Image Management: Cloudinary CDN for optimized image delivery
• Real-time Updates: Live cart updates and order status changes
• SEO Optimized: Server-side rendering with meta tags and structured data

🛠️ Technologies Used

Frontend

• Next.js 15 - React framework with App Router
• TypeScript - Type-safe JavaScript
• HeroUI v2 - Modern React component library
• Tailwind CSS - Utility-first CSS framework
• Framer Motion - Animation library
• Lucide React - Beautiful icons

Backend

• MongoDB Atlas - Cloud database
• Stripe - Payment processing
• Cloudinary - Image and video management
• JWT - JSON Web Tokens for authentication
• bcryptjs - Password hashing

Development Tools

• next-themes - Dark/light theme support
• Tailwind Variants - Component styling variants
• ESLint - Code linting
• Prettier - Code formatting

🚀 Quick Start

Prerequisites

• Node.js 18+ and pnpm
• MongoDB Atlas cluster
• Stripe account
• Cloudinary account

Installation

1. Clone the repository

   git clone https://github.com/your-username/book-shelf.git
   cd book-shelf

2. Install dependencies

   pnpm install

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

   # Database
   MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/book-store
   
   # Authentication
   JWT_SECRET=your-super-secret-jwt-key
   JWT_EXPIRES_IN=7d
   
   # Stripe
   STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
   STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key
   STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
   
   # Cloudinary
   CLOUDINARY_CLOUD_NAME=your_cloud_name
   CLOUDINARY_API_KEY=your_api_key
   CLOUDINARY_API_SECRET=your_api_secret
   
   # App Configuration
   NEXTAUTH_URL=http://localhost:3000
   NEXTAUTH_SECRET=your-nextauth-secret

4. Seed the database (optional)

   pnpm seed

5. Run the development server

   pnpm dev

6. Access the application

   • Frontend: http://localhost:3000
   • Admin Dashboard: http://localhost:3000/admin/dashboard

Demo Credentials

Buyer Account:
Email: buyer@demo.com
Password: password123

Admin Account:
Email: admin@demo.com
Password: password123

📁 Project Structure

book-shelf/
├── app/                        # Next.js 15 App Router
│   ├── (auth)/                # Authentication pages
│   │   ├── login/
│   │   └── register/
│   ├── admin/                 # Admin dashboard
│   │   ├── dashboard/
│   │   │   ├── books/         # Book management
│   │   │   ├── categories/    # Category management
│   │   │   ├── authors/       # Author management
│   │   │   ├── publishers/    # Publisher management
│   │   │   └── users/         # User management
│   │   └── layout.tsx
│   ├── api/                   # API routes
│   │   ├── auth/             # Authentication endpoints
│   │   ├── books/            # Book CRUD operations
│   │   ├── categories/       # Category management
│   │   ├── admin/            # Admin-only endpoints
│   │   └── uploads/          # File upload handling
│   ├── books/                # Book catalog pages
│   ├── cart/                 # Shopping cart
│   ├── checkout/             # Checkout process
│   ├── orders/               # Order management
│   └── page.tsx              # Homepage
├── components/               # Reusable React components
│   ├── sections/            # Homepage sections
│   ├── ui/                  # UI components
│   ├── navbar.tsx
│   └── layout-wrapper.tsx
├── contexts/                # React Context providers
│   ├── AuthContext.tsx      # Authentication state
│   ├── CartContext.tsx      # Shopping cart state
│   └── StripeContext.tsx    # Stripe integration
├── lib/                     # Utility libraries
│   ├── auth.ts             # Authentication utilities
│   ├── db.ts               # Database connection
│   ├── utils.ts            # General utilities
│   └── validations.ts      # Schema validations
├── types/                  # TypeScript type definitions
└── public/                # Static assets

🔧 Development Commands

# Development
pnpm dev              # Run development server with Turbo
pnpm build            # Build for production
pnpm start            # Start production server

# Database
pnpm seed             # Seed database with sample data

# Code Quality
pnpm lint             # Run ESLint
pnpm type-check       # Run TypeScript compiler

🌐 API Documentation

Authentication Endpoints

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user

Book Management

• GET /api/books - Get books with filtering and pagination
• GET /api/books/[id] - Get single book details
• POST /api/admin/books - Create new book (Admin)
• PUT /api/admin/books/[id] - Update book (Admin)
• DELETE /api/admin/books/[id] - Delete book (Admin)

Order Management

• GET /api/orders - Get user orders
• POST /api/orders - Create new order
• GET /api/admin/orders - Get all orders (Admin)
• PUT /api/admin/orders/[id] - Update order status (Admin)

File Uploads

• POST /api/uploads - Upload images to Cloudinary

🎨 Design System

The project follows a comprehensive design system with:

• Brand Colors: Primary blues, accent oranges, and semantic colors
• Typography: Inter font family with consistent sizing
• Component Library: HeroUI components with custom theming
• Responsive Design: Mobile-first approach with Tailwind breakpoints
• Dark Mode: Complete dark theme support

Refer to doc/design-system.json for detailed design specifications.

🚦 User Roles & Permissions

👤 Buyer Role

• Browse and search books
• Manage shopping cart
• Complete purchases
• Track orders
• Write reviews
• Manage account profile

🛡️ Admin Role

• All buyer permissions
• Access admin dashboard
• Manage book catalog
• Process orders
• Manage users
• View analytics
• Upload images

🔒 Security Features

• JWT Authentication: Secure token-based authentication
• Password Hashing: bcrypt for secure password storage
• Role-Based Access Control: Granular permissions system
• Input Validation: Zod schema validation for all inputs
• CORS Protection: Configured for production deployment
• Rate Limiting: API rate limiting for abuse prevention
• Secure Headers: Security headers for XSS and CSRF protection

📱 Deployment

Vercel (Recommended)

1. Connect your GitHub repository to Vercel
2. Add environment variables in Vercel dashboard
3. Deploy with automatic CI/CD

Manual Deployment

pnpm build
pnpm start

Environment Variables for Production

Ensure all environment variables are set in your deployment platform with production values for MongoDB, Stripe, and Cloudinary.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add 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 MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• HeroUI for the beautiful component library
• Stripe for payment processing
• MongoDB Atlas for database hosting
• Cloudinary for image management
• Vercel for hosting and deployment