🛒 CloudRetail - Enterprise E-Commerce Platform

A production-ready, scalable microservices-based e-commerce platform deployed on AWS

Features • Architecture • Tech Stack • Getting Started • API Docs • Deployment

---

📋 Table of Contents

• Overview
• Features
• Architecture
• Tech Stack
• Project Structure
• Getting Started
• AWS Services
• API Documentation
• Security
• Monitoring & Logging
• Contributing
• License

---

🌟 Overview

CloudRetail is a full-stack, cloud-native e-commerce platform built with modern microservices architecture. Designed for scalability, reliability, and security, it demonstrates enterprise-level cloud deployment practices using AWS services.

This project showcases:

• ✅ Microservices Architecture - Independent, scalable services
• ✅ Event-Driven Design - Asynchronous communication using AWS EventBridge
• ✅ Saga Pattern - Distributed transaction management
• ✅ Cloud-Native Deployment - Containerized services on AWS ECS
• ✅ Production-Ready - Complete CI/CD, monitoring, and security

---

✨ Features

🛍️ Customer Features

• 🔐 User Authentication - JWT-based auth with Amazon Cognito
• 📦 Product Catalog - Browse products with advanced search and filtering
• 🛒 Shopping Cart - Real-time cart management
• 💳 Multiple Payment Methods - Credit Card, PayPal, Bank Transfer
• 📧 Order Notifications - Email updates via Amazon SES
• 👤 User Profile - Manage account details and order history
• ⭐ Product Reviews - Rate and review products

👨‍💼 Admin Features

• 📊 Analytics Dashboard - Real-time sales and inventory metrics
• 📦 Inventory Management - Low stock alerts and automatic notifications
• 🏷️ Product Management - CRUD operations for products
• 📈 Order Management - Track and update order statuses
• 👥 User Management - Customer accounts administration

🔧 Technical Features

• 🔄 Event-Driven Architecture - EventBridge for service communication
• 🔁 Saga Orchestration - Reliable distributed transactions
• 🐳 Containerization - Docker containers on AWS ECS
• 🗄️ Database Persistence - MySQL on Amazon RDS
• 🌐 CDN Distribution - Amazon CloudFront for static assets
• 🔒 Security - WAF protection, encryption at rest/transit
• 📊 Monitoring - CloudWatch metrics and alarms
• 💾 Automated Backups - AWS Backup for data protection

---

🏗️ Architecture

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         USER LAYER                               │
│  ┌──────────────┐                          ┌──────────────┐     │
│  │   Browser    │──────────────────────────│  Mobile App  │     │
│  └──────────────┘                          └──────────────┘     │
└────────────┬────────────────────────────────────────┬───────────┘
             │                                         │
             └─────────────────┬───────────────────────┘
                               │ HTTPS
                    ┌──────────▼──────────┐
                    │  Amazon CloudFront  │ ← CDN
                    │    + AWS WAF        │ ← Security
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │   AWS API Gateway   │ ← API Management
                    └──────────┬──────────┘
                               │
┌──────────────────────────────┴──────────────────────────────────┐
│                    MICROSERVICES LAYER (ECS)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │     User     │  │   Product    │  │    Order     │          │
│  │   Service    │  │   Service    │  │   Service    │          │
│  │  (Port 3001) │  │  (Port 3003) │  │  (Port 3002) │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                  │                  │                  │
│  ┌──────┴───────┐  ┌──────┴───────┐  ┌──────┴───────┐          │
│  │   Payment    │  │  Inventory   │  │   Customer   │          │
│  │   Service    │  │   Service    │  │   Products   │          │
│  │  (Port 3005) │  │  (Port 3004) │  │   Service    │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                  │                  │                  │
│         └──────────────────┴──────────────────┘                 │
│                            │                                     │
│                   ┌────────▼────────┐                           │
│                   │  Saga           │                           │
│                   │  Orchestrator   │                           │
│                   └────────┬────────┘                           │
└────────────────────────────┴──────────────────────────────────┐
                             │                                    │
                   ┌─────────▼─────────┐                         │
                   │  Amazon EventBridge│ ← Event Bus            │
                   └─────────┬─────────┘                         │
                             │                                    │
              ┌──────────────┼──────────────┐                    │
              │              │              │                    │
     ┌────────▼───────┐ ┌───▼──────┐ ┌────▼──────┐             │
     │  AWS Lambda    │ │  Lambda  │ │  Lambda   │             │
     │  Order Event   │ │ Welcome  │ │ Payment   │             │
     │  Handler       │ │  Email   │ │Confirmation│             │
     └────────┬───────┘ └───┬──────┘ └────┬──────┘             │
              │             │              │                    │
              └─────────────┴──────────────┘                    │
                            │                                    │
                   ┌────────▼────────┐                          │
                   │  Amazon SES     │ ← Email Service          │
                   └─────────────────┘                          │
                                                                 │
┌────────────────────────────────────────────────────────────────┘
│                     DATA LAYER                                 │
│  ┌──────────────────┐         ┌──────────────────┐            │
│  │   Amazon RDS     │◄────────│  AWS Backup      │            │
│  │   (MySQL 8.0)    │         │  (Daily Backups) │            │
│  └──────────────────┘         └──────────────────┘            │
│  ┌──────────────────┐         ┌──────────────────┐            │
│  │   Amazon S3      │         │  Amazon ECR      │            │
│  │  (Images/Assets) │         │ (Docker Images)  │            │
│  └──────────────────┘         └──────────────────┘            │
└────────────────────────────────────────────────────────────────┘

Key Design Patterns

• 🎯 Microservices Pattern - Independent, loosely coupled services
• 🔄 Event-Driven Architecture - Asynchronous messaging via EventBridge
• 🎭 Saga Pattern - Distributed transaction coordination
• 🔌 API Gateway Pattern - Centralized API management
• 🏪 CQRS Lite - Separation of concerns in data operations
• 💾 Database per Service - Each service manages its own data

---

🚀 Tech Stack

Frontend

• Framework: Vue.js 3.x
• State Management: Vuex
• HTTP Client: Axios
• Routing: Vue Router
• UI Components: Custom + Bootstrap

Backend

• Runtime: Node.js (v18.x)
• Framework: Express.js
• Database: MySQL 8.0
• Authentication: JWT + bcrypt
• ORM: Raw SQL with connection pooling
• API Specs: OpenAPI 3.0 (Swagger)

DevOps & Infrastructure

• Containerization: Docker
• Cloud Platform: AWS
• Version Control: Git/GitHub
• Scripts: PowerShell, Bash

---

☁️ AWS Services Used

Service	Purpose	Configuration
Amazon ECS	Container orchestration for microservices	EC2 launch type, 7 services
Amazon EC2	Compute instances for ECS tasks	t3.small instance
Amazon RDS	Managed MySQL database	db.t3.micro, Multi-AZ ready
AWS Lambda	Serverless event handlers	7 functions (Node.js 18.x)
Amazon EventBridge	Event bus for service communication	Custom event patterns
Amazon API Gateway	REST API management	Regional endpoint
Amazon CloudFront	CDN for frontend assets	Global edge locations
Amazon S3	Static asset storage	2 buckets with versioning
Amazon ECR	Docker image registry	14 repositories
AWS WAF	Web application firewall	CloudFront protection
Amazon Cognito	User authentication	User pool with JWT
Amazon SES	Email notifications	Verified domains
Amazon CloudWatch	Monitoring and logging	Custom metrics, alarms
AWS Backup	Automated database backups	Daily backups, 7-day retention
AWS IAM	Identity and access management	Least privilege policies
AWS KMS	Encryption key management	Data encryption at rest

---

📁 Project Structure

CloudRetail/
├── 📂 frontend/                    # Vue.js Frontend Application
│   ├── src/
│   │   ├── components/            # Reusable Vue components
│   │   ├── views/                 # Page components
│   │   ├── router/                # Vue Router configuration
│   │   ├── store/                 # Vuex state management
│   │   ├── services/              # API service layer
│   │   └── App.vue                # Root component
│   ├── public/                    # Static assets
│   ├── package.json
│   └── Dockerfile
│
├── 📂 backend/                     # Microservices Backend
│   ├── api-gateway/               # API Gateway Service (Port 3000)
│   │   ├── index.js
│   │   ├── package.json
│   │   └── Dockerfile
│   │
│   ├── user-service/              # User Management (Port 3001)
│   │   ├── index.js
│   │   ├── routes/
│   │   ├── controllers/
│   │   ├── models/
│   │   └── Dockerfile
│   │
│   ├── product-service/           # Product Catalog (Port 3003)
│   │   ├── index.js
│   │   ├── routes/
│   │   └── Dockerfile
│   │
│   ├── order-service/             # Order Processing (Port 3002)
│   │   ├── index.js
│   │   ├── routes/
│   │   └── Dockerfile
│   │
│   ├── payment-service/           # Payment Processing (Port 3005)
│   │   ├── index.js
│   │   └── Dockerfile
│   │
│   ├── inventory-service/         # Inventory Management (Port 3004)
│   │   ├── index.js
│   │   └── Dockerfile
│   │
│   ├── customer-products-service/ # Seller Products (Port 3006)
│   │   ├── index.js
│   │   └── Dockerfile
│   │
│   ├── saga-orchestrator/         # Distributed Transaction Coordinator
│   │   ├── index.js
│   │   └── Dockerfile
│   │
│   ├── database/                  # Database Scripts
│   │   ├── schema.sql
│   │   ├── init.sql
│   │   └── migrations/
│   │
│   └── eventbridge-simulator.js  # Local EventBridge testing
│
├── 📂 lambda-functions/            # AWS Lambda Functions
│   ├── order-notification/
│   ├── welcome-email/
│   ├── payment-confirmation/
│   ├── low-inventory-alert/
│   ├── order-status-update/
│   └── product-notification/
│
├── 📂 infrastructure/              # Infrastructure as Code
│   ├── cloudformation/            # CloudFormation templates
│   ├── terraform/                 # Terraform configurations (optional)
│   └── diagrams/                  # Architecture diagrams
│
├── 📂 ecs-tasks/                   # ECS Task Definitions
│   ├── user-service.json
│   ├── product-service.json
│   ├── order-service.json
│   └── ... (other services)
│
├── 📂 deployment-scripts/          # Deployment Automation
│   ├── deploy-to-aws.ps1
│   ├── setup-ecs.ps1
│   ├── setup-rds.ps1
│   ├── deploy-lambda.ps1
│   └── stop-all-aws.ps1
│
├── 📂 configs/                     # Configuration Files
│   ├── CloudRetail-API.postman_collection.json
│   ├── cloudwatch-dashboard.json
│   ├── waf-config.json
│   └── grafana-dashboard-k6.json
│
├── 📂 scripts/                     # Utility Scripts
│   ├── populate-db.js
│   ├── backup-db.sh
│   └── health-check.ps1
│
├── 📂 testing-showcase/            # Testing & Load Tests
│   ├── k6/                        # Load testing scripts
│   └── integration/               # Integration tests
│
├── 📄 docker-compose.yml           # Local development setup
├── 📄 swagger.yaml                 # API documentation (OpenAPI 3.0)
├── 📄 package.json                 # Root package configuration
├── 📄 README.md                    # This file
└── 📄 .gitignore

---

🚀 Getting Started

Prerequisites

• Node.js v18.x or higher
• Docker & Docker Compose
• MySQL 8.0 (or use Docker)
• AWS Account (for cloud deployment)
• AWS CLI configured

Local Development Setup

1️⃣ Clone the Repository

git clone https://github.com/yourusername/CloudRetail.git
cd CloudRetail

2️⃣ Install Dependencies

# Install root dependencies
npm install

# Install backend dependencies
cd backend/user-service && npm install
cd ../product-service && npm install
cd ../order-service && npm install
# ... repeat for other services

# Install frontend dependencies
cd ../../frontend
npm install

3️⃣ Set Up Environment Variables

Create .env files in each service directory:

# backend/user-service/.env
PORT=3001
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=cloudretail
JWT_SECRET=your_jwt_secret_key
AWS_REGION=us-east-1
EVENTBRIDGE_BUS_NAME=cloudretail-events

4️⃣ Set Up Database

# Start MySQL using Docker
docker-compose up -d mysql

# Import database schema
mysql -u root -p cloudretail < backend/database/schema.sql

# Populate with sample data (optional)
node scripts/populate-db.js

5️⃣ Start All Services (Local)

Option A: Using Docker Compose

docker-compose up --build

Option B: Manual Start

# Terminal 1 - User Service
cd backend/user-service
npm start

# Terminal 2 - Product Service
cd backend/product-service
npm start

# Terminal 3 - Order Service
cd backend/order-service
npm start

# Terminal 4 - Payment Service
cd backend/payment-service
npm start

# Terminal 5 - Inventory Service
cd backend/inventory-service
npm start

# Terminal 6 - API Gateway
cd backend/api-gateway
npm start

# Terminal 7 - Frontend
cd frontend
npm run serve

6️⃣ Access the Application

• Frontend: http://localhost:8080
• API Gateway: http://localhost:3000
• Swagger UI: http://localhost:3000/api-docs
• Health Check: http://localhost:3000/health

---

🌩️ Deployment

Deploy to AWS

Prerequisites

• AWS CLI configured with appropriate credentials
• Docker installed for building images
• PowerShell (for Windows) or Bash (for Linux/Mac)

Automated Deployment

# 1. Build and push Docker images to ECR
.\deployment-scripts\build-and-push-ecr.ps1

# 2. Set up RDS database
.\deployment-scripts\setup-rds.ps1

# 3. Deploy ECS services
.\deployment-scripts\setup-ecs.ps1

# 4. Deploy Lambda functions
.\deployment-scripts\deploy-lambda.ps1

# 5. Configure API Gateway
.\deployment-scripts\setup-api-gateway.ps1

# 6. Deploy frontend to S3 + CloudFront
.\deployment-scripts\deploy-frontend.ps1

Manual Deployment Steps

1. Create ECR Repositories

aws ecr create-repository --repository-name cloudretail/user-service
aws ecr create-repository --repository-name cloudretail/product-service
# ... create for all services

2. Build and Push Docker Images

# Login to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com

# Build and push each service
cd backend/user-service
docker build -t cloudretail/user-service .
docker tag cloudretail/user-service:latest <account-id>.dkr.ecr.us-east-1.amazonaws.com/cloudretail/user-service:latest
docker push <account-id>.dkr.ecr.us-east-1.amazonaws.com/cloudretail/user-service:latest

3. Create ECS Cluster

aws ecs create-cluster --cluster-name cloudretail-cluster

4. Register Task Definitions

aws ecs register-task-definition --cli-input-json file://ecs-tasks/user-service.json
aws ecs register-task-definition --cli-input-json file://ecs-tasks/product-service.json
# ... register all task definitions

5. Create ECS Services

aws ecs create-service \
  --cluster cloudretail-cluster \
  --service-name user-service \
  --task-definition user-service:1 \
  --desired-count 1 \
  --launch-type EC2

6. Deploy Lambda Functions

cd lambda-functions/order-notification
zip -r function.zip .
aws lambda create-function \
  --function-name order-notification \
  --runtime nodejs18.x \
  --role arn:aws:iam::<account>:role/lambda-role \
  --handler index.handler \
  --zip-file fileb://function.zip

---

📚 API Documentation

Interactive API Docs

Access Swagger UI at: http://localhost:3000/api-docs (local) or your API Gateway URL

Base URL

Production: https://aygfmjsp82.execute-api.us-east-1.amazonaws.com/prod
Local: http://localhost:3000

Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Key Endpoints

Authentication

POST   /users/register          # Register new user
POST   /users/login             # Login
GET    /users/profile           # Get user profile (Auth required)
PUT    /users/profile           # Update profile (Auth required)

Products

GET    /products                # List all products
GET    /products/:id            # Get product details
POST   /products                # Create product (Admin)
PUT    /products/:id            # Update product (Admin)
DELETE /products/:id            # Delete product (Admin)
GET    /products/search?q=      # Search products

Orders

POST   /orders                  # Create new order (Auth required)
GET    /orders                  # Get user orders (Auth required)
GET    /orders/:id              # Get order details (Auth required)
PUT    /orders/:id/status       # Update order status (Admin)
POST   /orders/:id/cancel       # Cancel order (Auth required)

Payments

POST   /payments                # Process payment (Auth required)
GET    /payments/:id            # Get payment details (Auth required)
POST   /payments/:id/refund     # Refund payment (Admin)

Inventory

GET    /inventory/:productId    # Check stock availability
PUT    /inventory/:productId    # Update stock (Admin)
POST   /inventory/alerts        # Configure low-stock alerts (Admin)

Response Format

Success Response:

{
  "success": true,
  "data": {
    // ... response data
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

---

🔒 Security

Authentication & Authorization

• 🔐 JWT Tokens - Stateless authentication
• 👤 Amazon Cognito - User pool management
• 🔑 bcrypt - Password hashing (10 salt rounds)
• 🎫 Role-Based Access Control (RBAC) - Admin vs. Customer roles

Data Security

• 🔒 Encryption at Rest - AWS KMS for RDS encryption
• 🔐 Encryption in Transit - TLS/SSL everywhere
• 🛡️ AWS WAF - Protection against common web exploits
• 🔍 Input Validation - SQL injection prevention
• 🚫 CORS Configuration - Controlled cross-origin requests

Network Security

• 🔐 VPC Isolation - Private subnets for backend services
• 🔒 Security Groups - Strict firewall rules
• 🛡️ WAF Rules - Rate limiting, IP filtering
• 🔐 Secrets Management - AWS Secrets Manager

Best Practices Implemented

• ✅ Principle of least privilege (IAM policies)
• ✅ Regular security updates
• ✅ Database connection pooling with limits
• ✅ Request rate limiting
• ✅ SQL injection prevention (parameterized queries)
• ✅ XSS protection
• ✅ CSRF tokens for state-changing operations

---

📊 Monitoring & Logging

Amazon CloudWatch

• Metrics Collected:

  • API Gateway request count, latency, 4XX/5XX errors
  • ECS CPU/Memory utilization per service
  • RDS connections, CPU, storage
  • Lambda invocations, errors, duration

• CloudWatch Alarms:

  • High API error rate (>5% 5XX errors)
  • High API latency (>3 seconds)
  • High ECS CPU (>80%)
  • Lambda errors
  • Low RDS storage

Logging

• Service Logs: CloudWatch Logs for all ECS services
• Lambda Logs: Automatic CloudWatch Logs integration
• API Gateway Logs: Access logs and execution logs
• Structured Logging: JSON format for easy parsing

Health Checks

# Check all services health
curl http://localhost:3000/health

# Individual service health
curl http://localhost:3001/health  # User Service
curl http://localhost:3002/health  # Order Service
curl http://localhost:3003/health  # Product Service

---

🧪 Testing

Load Testing with K6

cd testing-showcase/k6
k6 run load-test.js

Integration Tests

npm test

Postman Collection

Import the collections from /configs directory:

• CloudRetail-API.postman_collection.json - API testing
• CloudRetail-Complete-Workflow.postman_collection.json - End-to-end flows

---

📈 Performance

Benchmarks

• API Response Time: < 200ms average
• Database Queries: < 50ms average
• Order Processing: < 2 seconds end-to-end
• Concurrent Users: Tested up to 1000 simultaneous users
• Throughput: 500+ requests/second

Optimization Techniques

• Database connection pooling
• Redis caching (ready for implementation)
• CDN for static assets (CloudFront)
• Horizontal scaling with ECS
• Async event processing with EventBridge
• Database indexes on frequently queried columns

---

🛠️ Troubleshooting

Common Issues

1. Services can't connect to database

# Check RDS security group allows ECS security group
# Verify connection string in environment variables
# Test connectivity from EC2 instance

2. ECS services stuck in "PENDING"

# Check ECS task logs
aws ecs describe-tasks --cluster cloudretail-cluster --tasks <task-id>

# Common causes: Docker image pull failures, port conflicts

3. Lambda function timeouts

# Increase timeout in function configuration
# Check CloudWatch Logs for errors
# Verify VPC configuration if using VPC

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Code Style

• Use ESLint configuration (.eslintrc.js)
• Follow JavaScript Standard Style
• Write meaningful commit messages
• Add tests for new features

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👨‍💻 Author

Nimsha Fernando

• GitHub: nimshafernando
• LinkedIn: Nimsha Fernando
• Email: nimsha.fernando@gmail.com

---

🙏 Acknowledgments

• AWS Documentation and Best Practices
• Node.js and Express.js communities
• Vue.js ecosystem
• Open source contributors

---

📞 Support

For support and questions:

• 📧 Email: nimsha.riveen@gmail.com
• 💬 Issues: GitHub Issues
• 📖 Documentation: Wiki

---

⭐ Star this repository if you find it helpful!

Made with ❤️ by [Nimsha Fernando]