Multi-Tenant E-commerce Marketplace Platform

Overview

A modern, scalable multi-tenant e-commerce marketplace platform built with microservices architecture. The platform enables vendors to create their own online stores while providing customers with a unified shopping experience across multiple marketplaces.

By leveraging microservices and event-driven architecture, the platform offers:

• Multi-tenant Architecture: Isolated environments for each vendor/store
• Scalable Microservices: Independent services for different business domains
• Real-time Operations: Event-driven communication between services
• Unified Customer Experience: Single interface for multiple stores
• Flexible Store Management: Customizable storefronts and configurations

Features

For Vendors

• Store Creation: Set up custom storefronts with unique subdomains
• Product Management: Comprehensive product catalog with categories, variants, and inventory
• Order Management: Track orders, manage fulfillment, and handle customer inquiries
• Analytics Dashboard: Monitor sales, track performance, and analyze customer behavior
• Multi-store Support: Manage multiple storefronts from a single dashboard
• Payment Integration: Secure payment processing with multiple gateway support

For Customers

• Unified Shopping Experience: Browse and purchase from multiple stores seamlessly
• Advanced Product Discovery: Search, filter, and compare products across stores
• Secure Shopping Cart: Persistent cart with real-time updates
• Order Tracking: Monitor order status from purchase to delivery
• Secure Payments: Multiple payment methods with encryption
• User Profiles: Manage personal information, order history, and preferences

Technical Architecture

The platform is built using modern technologies and follows microservices best practices:

Frontend

• Framework: Next.js 15 with React 19 and TypeScript
• Styling: Tailwind CSS with responsive design
• State Management: Zustand for client-side state
• Form Handling: React Hook Form with Yup validation
• UI Components: Custom component library with Framer Motion animations

Backend Services

• API Gateway: NestJS-based gateway with GraphQL and REST support
• Authentication Service: JWT-based auth with refresh tokens and role management
• Tenant Service: Multi-tenant management with subdomain routing
• Product Service: Product catalog, categories, and inventory management
• Cart Service: Shopping cart operations and persistence
• Order Service: Order processing, status tracking, and fulfillment
• Payment Service: Payment processing with Paymob integration

Infrastructure

• Database: MongoDB with Mongoose ODM
• Message Broker: RabbitMQ for inter-service communication
• Containerization: Docker with multi-stage builds
• API Protocols: REST APIs and GraphQL endpoints
• Real-time Communication: Event-driven architecture with message queues

Getting Started

Prerequisites

• Docker and Docker Compose
• Node.js 18+ and npm/pnpm
• MongoDB (handled by Docker)
• RabbitMQ (handled by Docker)
• Cloudinary account (for image uploads)

1. Clone and Setup

git clone <repository-url>
cd ITI_GRAD_PROJECT

2. Start Backend Services

cd services
docker-compose up -d

This will start all required services:

• MongoDB (Port 27017)
• RabbitMQ (Port 5672, Management UI: 15672)
• Auth Service (Port 3001)
• Tenant Service (Port 3002)
• Product Service (Port 3003)
• Cart Service (Port 3005)
• Order Service (Port 3006)
• Payment Service (Port 3004)
• API Gateway (Port 3010)

3. Start Frontend Client

cd client
npm install
npm run dev

The client will be available at http://localhost:3000

4. Verify Services

Check service health endpoints:

• API Gateway: http://localhost:3010/health
• Auth Service: http://localhost:3001/health
• Product Service: http://localhost:3003/health
• RabbitMQ Management: http://localhost:15672 (guest/guest)

Service Architecture

API Gateway (Port 3010)

• Purpose: Central entry point for all client requests
• Features: Authentication, routing, rate limiting, CORS handling
• Protocols: REST APIs and GraphQL endpoints
• Integration: Routes requests to appropriate microservices

Authentication Service (Port 3001)

• Purpose: User authentication and authorization
• Features: JWT tokens, refresh tokens, role-based access control
• Endpoints: Login, register, profile management, password reset
• Security: Encrypted passwords, token validation, session management

Tenant Service (Port 3002)

• Purpose: Multi-tenant store management
• Features: Store creation, subdomain management, tenant isolation
• Endpoints: CRUD operations for stores, subdomain validation
• Integration: User ownership, store configuration

Product Service (Port 3003)

• Purpose: Product catalog and inventory management
• Features: Product CRUD, categories, variants, search functionality
• Endpoints: Product operations, category management, search queries
• Integration: Tenant isolation, inventory tracking

Cart Service (Port 3005)

• Purpose: Shopping cart management
• Features: Add/remove items, quantity management, cart persistence
• Endpoints: Cart operations, item management
• Integration: User-specific carts, product validation

Order Service (Port 3006)

• Purpose: Order processing and management
• Features: Order creation, status tracking, fulfillment management
• Endpoints: Order CRUD, status updates, payment confirmation
• Integration: Cart integration, payment processing

Payment Service (Port 3004)

• Purpose: Payment processing and management
• Features: Payment gateway integration, transaction tracking
• Endpoints: Payment operations, status updates
• Integration: Paymob gateway, order confirmation

Development

Project Structure

ITI_GRAD_PROJECT/
├── client/                 # Next.js Frontend Application
│   ├── app/               # App router pages
│   ├── components/        # Reusable UI components
│   ├── lib/              # Utilities and services
│   └── public/           # Static assets
├── services/              # Backend Microservices
│   ├── api-gateway/      # API Gateway service
│   ├── auth/             # Authentication service
│   ├── tenant/           # Tenant management service
│   ├── product/          # Product management service
│   ├── cart/             # Shopping cart service
│   ├── order/            # Order management service
│   └── payment/          # Payment processing service
├── docs/                 # Documentation
└── docker-compose.yml    # Service orchestration

Key Technologies

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• Backend: NestJS, TypeScript, MongoDB, RabbitMQ
• Authentication: JWT with refresh tokens, role-based access control
• State Management: Zustand for client-side state
• Form Handling: React Hook Form with Yup validation
• UI Animations: Framer Motion
• Image Upload: Cloudinary integration
• Payment Processing: Paymob gateway integration

Environment Variables

Client (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:3010
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your-cloud-name
NEXT_PUBLIC_CLOUDINARY_UPLOAD_PRESET=your-upload-preset

Services (docker-compose.yml)

# Database
MONGODB_URI: mongodb://admin:admin123@mongodb:27017/auth-db?authSource=admin

# JWT
JWT_ACCESS_SECRET: your-access-secret
JWT_REFRESH_SECRET: your-refresh-secret

# RabbitMQ
RABBITMQ_URL: amqp://guest:guest@rabbitmq:5672

API Documentation

The platform provides comprehensive APIs through the API Gateway:

• REST Endpoints: Traditional REST API endpoints for all services
• GraphQL: GraphQL schema for flexible data querying
• Authentication: JWT-based authentication with role-based access
• Multi-tenancy: Tenant-scoped API operations
• Real-time Updates: Event-driven updates via message queues