🛍️ E-Commerce Order Management System

📋 Table of Contents

1. Prerequisites
2. Project Structure
3. Database Setup with Flask-SQLAlchemy
4. Flask Services Setup
5. Java JSP Frontend Setup
6. Application Scenarios
7. Testing the System
8. API Documentation
9. Troubleshooting

---

🔧 Prerequisites

Required Software

• Python 3.8+ - Download from python.org
• Java JDK 11+ - Download from Oracle or OpenJDK
• MySQL 8.0+ - Download from mysql.com
• Apache Tomcat 10.x - Download from tomcat.apache.org
• IDE (Optional but recommended):
  • IntelliJ IDEA for Java development
  • VS Code or PyCharm for Python

---

📁 Project Structure

Create the following directory structure:

ecommerce-system/
├── ecommerce_system.sql (optional - for manual setup only)
├── order_service/          (Port 5001)
│   ├── app.py
│   ├── config.py
│   ├── models.py
│   ├── resources.py
│   ├── requirements.txt
├── inventory_service/      (Port 5002)
│   ├── app.py
│   ├── config.py
│   ├── models.py
│   ├── resources.py
│   ├── requirements.txt
├── pricing_service/        (Port 5003)
│   ├── app.py
│   ├── config.py
│   ├── models.py
│   ├── resources.py
│   ├── requirements.txt
├── customer_service/       (Port 5004)
│   ├── app.py
│   ├── config.py
│   ├── models.py
│   ├── resources.py
│   ├── requirements.txt
├── notification_service/   (Port 5005)
│   ├── app.py
│   ├── config.py
│   ├── models.py
│   ├── resources.py
│   ├── requirements.txt
└── Ecommerce_jsp/
    ├── pom.xml
    └── src/
        └── main/
            ├── java/
            │   └── servlets/
            │       ├── OrderServlet.java
            │       ├── ProfileServlet.java
            │       ├── OrderHistoryServlet.java
            │       └── CheckoutServlet.java
            └── webapp/
                ├── main_page.jsp
                ├── checkout.jsp
                ├── confirmation.jsp
                ├── profile.jsp
                └── view_orders_history.jsp

---

🗄️ Database Setup with Flask-SQLAlchemy

Step 1: Create Empty Database

# Login to MySQL
mysql -u root -p

# Create database only
CREATE DATABASE ecommerce_system;

# Create user (optional but recommended)
CREATE USER 'ecommerce_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON ecommerce_system.* TO 'ecommerce_user'@'localhost';
FLUSH PRIVILEGES;
exit;

Note: We will NOT manually create tables. Flask-Migrate will handle all table creation automatically!

Step 2: Understanding Flask-SQLAlchemy Workflow

We use Flask-SQLAlchemy with Flask-Migrate to:

• ✅ Define models in Python (no manual SQL)
• ✅ Auto-generate database tables
• ✅ Track database changes with migrations
• ✅ Easy rollback/upgrade of schema

---

🐍 Flask Services Setup

Step 1: Install Dependencies

For each of the 5 services, create a requirements.txt file:

Flask==3.0.0
Flask-RESTful==0.3.10
Flask-SQLAlchemy==3.1.1
Flask-Migrate==4.0.5
mysqlclient==2.2.0
requests==2.31.0

Step 2: Set Up Each Service

For each service (order, inventory, pricing, customer, notification):

# Navigate to service directory
cd order_service

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Step 3: Configure Database Connection

Create config.py in each service:

class Config:
    # Database configuration
    SQLALCHEMY_DATABASE_URI = 'mysql://ecommerce_user:secure_password@localhost/ecommerce_system'
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    
    # Service URLs for inter-service communication
    ORDER_SERVICE_URL = 'http://localhost:5001'
    INVENTORY_SERVICE_URL = 'http://localhost:5002'
    PRICING_SERVICE_URL = 'http://localhost:5003'
    CUSTOMER_SERVICE_URL = 'http://localhost:5004'
    NOTIFICATION_SERVICE_URL = 'http://localhost:5005'

Important: Update the database credentials:

• Replace ecommerce_user with your MySQL username (or use root)
• Replace secure_password with your MySQL password

Step 4: Initialize Database Migrations

For each service, run these commands:

# Make sure you're in the service directory with venv activated
cd order_service
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Initialize migrations (only first time)
flask --app app db init

# Create initial migration
flask --app app db migrate -m "Initial migration"

# Apply migrations to database
flask --app app db upgrade

What happens:

• flask db init - Creates migrations/ folder
• flask db migrate - Detects model changes and generates migration script
• flask db upgrade - Applies migrations and creates tables in MySQL

Repeat for all 5 services!

Step 5: Insert Sample Data (Optional)

After migrations, you can add sample data via Python or SQL:

# Option 1: Python shell
flask --app app shell
>>> from models import Inventory, db
>>> product = Inventory(product_name='Laptop', quantity_available=50, unit_price=999.99)
>>> db.session.add(product)
>>> db.session.commit()
>>> exit()

# Option 2: MySQL (if you prefer)
mysql -u ecommerce_user -p ecommerce_system < sample_data.sql

Step 6: Start All Services

Open 5 separate terminal windows, one for each service:

Terminal 1 - Order Service (Port 5001):

cd order_service
source venv/bin/activate  # or venv\Scripts\activate on Windows
python app.py

Terminal 2 - Inventory Service (Port 5002):

cd inventory_service
source venv/bin/activate
python app.py

Terminal 3 - Pricing Service (Port 5003):

cd pricing_service
source venv/bin/activate
python app.py

Terminal 4 - Customer Service (Port 5004):

cd customer_service
source venv/bin/activate
python app.py

Terminal 5 - Notification Service (Port 5005):

cd notification_service
source venv/bin/activate
python app.py

Step 7: Verify Services Are Running

Each service should display:

* Running on http://0.0.0.0:500X
* Debug mode: on

Test each service:

# Inventory Service - Get all products
curl http://localhost:5002/api/inventory/products

# Customer Service - Get all customers
curl http://localhost:5004/api/customers/all

# Pricing Service - Calculate price
curl -X POST http://localhost:5003/api/pricing/calculate \
  -H "Content-Type: application/json" \
  -d '{"products":[{"product_id":1,"quantity":2}]}'

---

☕ Java JSP Frontend Setup

Option A: Using IntelliJ IDEA

1. Create New Project

   • File → New Project → Java with Maven → Web Application
   • Project Name: jsp-frontend
   • Server: Apache Tomcat 10.x

2. Add Dependencies to pom.xml

<dependencies>
    <dependency>
        <groupId>jakarta.servlet</groupId>
        <artifactId>jakarta.servlet-api</artifactId>
        <version>6.0.0</version>
        <scope>provided</scope>
    </dependency>
    
    <dependency>
        <groupId>jakarta.servlet.jsp</groupId>
        <artifactId>jakarta.servlet.jsp-api</artifactId>
        <version>3.1.0</version>
        <scope>provided</scope>
    </dependency>
    
    <dependency>
        <groupId>org.json</groupId>
        <artifactId>json</artifactId>
        <version>20231013</version>
    </dependency>
</dependencies>

3. Create Servlets

   • Create servlets for each scenario (see Application Scenarios section)
   • Place in src/main/java/servlets/

4. Create JSP Pages

   • Create all JSP pages (index, checkout, confirmation, profile, view_orders_history)
   • Place in src/main/webapp/

5. Build and Deploy

   • Build → Build Project
   • Run → Run on Tomcat
   • IntelliJ will deploy to Tomcat automatically

Option B: Using Maven Command Line

cd jsp-frontend

# Build the WAR file
mvn clean package

# Deploy to Tomcat
cp target/jsp-frontend.war /path/to/tomcat/webapps/

# Start Tomcat
cd /path/to/tomcat/bin
./startup.sh  # Linux/Mac
startup.bat   # Windows

---

🎬 Application Scenarios

Scenario 1: Making an Order (Main Flow)

Flow:

1. Main Page (index.jsp)

   • Display all products where quantity > 0
   • Links to: Profile page, Orders history page
   • Customer selects products and quantities
   • Click "Make Order" button

2. CheckoutServlet

   • Validates: selected quantity ≤ available quantity
   • Calls Inventory Service: GET /api/inventory/check/{product_id}
   • Calls Pricing Service: POST /api/pricing/calculate
   • Forwards to checkout.jsp

3. Checkout Page (checkout.jsp)

   • Shows products, quantities, and prices
   • Customer can: Cancel (go to main) or Confirm

4. OrderServlet (when customer confirms)

   • Reads: customer_id, products, quantities, total_amount
   • Calls Order Service: POST /api/orders/create
   • Calls Customer Service: PUT /api/customers/{customer_id}/loyalty
   • Calls Notification Service: POST /api/notifications/send
   • Forwards to confirmation.jsp

5. Confirmation Page (confirmation.jsp)

   • Shows order details and success message

Endpoints Used:

• GET /api/inventory/products (Inventory Service)
• GET /api/inventory/check/{product_id} (Inventory Service)
• POST /api/pricing/calculate (Pricing Service)
• POST /api/orders/create (Order Service)
• PUT /api/customers/{customer_id}/loyalty (Customer Service)
• POST /api/notifications/send (Notification Service)

---

Scenario 2: View Customer Profile

Flow:

1. Customer clicks "Profile" link on main page

2. ProfileServlet is called

   • Reads customer_id from session
   • Calls Customer Service: GET /api/customers/{customer_id}
   • Gets customer details including loyalty points
   • Forwards to profile.jsp

3. Profile Page (profile.jsp)

   • Displays customer information
   • Shows loyalty points

Endpoints Used:

• GET /api/customers/{customer_id} (Customer Service)

---

Scenario 3: View Order History

Flow:

1. Customer clicks "View Orders History" on main page

2. OrderHistoryServlet is called

   • Reads customer_id from session
   • Calls Customer Service: GET /api/customers/{customer_id}/orders
   • For each order, calls Order Service: GET /api/orders/{order_id}
   • Aggregates all order details
   • Forwards to view_orders_history.jsp

3. Order History Page (view_orders_history.jsp)

   • Displays all previous orders
   • Shows order details, products, amounts, dates

Endpoints Used:

• GET /api/customers/{customer_id}/orders (Customer Service)
• GET /api/orders/{order_id} (Order Service)

---

🧪 Testing the System

Step 1: Verify All Services Are Running

Check that you have:

• ✅ 5 Flask services running (ports 5001-5005)
• ✅ MySQL database with tables created by migrations
• ✅ Sample data in database
• ✅ Tomcat server running (port 8080)
• ✅ JSP application deployed

Step 2: Verify Database Tables Created

USE ecommerce_system;
SHOW TABLES;

-- You should see tables:
-- orders, inventory, customers, pricing_rules, tax_rates, notification_log

Step 3: Add Sample Data (if not already added)

-- Sample products
INSERT INTO inventory (product_name, quantity_available, unit_price) VALUES
('Laptop', 50, 999.99),
('Mouse', 200, 29.99),
('Keyboard', 150, 79.99),
('Monitor', 75, 299.99),
('Headphones', 100, 149.99);

-- Sample customers
INSERT INTO customers (name, email, phone, loyalty_points) VALUES
('Ahmed Hassan', 'ahmed@example.com', '01012345678', 100),
('Sara Mohamed', 'sara@example.com', '01098765432', 250),
('Omar Ali', 'omar@example.com', '01055555555', 50);

-- Sample pricing rules
INSERT INTO pricing_rules (product_id, min_quantity, discount_percentage) VALUES
(1, 5, 10.00),
(2, 10, 15.00),
(3, 10, 12.00);

-- Sample tax rates
INSERT INTO tax_rates (region, tax_rate) VALUES
('Egypt', 14.00),
('Default', 10.00);

Step 4: Access the Application

Open your browser and navigate to:

http://localhost:8080/Ecommerce_jsp/main_page.jsp

Step 5: Test Each Scenario

Test Scenario 1: Making an Order

1. Browse products on main page
2. Select products and quantities
3. Click "Make Order"
4. Verify prices on checkout page
5. Click "Confirm"
6. Check confirmation page shows order details

Test Scenario 2: View Profile

1. Click "Profile" link
2. Verify customer details displayed
3. Check loyalty points shown

Test Scenario 3: View Order History

1. Click "View Orders History" link
2. Verify all previous orders displayed
3. Check order details are complete

Step 6: Verify Backend Operations

Check database changes:

-- Check orders created
SELECT * FROM orders ORDER BY created_at DESC LIMIT 5;

-- Check inventory updated
SELECT * FROM inventory;

-- Check loyalty points updated
SELECT name, loyalty_points FROM customers;

-- Check notifications logged
SELECT * FROM notification_log ORDER BY sent_at DESC LIMIT 5;

Check API endpoints:

# Get all products (only with quantity > 0)
curl http://localhost:5002/api/inventory/products

# Get customer profile
curl http://localhost:5004/api/customers/1

# Get customer order history
curl http://localhost:5004/api/customers/1/orders

# Get specific order
curl http://localhost:5001/api/orders/1

---

📚 API Documentation

Inventory Service (Port 5002)

Method	Endpoint	Description	Used In
GET	/api/inventory/products	Get all products (quantity > 0)	Scenario 1 - Main Page
GET	/api/inventory/check/{product_id}	Check stock availability	Scenario 1 - Checkout
PUT	/api/inventory/update	Update inventory	Internal

Pricing Service (Port 5003)

Method	Endpoint	Description	Used In
POST	/api/pricing/calculate	Calculate order total with discounts/tax	Scenario 1 - Checkout

Order Service (Port 5001)

Method	Endpoint	Description	Used In
POST	/api/orders/create	Create new order	Scenario 1 - Order Confirmation
GET	/api/orders/{order_id}	Get order details	Scenario 3 - Order History
GET	/api/orders?customer_id=X	Get orders by customer	Internal

Customer Service (Port 5004)

Method	Endpoint	Description	Used In
GET	/api/customers/all	Get all customers	Internal
GET	/api/customers/{customer_id}	Get customer profile	Scenario 2 - Profile
GET	/api/customers/{customer_id}/orders	Get customer order history	Scenario 3 - Order History
PUT	/api/customers/{customer_id}/loyalty	Update loyalty points	Scenario 1 - After Order

Notification Service (Port 5005)

Method	Endpoint	Description	Used In
POST	/api/notifications/send	Send order notification	Scenario 1 - After Order
GET	/api/notifications/history/{customer_id}	Get notification history	Internal

---

🔧 Troubleshooting

Common Issues and Solutions

1. Flask-Migrate Issues

Error: No such command "db"

Solution:

# Make sure Flask-Migrate is installed
pip install Flask-Migrate

# Verify app.py has proper setup
# from flask_migrate import Migrate
# migrate = Migrate(app, db)

2. Migration Failed

Error: Can't locate revision identified by 'xxxxx'

Solution:

# Delete migrations folder and start over
rm -rf migrations/
flask --app app db init
flask --app app db migrate -m "Initial"
flask --app app db upgrade

3. Database Connection Error

Error: Access denied for user 'ecommerce_user'@'localhost'

Solution:

-- Check user exists
SELECT User, Host FROM mysql.user WHERE User='ecommerce_user';

-- Grant privileges
GRANT ALL PRIVILEGES ON ecommerce_system.* TO 'ecommerce_user'@'localhost';
FLUSH PRIVILEGES;

4. mysqlclient Installation Failed

Error: Failed building wheel for mysqlclient

Solution:

# On Ubuntu/Debian
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential

# On MacOS
brew install mysql

# On Windows
# Download mysqlclient wheel from:
# https://www.lfd.uci.edu/~gohlke/pythonlibs/#mysqlclient
pip install mysqlclient‑xxx.whl

5. Port Already in Use

Error: Address already in use: bind

Solution:

# Find and kill process
lsof -i :5001  # Linux/Mac
netstat -ano | findstr :5001  # Windows

kill -9 <PID>  # Linux/Mac
taskkill /PID <PID> /F  # Windows

6. Service Communication Failed

Error: Connection refused when calling other services

Solution:

• Verify all 5 services are running
• Check service URLs in config.py
• Test each service individually with curl
• Check firewall settings

🚀 Quick Start Commands Summary

# 1. Create database
mysql -u root -p
CREATE DATABASE ecommerce_system;

# 2. For each service:
cd service_name
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 3. Initialize migrations (each service)
flask --app app db init
flask --app app db migrate -m "Initial"
flask --app app db upgrade

# 4. Start service
python app.py

# 5. Build and deploy JSP
cd Ecommerce_jsp
mvn clean package
# Deploy to Tomcat

# 6. Access application
http://localhost:8080/Ecommerce_jsp/main_page.jsp

---

📞 Support

If you encounter issues:

1. Check the troubleshooting section above
2. Review service logs in terminal windows
3. Check Flask migration status: flask --app app db current
4. Verify database tables: SHOW TABLES; in MySQL
5. Check Tomcat logs in tomcat/logs/