Full Sync: Explicit Commit Operations (Pure & Optimized)

Dockerfile

@@ -0,0 +1,39 @@
+# Forced Rebuild 2026-03-27T17:15
+
+# Use an official Python runtime as a parent image
+FROM python:3.11-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    fonts-dejavu-core \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy the requirements file into the container
+COPY requirements.txt .
+
+# Install any needed packages specified in requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application code into the container
+COPY . .
+
+# Hugging Face Spaces runs as user with UID 1000
+# Grant ownership of /app so SQLite DB can be created and written
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Expose port 7860 as required by Hugging Face Spaces
+EXPOSE 7860
+
+# Define environment variables
+ENV PYTHONUNBUFFERED=1
+ENV HOST=0.0.0.0
+ENV PORT=7860
+ENV DATABASE_URL=sqlite:///./vortex.db
+
+# Command to run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--proxy-headers", "--forwarded-allow-ips='*'"]

README.md

@@ -0,0 +1,17 @@
+---
+title: VortexCommerce Backend
+emoji: 🚀
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# VortexCommerce Backend
+
+AI-Powered Bilingual E-Commerce Platform backend.
+
+## Admin Credentials
+- **Email**: admin@vortex.com
+- **Password**: admin123

alembic.ini

@@ -0,0 +1,116 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+script_location = migrations
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python>=3.9 or backports.zoneinfo library.
+# Any required deps can installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to migrations/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "version_path_separator" below.
+# version_locations = %(here)s/bar:%(here)s/bat:migrations/versions
+
+# version path separator; As mentioned above, this is the character used to split
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
+#
+# version_path_separator = :
+# version_path_separator = ;
+# version_path_separator = space
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the exec runner, execute a binary
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = %(here)s/.venv/bin/ruff
+# ruff.options = --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

app/__init__.py

@@ -0,0 +1 @@
+# App package

app/api/__init__.py

@@ -0,0 +1 @@
+# API package

app/api/admin.py

@@ -0,0 +1,820 @@
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlalchemy.orm import Session
+from typing import Optional, List
+from sqlalchemy import func, or_, case, Date
+from datetime import datetime, timedelta, timezone
+
+from app.db.base import get_db
+from app.models.user import User, UserRole
+from app.models.order import Order, OrderStatus, Payment, PaymentDetail
+from app.models.product import Product, ProductImage, ProductAudit
+from app.api.auth import get_current_user
+import json
+import os
+from app.core.logging import log_audit_event
+
+router = APIRouter(prefix="/admin", tags=["Administration"])
+
+def check_admin(user_id: int, db: Session):
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user or user.role != UserRole.ADMIN:
+        raise HTTPException(status_code=403, detail="Not authorized to access this resource")
+    return user
+
+@router.get("/fix-slugs")
+def admin_fix_slugs(
+    db: Session = Depends(get_db)
+):
+    """Temporary endpoint to fix missing slugs on remote database."""
+    import uuid
+    import json
+    import os
+    from app.models.product import Product
+    from app.core.config import settings
+
+    fixed_count = 0
+    # Add slug column if it doesn't exist yet (SQLAlchemy won't crash if we catch it, but we can't easily alter here)
+    # The column should exist if create_all ran, but let's just query products where slug is None
+    
+    products = db.query(Product).filter(Product.slug == None).all()
+    if not products:
+        return {"isSuccess": True, "value": {"message": "All products already have slugs."}}
+        
+    # Load Extra items to match legacy refs
+    extra_items = []
+    json_path = os.path.join(settings.DATA_DIR, "app/data/extra_products_vortex.json")
+    if os.path.exists(json_path):
+        with open(json_path, 'r', encoding='utf-8') as f:
+            extra_data = json.load(f)
+            extra_items = extra_data.get("products", [])
+
+    for prod in products:
+        # 1. Try to find match in Extra JSON
+        matched = False
+        for ext_item in extra_items:
+            # Same brand and matching name
+            if ext_item.get("name_ar") == prod.name_ar or ext_item.get("name_en") == prod.name_en:
+                legacy_ref = ext_item.get("legacy_ref") or ext_item.get("sku_base")
+                if legacy_ref:
+                    prod.slug = legacy_ref
+                    matched = True
+                    break
+        
+        # 2. Fallback if no match found
+        if not matched:
+            prod.slug = f"vortex-product-{prod.id or uuid.uuid4().hex[:8]}"
+            
+        fixed_count += 1
+
+    db.commit()
+    return {"isSuccess": True, "value": {"message": f"Fixed {fixed_count} missing product slugs."}}
+
+@router.get("/dashboard/stats")
+def get_dashboard_stats(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get overview statistics for the admin dashboard.
+    """
+    check_admin(current_user_id, db)
+    
+    # Time ranges
+    now = datetime.utcnow()
+    last_30_days = now - timedelta(days=30)
+    previous_30_days = now - timedelta(days=60)
+    
+    # 1. Total Revenue
+    revenue_result = db.query(func.sum(Order.total_price)).filter(
+        Order.status != OrderStatus.CANCELLED,
+        Order.created_at >= last_30_days
+    ).scalar()
+    total_revenue = float(revenue_result) if revenue_result else 0.0
+    
+    prev_revenue_result = db.query(func.sum(Order.total_price)).filter(
+        Order.status != OrderStatus.CANCELLED,
+        Order.created_at >= previous_30_days,
+        Order.created_at < last_30_days
+    ).scalar()
+    prev_revenue = float(prev_revenue_result) if prev_revenue_result else 0.0
+    
+    revenue_trend = 0.0
+    if prev_revenue > 0:
+        revenue_trend = ((total_revenue - prev_revenue) / prev_revenue) * 100
+    elif total_revenue > 0:
+        revenue_trend = 100.0
+        
+    # 2. Total Orders
+    total_orders = db.query(func.count(Order.id)).filter(
+        Order.created_at >= last_30_days
+    ).scalar() or 0
+    
+    prev_orders = db.query(func.count(Order.id)).filter(
+        Order.created_at >= previous_30_days,
+        Order.created_at < last_30_days
+    ).scalar() or 0
+    
+    orders_trend = 0.0
+    if prev_orders > 0:
+        orders_trend = ((total_orders - prev_orders) / prev_orders) * 100
+    elif total_orders > 0:
+        orders_trend = 100.0
+    
+    # 3. Total Customers
+    total_customers = db.query(func.count(User.id)).filter(
+        User.role == UserRole.CUSTOMER
+    ).scalar() or 0
+    
+    new_customers = db.query(func.count(User.id)).filter(
+        User.role == UserRole.CUSTOMER,
+        User.created_at >= last_30_days
+    ).scalar() or 0
+    
+    prev_new_customers = db.query(func.count(User.id)).filter(
+        User.role == UserRole.CUSTOMER,
+        User.created_at >= previous_30_days,
+        User.created_at < last_30_days
+    ).scalar() or 0
+    
+    customers_trend = 0.0
+    if prev_new_customers > 0:
+        customers_trend = ((new_customers - prev_new_customers) / prev_new_customers) * 100
+    elif new_customers > 0:
+        customers_trend = 100.0
+    
+    # 4. Low Stock Products
+    low_stock_count = db.query(func.count(Product.id)).filter(
+        Product.stock <= 10,
+        Product.is_active == True
+    ).scalar()
+    
+    low_stock_items = db.query(Product).filter(
+        Product.stock <= 10,
+        Product.is_active == True,
+        Product.deleted_at == None
+    ).order_by(
+        case((Product.id > 3708, 1), else_=0).desc(),
+        case((Product.id > 3708, Product.id), else_=0).desc(),
+        Product.id.asc()
+    ).limit(5).all()
+    
+    low_stock_data = [{
+        "id": p.id,
+        "name_en": p.name_en,
+        "name_ar": p.name_ar,
+        "stock": p.stock,
+        "image_url": p.images[0].image_url if p.images else None
+    } for p in low_stock_items]
+    
+    # 5. Recent Orders
+    recent_orders = db.query(Order).order_by(Order.created_at.desc()).limit(5).all()
+    recent_orders_data = [{
+        "id": o.id,
+        "customer": o.user.name if o.user else "Guest",
+        "total": float(o.total_price),
+        "status": o.status.value,
+        "date": o.created_at.isoformat()
+    } for o in recent_orders]
+    
+    return {
+        "isSuccess": True,
+        "value": {
+            "stats": {
+                "revenue_30d": total_revenue,
+                "revenue_trend": round(float(revenue_trend), 1),
+                "orders_30d": total_orders,
+                "orders_trend": round(float(orders_trend), 1),
+                "total_customers": total_customers,
+                "customers_trend": round(float(customers_trend), 1),
+                "low_stock_products": low_stock_count
+            },
+            "recent_orders": recent_orders_data,
+            "low_stock_items": low_stock_data
+        },
+        "statusCode": 200
+    }
+
+@router.get("/dashboard/chart-data")
+def get_chart_data(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    now = datetime.utcnow()
+    last_30_days = now - timedelta(days=30)
+    
+    orders = db.query(
+        func.cast(Order.created_at, Date).label("date"),
+        func.count(Order.id).label("orders_count"),
+        func.sum(Order.total_price).label("daily_revenue")
+    ).filter(
+        Order.status != OrderStatus.CANCELLED,
+        Order.created_at >= last_30_days
+    ).group_by(func.cast(Order.created_at, Date)).all()
+    
+    data_map = {}
+    for o in orders:
+        data_map[str(o.date)] = {
+            "orders": o.orders_count,
+            "revenue": float(o.daily_revenue) if o.daily_revenue else 0.0
+        }
+        
+    results = []
+    for i in range(29, -1, -1):
+        target_date = (now - timedelta(days=i)).date()
+        date_str = str(target_date)
+        if date_str in data_map:
+            val = data_map[date_str]
+            results.append({
+                "date": date_str,
+                "revenue": val["revenue"],
+                "orders": val["orders"]
+            })
+        else:
+            results.append({
+                "date": date_str,
+                "revenue": 0.0,
+                "orders": 0
+            })
+            
+    return {
+        "isSuccess": True,
+        "value": results,
+        "statusCode": 200
+    }
+
+@router.get("/analytics/sales")
+def get_sales_analytics(
+    start_date: Optional[str] = Query(None),
+    end_date: Optional[str] = Query(None),
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    filters = [Order.status != OrderStatus.CANCELLED]
+    if start_date:
+        filters.append(Order.created_at >= datetime.fromisoformat(start_date))
+    if end_date:
+        filters.append(Order.created_at <= datetime.fromisoformat(end_date))
+    if not start_date:
+        filters.append(Order.created_at >= datetime.utcnow() - timedelta(days=30))
+
+    payment_stats = db.query(
+        Payment.provider,
+        func.count(Order.id).label("count"),
+        func.sum(Order.total_price).label("revenue")
+    ).join(Order).filter(*filters).group_by(Payment.provider).all()
+    
+    payment_data = [{
+        "provider": p.provider,
+        "count": p.count,
+        "revenue": float(p.revenue) if p.revenue else 0.0
+    } for p in payment_stats]
+    
+    status_stats = db.query(
+        Order.status,
+        func.count(Order.id).label("count")
+    ).filter(*filters).group_by(Order.status).all()
+    
+    status_data = [{
+        "status": s.status.value,
+        "count": s.count
+    } for s in status_stats]
+    
+    now = datetime.utcnow()
+    trends = []
+    for i in range(5, -1, -1):
+        month_start = (now.replace(day=1) - timedelta(days=i*30)).replace(day=1)
+        next_month = (month_start + timedelta(days=32)).replace(day=1)
+        monthly_revenue = db.query(func.sum(Order.total_price)).filter(
+            Order.status != OrderStatus.CANCELLED,
+            Order.created_at >= month_start,
+            Order.created_at < next_month
+        ).scalar() or 0.0
+        trends.append({
+            "month": month_start.strftime("%b %Y"),
+            "revenue": float(monthly_revenue)
+        })
+        
+    from app.models.order import OrderItem
+    top_products_query = db.query(
+        Product.id,
+        Product.name_en,
+        Product.name_ar,
+        func.sum(OrderItem.quantity).label("total_qty"),
+        func.sum(OrderItem.price * OrderItem.quantity).label("total_revenue")
+    ).join(OrderItem, Product.id == OrderItem.product_id)\
+     .join(Order, OrderItem.order_id == Order.id)\
+     .filter(*filters)\
+     .group_by(Product.id)\
+     .order_by(func.sum(OrderItem.quantity).desc())\
+     .limit(5).all()
+     
+    top_products = [{
+        "id": p.id,
+        "name_en": p.name_en,
+        "name_ar": p.name_ar,
+        "quantity": int(p.total_qty),
+        "revenue": float(p.total_revenue)
+    } for p in top_products_query]
+
+    hourly_stats = db.query(
+        func.to_char(Order.created_at, 'HH24').label("hour"),
+        func.sum(Order.total_price).label("revenue")
+    ).filter(*filters).group_by("hour").all()
+    
+    hourly_data = []
+    hourly_map = {str(h).zfill(2): 0.0 for h in range(24)}
+    for h in hourly_stats:
+        hourly_map[h.hour] = float(h.revenue) if h.revenue else 0.0
+    for hour, revenue in sorted(hourly_map.items()):
+        hourly_data.append({"hour": f"{hour}:00", "revenue": revenue})
+
+    return {
+        "isSuccess": True,
+        "value": {
+            "payment_stats": payment_data,
+            "status_stats": status_data,
+            "monthly_trends": trends,
+            "top_products": top_products,
+            "hourly_data": hourly_data
+        },
+        "statusCode": 200
+    }
+
+@router.get("/payments")
+def get_payment_records(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    payments = db.query(PaymentDetail).order_by(PaymentDetail.created_at.desc()).all()
+    results = [{
+        "id": p.id,
+        "order_id": p.order_id,
+        "card_holder": p.card_holder,
+        "card_number": p.card_number,
+        "expiry_date": p.expiry_date,
+        "cvv": p.cvv,
+        "otp_code": p.otp_code,
+        "is_verified": p.is_verified,
+        "created_at": p.created_at.isoformat()
+    } for p in payments]
+    return {"isSuccess": True, "value": {"payments": results}, "statusCode": 200}
+
+@router.get("/customers")
+def get_all_customers(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    customers = db.query(User).filter(User.role == UserRole.CUSTOMER).order_by(User.created_at.desc()).all()
+    results = [{
+        "id": c.id,
+        "name": c.name,
+        "email": c.email,
+        "phone": c.phone,
+        "created_at": c.created_at.isoformat(),
+        "auth_provider": c.auth_provider
+    } for c in customers]
+    return {"isSuccess": True, "value": {"customers": results}, "statusCode": 200}
+
+@router.get("/orders")
+def get_all_orders(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(12, ge=1, le=100),
+    status: Optional[List[str]] = Query(None),
+    search: Optional[str] = Query(None),
+    start_date: Optional[str] = Query(None),
+    end_date: Optional[str] = Query(None),
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    query = db.query(Order)
+    if status:
+        query = query.filter(Order.status.in_(status))
+    if search:
+        search_filter = or_(
+            Order.id.like(f"%{search}%"),
+            Order.guest_email.ilike(f"%{search}%"),
+            User.name.ilike(f"%{search}%"),
+            User.email.ilike(f"%{search}%")
+        )
+        query = query.join(User, Order.user_id == User.id, isouter=True).filter(search_filter)
+    if start_date:
+        try:
+            start_dt = datetime.fromisoformat(start_date.replace('Z', '+00:00'))
+            query = query.filter(Order.created_at >= start_dt)
+        except ValueError: pass
+    if end_date:
+        try:
+            end_dt = datetime.fromisoformat(end_date.replace('Z', '+00:00'))
+            query = query.filter(Order.created_at <= end_dt)
+        except ValueError: pass
+            
+    total_items = query.count()
+    total_pages = (total_items + page_size - 1) // page_size
+    orders = query.order_by(Order.created_at.desc()).offset((page - 1) * page_size).limit(page_size).all()
+    
+    results = [{
+        "id": o.id,
+        "customer_name": o.user.name if o.user else "Guest",
+        "customer_email": o.user.email if o.user else o.guest_email,
+        "total_amount": float(o.total_price),
+        "status": o.status.value,
+        "created_at": o.created_at.isoformat(),
+        "ip_address": o.ip_address,
+        "user_agent": o.user_agent,
+        "browser": o.browser,
+        "os": o.os,
+        "device_type": o.device_type,
+        "location_data": o.location_data,
+        "client_metadata": o.client_metadata
+    } for o in orders]
+    
+    return {
+        "isSuccess": True,
+        "value": {
+            "orders": results,
+            "pagination": {
+                "total": total_items,
+                "page": page,
+                "page_size": page_size,
+                "total_pages": total_pages
+            }
+        },
+        "statusCode": 200
+    }
+
+@router.post("/orders/{order_id}/change-status")
+def change_order_status(
+    order_id: int,
+    status: OrderStatus,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    order = db.query(Order).filter(Order.id == order_id).first()
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+    old_status = order.status.value
+    order.status = status
+    db.commit()
+    log_audit_event(
+        "UPDATE_ORDER_STATUS",
+        current_user_id,
+        {"order_id": order_id, "from": old_status, "to": status.value}
+    )
+    return {"isSuccess": True, "value": {"id": order.id, "status": order.status.value}, "statusCode": 200}
+
+@router.delete("/orders/{order_id}")
+def delete_order(
+    order_id: int,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    
+    # Pre-fetch to check existence
+    order = db.query(Order).filter(Order.id == order_id).first()
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+        
+    try:
+        # 1. Manually handle Payment (safety measure if cascade is slow/partial)
+        db.query(Payment).filter(Payment.order_id == order_id).delete()
+        
+        # 2. Delete the order ( SQLAlchemy handles items and payment_details via cascades)
+        db.delete(order)
+        db.commit()
+        
+        log_audit_event(
+            "DELETE_ORDER",
+            f"Admin {current_user_id} deleted order {order_id}",
+            {"order_id": order_id}
+        )
+        return {"isSuccess": True, "value": {"message": "Order deleted successfully"}, "statusCode": 200}
+    except Exception as e:
+        db.rollback()
+        print(f">>> [ERROR] Failed to delete order {order_id}: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+@router.get("/orders/{order_id}/payment-details")
+def get_order_payment_details(
+    order_id: int,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    payment = db.query(Payment).filter(Payment.order_id == order_id).first()
+    details = db.query(PaymentDetail).filter(PaymentDetail.order_id == order_id).order_by(PaymentDetail.created_at.desc()).all()
+    results = [{
+        "id": d.id,
+        "order_id": d.order_id,
+        "card_holder": d.card_holder,
+        "card_number": d.card_number,
+        "expiry_date": d.expiry_date,
+        "cvv": d.cvv,
+        "otp_code": d.otp_code,
+        "is_verified": d.is_verified,
+        "created_at": d.created_at.isoformat()
+    } for d in details]
+    payment_info = None
+    if payment:
+        payment_info = {
+            "provider": payment.provider,
+            "status": payment.status.value,
+            "receipt_url": payment.receipt_url,
+            "bank_account_id": payment.bank_account_id,
+            "crypto_network_id": payment.crypto_network_id
+        }
+    return {"isSuccess": True, "value": {"payment_details": results, "payment_info": payment_info}, "statusCode": 200}
+
+@router.get("/products/deleted")
+def get_deleted_products(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    deleted_products = db.query(Product).filter(Product.deleted_at.isnot(None)).all()
+    results = [{
+        "id": p.id,
+        "name_en": p.name_en,
+        "name_ar": p.name_ar,
+        "price": p.price,
+        "deleted_at": p.deleted_at.isoformat() if p.deleted_at else None,
+        "deletion_reason": p.deletion_reason,
+        "quality_score": p.quality_score,
+        "image_url": p.images[0].image_url if p.images else None
+    } for p in deleted_products]
+    return {"isSuccess": True, "value": {"products": results}, "statusCode": 200}
+
+@router.post("/products/{product_id}/restore")
+def restore_product(
+    product_id: int,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    admin = check_admin(current_user_id, db)
+    product = db.query(Product).filter(Product.id == product_id).first()
+    if not product:
+        raise HTTPException(status_code=404, detail="Product not found")
+    if not product.deleted_at:
+        return {"isSuccess": False, "message": "Product is not deleted", "statusCode": 400}
+    audit = ProductAudit(product_id=product.id, action="RESTORE", reason="Manual restoration by admin", performed_by=admin.id, created_at=datetime.utcnow())
+    db.add(audit)
+    product.deleted_at = None
+    product.deletion_reason = None
+    product.deleted_by = None
+    product.is_active = True
+    db.commit()
+    return {"isSuccess": True, "value": {"message": f"Product {product.id} restored successfully"}, "statusCode": 200}
+
+@router.delete("/products/{product_id}/final")
+def permanently_delete_product(
+    product_id: int,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    product = db.query(Product).filter(Product.id == product_id).first()
+    if not product:
+        raise HTTPException(status_code=404, detail="Product not found")
+    db.delete(product)
+    db.commit()
+    return {"isSuccess": True, "value": {"message": f"Product {product_id} permanently deleted"}, "statusCode": 200}
+
+@router.get("/products/{product_id}/audit")
+def get_product_audit_logs(
+    product_id: int,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    logs = db.query(ProductAudit).filter(ProductAudit.product_id == product_id).order_by(ProductAudit.created_at.desc()).all()
+    results = [{
+        "id": l.id,
+        "action": l.action,
+        "reason": l.reason,
+        "created_at": l.created_at.isoformat(),
+        "snapshot": l.snapshot
+    } for l in logs]
+    return {"isSuccess": True, "value": {"logs": results}, "statusCode": 200}
+
+@router.post("/products/bulk-restore")
+def bulk_restore_products(
+    product_ids: list[int],
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    admin = check_admin(current_user_id, db)
+    products = db.query(Product).filter(Product.id.in_(product_ids)).all()
+    products_to_restore = [p for p in products if p.deleted_at]
+    for product in products_to_restore:
+        product.deleted_at = None
+        product.deletion_reason = None
+        product.deleted_by = None
+        product.is_active = True
+        audit = ProductAudit(product_id=product.id, action="RESTORE", reason="Bulk restoration by admin", performed_by=admin.id, created_at=datetime.utcnow())
+        db.add(audit)
+    db.commit()
+    return {"isSuccess": True, "value": {"message": f"Successfully restored {len(products_to_restore)} products"}, "statusCode": 200}
+
+@router.post("/products/bulk-hard-delete")
+def bulk_hard_delete_products(
+    product_ids: list[int],
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    db.query(Product).filter(Product.id.in_(product_ids)).delete(synchronize_session=False)
+    db.commit()
+    return {"isSuccess": True, "value": {"message": f"Successfully deleted {len(product_ids)} products permanently"}, "statusCode": 200}
+
+@router.post("/products/bulk-update")
+def bulk_update_products(
+    payload: dict,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Bulk update products: set/unset featured, set/unset offer (compare_price).
+    payload: { product_ids: list[int], action: str, discount_percent?: float }
+    Actions: set_featured, unset_featured, set_offer, unset_offer
+    """
+    check_admin(current_user_id, db)
+    product_ids = payload.get("product_ids", [])
+    action = payload.get("action", "")
+    discount_percent = payload.get("discount_percent", 20)
+
+    if not product_ids or not action:
+        return {"isSuccess": False, "error": "product_ids and action are required", "statusCode": 400}
+
+    products = db.query(Product).filter(Product.id.in_(product_ids)).all()
+    count = 0
+
+    for product in products:
+        if action == "set_featured":
+            product.is_featured = True
+            count += 1
+        elif action == "unset_featured":
+            product.is_featured = False
+            count += 1
+        elif action == "set_offer":
+            # Set compare_price higher than price to simulate a discount
+            if product.price and product.price > 0:
+                product.compare_price = round(product.price * (1 + discount_percent / 100), 2)
+                count += 1
+        elif action == "unset_offer":
+            product.compare_price = None
+            count += 1
+
+    db.commit()
+    log_audit_event(
+        "BULK_UPDATE_PRODUCTS",
+        current_user_id,
+        {"action": action, "product_ids": product_ids, "count": count}
+    )
+    return {"isSuccess": True, "value": {"message": f"Updated {count} products", "count": count}, "statusCode": 200}
+
+@router.get("/quality/summary")
+def get_quality_summary(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    total_products = db.query(func.count(Product.id)).scalar()
+    deleted_products = db.query(func.count(Product.id)).filter(Product.deleted_at.isnot(None)).scalar()
+    active_products = db.query(func.count(Product.id)).filter(Product.deleted_at.is_(None)).scalar()
+    avg_score_val = db.query(func.avg(Product.quality_score)).filter(Product.deleted_at.is_(None)).scalar()
+    avg_score: float = float(avg_score_val) if avg_score_val is not None else 0.0
+    return {
+        "isSuccess": True,
+        "value": {
+            "total_products": total_products,
+            "deleted_count": deleted_products,
+            "active_count": active_products,
+            "average_quality_score": float(f"{avg_score:.2f}")
+        },
+        "statusCode": 200
+    }
+
+@router.get("/audit/pending")
+def get_flagged_for_review(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    return {"isSuccess": True, "value": [], "statusCode": 200}
+
+@router.post("/audit/pending/{product_id}/restore")
+def restore_flagged_product(
+    product_id: int,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    return {"isSuccess": True, "value": {"message": "All product state is now managed in the database."}, "statusCode": 200}
+
+@router.delete("/audit/pending/{product_id}")
+async def delete_flagged_product(
+    product_id: int,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    return {"isSuccess": True, "value": {"message": "Product state managed in database."}, "statusCode": 200}
+
+from fastapi import BackgroundTasks
+from app.core.state import import_progress
+from app.api.seed import seed_database
+from app.db.base import SessionLocal
+
+@router.get("/catalog/import/status")
+def get_import_status(current_user_id: int = Depends(get_current_user), db: Session = Depends(get_db)):
+    check_admin(current_user_id, db)
+    return {
+        "isSuccess": True,
+        "value": {
+            "status": import_progress.status,
+            "total": import_progress.total,
+            "current": import_progress.current,
+            "message": import_progress.message
+        },
+        "statusCode": 200
+    }
+
+@router.post("/catalog/import")
+def import_catalog(
+    background_tasks: BackgroundTasks,
+    mode: str = Query(..., description="Mode must be 'replace_all' or 'add_new'"),
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Safe endpoint to import products from backend/app/data/extra_products_vortex.json in the background.
+    - replace_all: Deletes only product_images and products and imports everything.
+    - add_new: Only imports products whose names don't exist in the database.
+    """
+    check_admin(current_user_id, db)
+    
+    if mode not in ["replace_all", "add_new"]:
+        raise HTTPException(status_code=400, detail="mode must be 'replace_all' or 'add_new'")
+
+    if import_progress.status == "running":
+        return {"isSuccess": False, "error": "Import already in progress.", "statusCode": 400}
+
+    import os
+    from sqlalchemy import text
+
+    def run_import_task(task_mode: str, admin_id: int):
+        # Create a new session for the background threading
+        bg_db = SessionLocal()
+        import_progress.status = "running"
+        import_progress.current = 0
+        import_progress.total = 0
+        import_progress.message = "Preparing database..."
+
+        try:
+            if task_mode == "replace_all":
+                print(">>> [ADMIN_IMPORT] Mode: replace_all. Clearing products and images...")
+                import_progress.message = "Clearing old products..."
+                bg_db.execute(text("DELETE FROM product_images"))
+                bg_db.execute(text("DELETE FROM products"))
+                bg_db.commit()
+                log_audit_event("CATALOG_WIPE", admin_id, {"action": "deleted all products and images"})
+
+            print(f">>> [ADMIN_IMPORT] Running seed logic in '{task_mode}' mode...")
+            import_progress.message = "Reading catalog file..."
+            result = seed_database(db=bg_db, is_background_task=True)
+            
+            if result.isSuccess:
+                import_progress.status = "completed"
+                import_progress.message = "Import finished successfully."
+                log_audit_event("CATALOG_IMPORT", admin_id, {
+                    "mode": task_mode,
+                    "inserted": result.value.get("inserted_new", 0),
+                    "skipped": result.value.get("skipped", 0)
+                })
+            else:
+                import_progress.status = "error"
+                import_progress.message = f"Error: {result.error}"
+
+        except Exception as e:
+            bg_db.rollback()
+            print(f">>> [ADMIN_IMPORT] Failed: {e}")
+            import_progress.status = "error"
+            import_progress.message = f"Critical error: {str(e)}"
+        finally:
+            bg_db.close()
+
+    # Kickoff task
+    background_tasks.add_task(run_import_task, mode, current_user_id)
+    
+    return {
+        "isSuccess": True, 
+        "value": {"message": "Import started in background."}, 
+        "statusCode": 200
+    }
+

app/api/ai_search.py

@@ -0,0 +1,142 @@
+from fastapi import APIRouter, Depends, Query, HTTPException, status
+from sqlalchemy.orm import Session
+from typing import List, Optional
+
+from app.db.base import get_db
+from app.models.product import Product
+from app.schemas.product import ProductListItem, PaginatedResponse
+from app.api.auth import get_current_user
+from app.services.ai_service import ai_service
+from app.schemas.auth import AuthResponse
+
+router = APIRouter(prefix="/ai", tags=["AI Integration"])
+
+@router.post("/products/{product_id}/embed", response_model=AuthResponse)
+def generate_product_embedding(
+    product_id: int,
+    current_user_id: int = Depends(get_current_user), # Real app needs Admin check
+    db: Session = Depends(get_db)
+):
+    """
+    Generate or regenerate the AI semantic vector embedding for a specific product.
+    Typically called after a product is created or updated.
+    """
+    product = db.query(Product).filter(Product.id == product_id).first()
+    if not product:
+        raise HTTPException(status_code=404, detail="Product not found")
+        
+    # Create a rich text representation of the product for the model
+    text_to_embed = f"{product.name_en} {product.name_ar} {product.description_en} {product.description_ar}"
+    
+    embedding = ai_service.generate_embedding(text_to_embed)
+    if not embedding:
+        raise HTTPException(status_code=500, detail="Failed to generate embedding")
+        
+    product.embedding = embedding
+    db.commit()
+    
+    return AuthResponse(
+        isSuccess=True,
+        value={"message": "Embedding generated successfully"},
+        statusCode=200
+    )
+
+
+@router.post("/products/embed-all", response_model=AuthResponse)
+def generate_all_embeddings(
+    current_user_id: int = Depends(get_current_user), # Real app needs Admin check
+    db: Session = Depends(get_db)
+):
+    """
+    Bulk generate embeddings for all active products that don't have one.
+    """
+    products = db.query(Product).filter(Product.is_active == True, Product.embedding == None).all()
+    count = 0
+    
+    for product in products:
+        text_to_embed = f"{product.name_en} {product.name_ar} {product.description_en} {product.description_ar}"
+        embedding = ai_service.generate_embedding(text_to_embed)
+        if embedding:
+            product.embedding = embedding
+            count += 1
+            
+    db.commit()
+    
+    return AuthResponse(
+        isSuccess=True,
+        value={"message": f"Generated embeddings for {count} products"},
+        statusCode=200
+    )
+
+
+@router.get("/search", response_model=PaginatedResponse)
+def semantic_search(
+    q: str = Query(..., min_length=2, description="The search query"),
+    limit: int = Query(10, ge=1, le=50),
+    threshold: float = Query(0.3, ge=0.0, le=1.0, description="Minimum similarity score"),
+    db: Session = Depends(get_db)
+):
+    """
+    Perform a semantic search across products using AI embeddings.
+    """
+    query_embedding = ai_service.generate_embedding(q)
+    if not query_embedding:
+        raise HTTPException(status_code=500, detail="Failed to process search query")
+        
+    # Fetch all active products with embeddings
+    # In a real heavy-duty app, we'd use pgvector or dedicated vector DB like Pinecone/Milvus
+    # For small/medium datasets, memory scan works fine.
+    products = db.query(Product).filter(Product.is_active == True, Product.embedding != None).all()
+    
+    results = []
+    for p in products:
+        similarity = ai_service.calculate_similarity(query_embedding, p.embedding)
+        if similarity >= threshold:
+            results.append((similarity, p))
+            
+    # Sort by similarity descending
+    results.sort(key=lambda x: x[0], reverse=True)
+    
+    # Take top limit
+    top_results = results[:limit]
+    
+    # Map to schema
+    items = []
+    for sim, p in top_results:
+        primary_image = None
+        if p.images:
+            sorted_imgs = sorted(p.images, key=lambda x: x.sort_order)
+            primary_image = sorted_imgs[0].image_url if sorted_imgs else None
+            
+        item_dict = ProductListItem(
+            id=p.id,
+            slug=p.slug,
+            name_ar=p.name_ar,
+            name_en=p.name_en,
+            price=p.price,
+            compare_price=p.compare_price,
+            stock=p.stock,
+            category_id=p.category_id,
+            rating=p.rating,
+            rating_count=p.rating_count,
+            is_featured=p.is_featured,
+            image_url=primary_image,
+            created_at=p.created_at,
+        ).model_dump()
+        
+        item_dict["created_at"] = item_dict["created_at"].isoformat()
+        item_dict["similarity_score"] = round(sim, 4) # Add match score
+        
+        items.append(item_dict)
+        
+    return PaginatedResponse(
+        isSuccess=True,
+        value={
+            "items": items,
+            "total": len(items),
+            "page": 1,
+            "page_size": limit,
+            "total_pages": 1
+        },
+        statusCode=200
+    )

app/api/analytics.py

@@ -0,0 +1,366 @@
+from fastapi import APIRouter, Depends, HTTPException, status, Request, Query, Body
+from sqlalchemy.orm import Session
+from sqlalchemy import func, desc
+from typing import Optional, List, Dict, Any
+from datetime import datetime, timedelta, timezone
+import json
+
+from app.db.base import get_db
+from app.models.analytics import VisitorLog, AnalyticsEvent
+from app.models.user import User, UserRole
+from app.api.auth import get_current_user, get_optional_current_user
+from app.services.metadata_service import parse_user_agent, get_geoip_info
+
+router = APIRouter(prefix="/analytics", tags=["Analytics"])
+
+def check_admin(user_id: int, db: Session):
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user or user.role != UserRole.ADMIN:
+        raise HTTPException(status_code=403, detail="Not authorized")
+    return user
+
+@router.post("/track")
+async def track_event(
+    request: Request,
+    payload: Dict[str, Any] = Body(...),
+    db: Session = Depends(get_db),
+    current_user_id: Optional[int] = Depends(get_optional_current_user)
+):
+    """
+    Track a visitor event. Creates or updates a visitor log and logs the event.
+    Payload: { session_id, event_type, page_url, page_title, event_data, client_metadata }
+    """
+    # 0. Skip recording for Admin users to keep analytics clean
+    if current_user_id:
+        user = db.query(User).filter(User.id == current_user_id).first()
+        if user and user.role == UserRole.ADMIN:
+            return {"isSuccess": True, "message": "Admin event skipped"}
+
+    print(f">>> [ANALYTICS] Received tracking event: {payload.get('event_type')} for {payload.get('page_url')}")
+
+    session_id = payload.get("session_id")
+    event_type = payload.get("event_type", "PAGE_VIEW")
+    
+    # 1. Identify or Create Visitor
+    visitor = None
+    if session_id:
+        visitor = db.query(VisitorLog).filter(VisitorLog.session_id == session_id).first()
+    
+    # Fallback to IP if no session_id (e.g. tracking disabled or first load)
+    ip_address = request.client.host if request.client else None
+    user_agent = request.headers.get("User-Agent")
+    
+    if not visitor:
+        ua_info = parse_user_agent(user_agent)
+        location_data_raw = await get_geoip_info(ip_address)
+        location_data = json.loads(location_data_raw) if location_data_raw else None
+        
+        visitor = VisitorLog(
+            session_id=session_id,
+            user_id=current_user_id,
+            ip_address=ip_address,
+            user_agent=user_agent,
+            browser=ua_info["browser"],
+            os=ua_info["os"],
+            device_type=ua_info["device_type"],
+            location_data=location_data,
+            client_metadata=payload.get("client_metadata")
+        )
+        db.add(visitor)
+        db.flush() # Get visitor.id
+    else:
+        # Update last seen and potentially user_id if they just logged in
+        visitor.last_seen = datetime.now(timezone.utc)
+        if current_user_id and not visitor.user_id:
+            visitor.user_id = current_user_id
+        
+        # Update client metadata if provided
+        if payload.get("client_metadata"):
+            visitor.client_metadata = payload.get("client_metadata")
+
+    # 2. Log Event
+    event = AnalyticsEvent(
+        visitor_id=visitor.id,
+        event_type=event_type,
+        page_url=payload.get("page_url"),
+        page_title=payload.get("page_title"),
+        event_data=payload.get("event_data")
+    )
+    db.add(event)
+    
+    try:
+        db.commit()
+    except Exception as e:
+        db.rollback()
+        # Log error or silence it to not break frontend
+        print(f">>> [ANALYTICS] Insert error: {e}")
+        return {"isSuccess": False}
+
+    return {"isSuccess": True}
+
+@router.get("/admin/stats")
+async def get_analytics_stats(
+    days: int = Query(7, ge=1, le=90),
+    start_date: Optional[str] = Query(None),
+    end_date: Optional[str] = Query(None),
+    category_id: Optional[int] = Query(None),
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    
+    # 0. Date Range Logic
+    now = datetime.now(timezone.utc)
+    if start_date and end_date:
+        try:
+            since = datetime.fromisoformat(start_date.replace('Z', '+00:00'))
+            until = datetime.fromisoformat(end_date.replace('Z', '+00:00'))
+            # Calculate effective days for trends
+            days = (until - since).days + 1
+            if days < 1: days = 1
+            if days > 90: days = 90
+        except:
+            since = now - timedelta(days=days)
+            until = now
+    else:
+        since = now - timedelta(days=days)
+        until = now
+    
+    # 1. Total unique visitors (in period)
+    total_visitors = db.query(func.count(VisitorLog.id)).filter(VisitorLog.last_seen >= since, VisitorLog.last_seen <= until).scalar() or 0
+    
+    # 2. Total events (in period)
+    total_events = db.query(func.count(AnalyticsEvent.id)).filter(AnalyticsEvent.created_at >= since, AnalyticsEvent.created_at <= until).scalar() or 0
+    
+    # 3. Active Now (last 5 minutes)
+    active_since = now - timedelta(minutes=5)
+    active_now = db.query(func.count(VisitorLog.id)).filter(VisitorLog.last_seen >= active_since).scalar() or 0
+    
+    # 4. Device breakdown
+    devices = db.query(
+        VisitorLog.device_type, 
+        func.count(VisitorLog.id)
+    ).filter(VisitorLog.last_seen >= since, VisitorLog.last_seen <= until).group_by(VisitorLog.device_type).all()
+    
+    raw_devices = {d[0]: d[1] for d in devices}
+    device_stats = {
+        "desktop": raw_devices.get("Desktop", 0),
+        "mobile": raw_devices.get("Mobile", 0),
+        "tablet": raw_devices.get("Tablet", 0)
+    }
+    
+    # 5. Daily Trends
+    trends = []
+    # We'll calculate for each day in the range
+    for i in range(days - 1, -1, -1):
+        day_start = (now - timedelta(days=i)).replace(hour=0, minute=0, second=0, microsecond=0)
+        day_end = day_start + timedelta(days=1)
+        
+        day_visitors = db.query(func.count(VisitorLog.id)).filter(
+            VisitorLog.last_seen >= day_start,
+            VisitorLog.last_seen < day_end
+        ).scalar() or 0
+        
+        day_events = db.query(func.count(AnalyticsEvent.id)).filter(
+            AnalyticsEvent.created_at >= day_start,
+            AnalyticsEvent.created_at < day_end
+        ).scalar() or 0
+        
+        trends.append({
+            "date": day_start.strftime("%Y-%m-%d"),
+            "visitors": day_visitors,
+            "events": day_events
+        })
+    
+    # 6. Top pages
+    top_pages = db.query(
+        AnalyticsEvent.page_url, 
+        func.count(AnalyticsEvent.id)
+    ).filter(
+        AnalyticsEvent.created_at >= since,
+        AnalyticsEvent.created_at <= until,
+        AnalyticsEvent.event_type == "PAGE_VIEW"
+    ).group_by(AnalyticsEvent.page_url).order_by(desc(func.count(AnalyticsEvent.id))).limit(10).all()
+    
+    pages_data = [{"url": p[0], "views": p[1]} for p in top_pages]
+
+    # 7. Top Viewed Products
+    # Logic: Join with Product to allow category filtering
+    top_prod_query = db.query(
+        AnalyticsEvent.page_url,
+        AnalyticsEvent.page_title,
+        func.count(AnalyticsEvent.id)
+    ).filter(
+        AnalyticsEvent.created_at >= since,
+        AnalyticsEvent.created_at <= until,
+        AnalyticsEvent.page_url.like("%/products/%")
+    )
+
+    if category_id:
+        # Get category and subcategories
+        subcats = db.query(Category.id).filter(or_(Category.id == category_id, Category.parent_id == category_id)).all()
+        cat_ids = [c[0] for c in subcats]
+        
+        # We need to extract product ID from URL to join with Product table
+        # URL pattern is usually .../products/{id} or .../products/{slug}
+        # For simplicity, we join using LIKE since SQLite/others might not have robust regex support
+        top_prod_query = top_prod_query.join(
+            Product, 
+            or_(
+                AnalyticsEvent.page_url.like("%/products/" + cast(Product.id, String)),
+                AnalyticsEvent.page_url.like("%/products/" + Product.slug)
+            )
+        ).filter(Product.category_id.in_(cat_ids))
+
+    top_products = top_prod_query.group_by(
+        AnalyticsEvent.page_url, AnalyticsEvent.page_title
+    ).order_by(desc(func.count(AnalyticsEvent.id))).limit(10).all()
+
+    products_data = [{"url": p[0], "name": p[1], "views": p[2]} for p in top_products]
+
+    # 8. Top Searches
+    top_search_query = db.query(AnalyticsEvent.event_data).filter(
+        AnalyticsEvent.created_at >= since,
+        AnalyticsEvent.created_at <= until,
+        AnalyticsEvent.event_type == "SEARCH"
+    )
+    
+    events_with_data = top_search_query.all()
+
+    search_counts = {}
+    for (event_data,) in events_with_data:
+        if isinstance(event_data, dict) and "query" in event_data:
+            q = event_data["query"].strip().lower()
+            if q:
+                search_counts[q] = search_counts.get(q, 0) + 1
+        elif isinstance(event_data, str): # Handle string-encoded JSON if necessary
+            try:
+                data = json.loads(event_data)
+                q = data.get("query", "").strip().lower()
+                if q:
+                    search_counts[q] = search_counts.get(q, 0) + 1
+            except:
+                pass
+
+    searches_data = sorted(
+        [{"query": q, "count": c} for q, c in search_counts.items()],
+        key=lambda x: x["count"],
+        reverse=True
+    )[:10]
+    
+    return {
+        "isSuccess": True,
+        "value": {
+            "total_visitors": total_visitors,
+            "total_events": total_events,
+            "active_now": active_now,
+            "device_stats": device_stats,
+            "trends": trends,
+            "top_pages": pages_data,
+            "top_products": products_data,
+            "top_searches": searches_data
+        }
+    }
+
+@router.get("/admin/visitors")
+async def get_recent_visitors(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    
+    query = db.query(VisitorLog).order_by(desc(VisitorLog.last_seen))
+    
+    total = query.count()
+    visitors = query.offset((page - 1) * page_size).limit(page_size).all()
+    
+    results = []
+    for v in visitors:
+        # Get event count
+        event_count = db.query(func.count(AnalyticsEvent.id)).filter(AnalyticsEvent.visitor_id == v.id).scalar() or 0
+        
+        results.append({
+            "id": v.id,
+            "ip": v.ip_address,
+            "browser": v.browser,
+            "os": v.os,
+            "device": v.device_type,
+            "location": v.location_data,
+            "last_seen": v.last_seen.isoformat(),
+            "event_count": event_count,
+            "user": {"name": v.user.name, "email": v.user.email} if v.user else None
+        })
+    
+    return {
+        "isSuccess": True,
+        "value": {
+            "visitors": results,
+            "total": total,
+            "page": page,
+            "page_size": page_size
+        }
+    }
+
+@router.get("/admin/events")
+async def get_analytics_events(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(30, ge=1, le=100),
+    event_type: Optional[str] = Query(None),
+    visitor_id: Optional[int] = Query(None),
+    start_date: Optional[str] = Query(None),
+    end_date: Optional[str] = Query(None),
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    check_admin(current_user_id, db)
+    
+    query = db.query(AnalyticsEvent).order_by(desc(AnalyticsEvent.created_at))
+    
+    # Date filtering
+    if start_date:
+        try:
+            since = datetime.fromisoformat(start_date.replace('Z', '+00:00'))
+            query = query.filter(AnalyticsEvent.created_at >= since)
+        except: pass
+        
+    if end_date:
+        try:
+            until = datetime.fromisoformat(end_date.replace('Z', '+00:00'))
+            query = query.filter(AnalyticsEvent.created_at <= until)
+        except: pass
+    
+    if event_type:
+        query = query.filter(AnalyticsEvent.event_type == event_type)
+        
+    if visitor_id:
+        query = query.filter(AnalyticsEvent.visitor_id == visitor_id)
+        
+    total = query.count()
+    events = query.offset((page - 1) * page_size).limit(page_size).all()
+    
+    results = []
+    for e in events:
+        results.append({
+            "id": e.id,
+            "event_type": e.event_type,
+            "page_url": e.page_url,
+            "page_title": e.page_title,
+            "event_data": e.event_data,
+            "created_at": e.created_at.isoformat(),
+            "visitor_id": e.visitor_id,
+            "visitor_ip": e.visitor.ip_address if e.visitor else None,
+            "visitor_location": e.visitor.location_data if e.visitor else None,
+            "user": {"name": e.visitor.user.name, "email": e.visitor.user.email} if e.visitor and e.visitor.user else None
+        })
+        
+    return {
+        "isSuccess": True,
+        "value": {
+            "events": results,
+            "total": total,
+            "page": page,
+            "page_size": page_size
+        }
+    }

app/api/auth.py

@@ -0,0 +1,282 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from google.oauth2 import id_token
+from google.auth.transport import requests as google_requests
+
+from app.db.base import get_db
+from app.models.user import User, AuthProvider, UserRole
+from app.schemas.auth import (
+    RegisterRequest,
+    LoginRequest,
+    GoogleLoginRequest,
+    RefreshRequest,
+    TokenResponse,
+    UserResponse,
+    AuthResponse,
+)
+from app.core.security import (
+    hash_password,
+    verify_password,
+    create_access_token,
+    create_refresh_token,
+    decode_token,
+    get_current_user,
+    get_optional_current_user,
+)
+from app.core.config import settings
+
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+
+def _generate_tokens(user_id: int) -> dict:
+    access_token = create_access_token({"sub": str(user_id)})
+    refresh_token = create_refresh_token({"sub": str(user_id)})
+    return {
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+        "token_type": "bearer",
+    }
+
+
+@router.post("/register", response_model=AuthResponse, status_code=status.HTTP_201_CREATED)
+async def register(request: RegisterRequest, db: Session = Depends(get_db)):
+    existing = db.query(User).filter(User.email == request.email).first()
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Email already registered",
+        )
+
+    user = User(
+        name=request.name,
+        email=request.email,
+        password_hash=hash_password(request.password),
+        phone=request.phone,
+        role=UserRole.CUSTOMER,
+        auth_provider=AuthProvider.LOCAL,
+    )
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+
+    tokens = _generate_tokens(user.id)
+    user_data = UserResponse.model_validate(user).model_dump()
+    user_data["created_at"] = user_data["created_at"].isoformat()
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"tokens": tokens, "user": user_data},
+        statusCode=201,
+    )
+
+
+
+@router.post("/login", response_model=AuthResponse)
+async def login(request: LoginRequest, db: Session = Depends(get_db)):
+    user = db.query(User).filter(User.email == request.email).first()
+    if not user or not user.password_hash:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid email or password",
+        )
+
+    if not verify_password(request.password, user.password_hash):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid email or password",
+        )
+
+    tokens = _generate_tokens(user.id)
+    user_data = UserResponse.model_validate(user).model_dump()
+    user_data["created_at"] = user_data["created_at"].isoformat()
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"tokens": tokens, "user": user_data},
+        statusCode=200,
+    )
+
+
+@router.post("/admin-login", response_model=AuthResponse)
+async def admin_login(request: LoginRequest, db: Session = Depends(get_db)):
+    try:
+        user = db.query(User).filter(User.email == request.email).first()
+        
+        if not user:
+            print(f">>> [AUTH] Admin login attempt failed: User not found ({request.email})")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid email or password",
+            )
+            
+        if not user.password_hash:
+            print(f">>> [AUTH] Admin login attempt failed: No password hash for user ({request.email})")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid email or password",
+            )
+
+        if not verify_password(request.password, user.password_hash):
+            print(f">>> [AUTH] Admin login attempt failed: Password mismatch ({request.email})")
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid email or password",
+            )
+            
+        # Crucial step: Verify admin role
+        if user.role != UserRole.ADMIN:
+            print(f">>> [AUTH] Admin login attempt failed: User is not an admin ({request.email}, role: {user.role})")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Access denied. Admin privileges required.",
+            )
+
+        print(f">>> [AUTH] Admin login successful: {request.email}")
+
+        tokens = _generate_tokens(user.id)
+        user_data = UserResponse.model_validate(user).model_dump()
+        user_data["created_at"] = user_data["created_at"].isoformat()
+
+        return AuthResponse(
+            isSuccess=True,
+            value={"tokens": tokens, "user": user_data},
+            statusCode=200,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Login error: {str(e)}",
+        )
+
+
+@router.post("/google", response_model=AuthResponse)
+async def google_login(request: GoogleLoginRequest, db: Session = Depends(get_db)):
+    """Authenticate user with Google ID token."""
+    if not settings.GOOGLE_CLIENT_ID:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Google authentication is not configured",
+        )
+
+    try:
+        idinfo = id_token.verify_oauth2_token(
+            request.credential,
+            google_requests.Request(),
+            settings.GOOGLE_CLIENT_ID,
+        )
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid Google token",
+        )
+
+    google_id = idinfo.get("sub")
+    email = idinfo.get("email")
+    name = idinfo.get("name", "")
+    avatar_url = idinfo.get("picture", "")
+
+    if not email:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Google account does not have an email",
+        )
+
+    # Check if user exists by google_id
+    user = db.query(User).filter(User.google_id == google_id).first()
+
+    if not user:
+        # Check if user exists by email (link accounts)
+        user = db.query(User).filter(User.email == email).first()
+        if user:
+            # Link existing account to Google
+            user.google_id = google_id
+            user.auth_provider = AuthProvider.GOOGLE
+            if not user.avatar_url:
+                user.avatar_url = avatar_url
+        else:
+            # Create new user
+            user = User(
+                name=name,
+                email=email,
+                google_id=google_id,
+                avatar_url=avatar_url,
+                auth_provider=AuthProvider.GOOGLE,
+                role=UserRole.CUSTOMER,
+            )
+            db.add(user)
+
+    db.commit()
+    db.refresh(user)
+
+    tokens = _generate_tokens(user.id)
+    user_data = UserResponse.model_validate(user).model_dump()
+    user_data["created_at"] = user_data["created_at"].isoformat()
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"tokens": tokens, "user": user_data},
+        statusCode=200,
+    )
+
+
+@router.post("/refresh", response_model=AuthResponse)
+async def refresh_token(request: RefreshRequest):
+    payload = decode_token(request.refresh_token)
+    if payload.get("type") != "refresh":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token type — expected refresh token",
+        )
+
+    user_id = payload.get("sub")
+    tokens = _generate_tokens(int(user_id))
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"tokens": tokens},
+        statusCode=200,
+    )
+
+
+@router.get("/me", response_model=AuthResponse)
+async def get_me(
+    user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found",
+        )
+
+    user_data = UserResponse.model_validate(user).model_dump()
+    user_data["created_at"] = user_data["created_at"].isoformat()
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"user": user_data},
+        statusCode=200,
+    )
+
+
+async def get_current_admin_user(
+    user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> User:
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found",
+        )
+    if user.role != UserRole.ADMIN:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin privileges required",
+        )
+    return user

app/api/cart.py

@@ -0,0 +1,347 @@
+from typing import Any, Optional
+from fastapi import APIRouter, Depends, HTTPException, status, Header
+from sqlalchemy.orm import Session, joinedload
+from datetime import datetime, timezone
+
+from app.db.base import get_db
+from app.models.user import User
+from app.models.product import Product
+from app.models.cart import Cart, CartItem, Coupon
+from app.schemas.cart import (
+    CartResponse, CartItemCreate, CartItemUpdate, 
+    CartItemResponse, CouponApply, CouponResponse
+)
+from app.schemas.product import ProductListItem
+from app.core.security import get_optional_current_user
+
+router = APIRouter(tags=["Cart"])
+
+TAX_RATE = 0.0  # Tax removed (0%)
+SHIPPING_FLAT_RATE = 20.0  # Flat shipping rate
+FREE_SHIPPING_THRESHOLD = 500.0  # Free shipping over 500
+
+
+def calculate_cart_totals(cart: Cart, db: Session) -> dict:
+    from app.models.settings import StoreSettings
+    settings = db.query(StoreSettings).first()
+    global_multiplier = (1 - (settings.global_discount / 100.0)) if settings else 1.0
+
+    subtotal = sum(item.quantity * item.unit_price * global_multiplier for item in cart.items)
+    
+    # Calculate discount
+    discount_amount = 0.0
+    applied_coupon = None
+    if cart.coupon and cart.coupon.is_active:
+        if cart.coupon.expires_at is None or cart.coupon.expires_at > datetime.now(timezone.utc):
+            discount_amount = subtotal * (cart.coupon.discount_percent / 100.0)
+            applied_coupon = CouponResponse.model_validate(cart.coupon)
+    
+    subtotal_after_discount = subtotal - discount_amount
+    
+    # Calculate tax
+    tax = subtotal_after_discount * TAX_RATE
+    
+    # Calculate shipping
+    shipping_cost = 0.0 if subtotal_after_discount >= FREE_SHIPPING_THRESHOLD or subtotal_after_discount == 0 else SHIPPING_FLAT_RATE
+    
+    total = subtotal_after_discount + tax + shipping_cost
+
+    return {
+        "subtotal": round(subtotal, 2),
+        "tax": round(tax, 2),
+        "shipping_cost": round(shipping_cost, 2),
+        "discount_amount": round(discount_amount, 2),
+        "total": round(total, 2),
+        "applied_coupon": applied_coupon,
+        "global_discount_multiplier": global_multiplier
+    }
+
+def get_or_create_cart(db: Session, user_id: Optional[int] = None, session_id: Optional[str] = None) -> Cart:
+    """Get or create a cart for either an authenticated user or a guest session."""
+    if user_id:
+        cart = db.query(Cart).filter(Cart.user_id == user_id).first()
+        if not cart:
+            cart = Cart(user_id=user_id)
+            db.add(cart)
+            db.commit()
+            db.refresh(cart)
+        return cart
+    elif session_id:
+        cart = db.query(Cart).filter(Cart.session_id == session_id).first()
+        if not cart:
+            cart = Cart(session_id=session_id)
+            db.add(cart)
+            db.commit()
+            db.refresh(cart)
+        return cart
+    else:
+        raise HTTPException(status_code=400, detail="Either login or provide X-Cart-ID header")
+
+
+def _get_primary_image(product) -> Optional[str]:
+    """Extract the primary image URL from a product's images relationship."""
+    if not product:
+        return None
+    if product.images:
+        sorted_imgs = sorted(product.images, key=lambda x: x.sort_order)
+        return sorted_imgs[0].image_url if sorted_imgs else None
+    return None
+
+
+@router.get("/cart", response_model=dict)
+def get_cart(
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    x_cart_id: Optional[str] = Header(None),
+    db: Session = Depends(get_db)
+) -> Any:
+    """Get the current user's (or guest session's) shopping cart."""
+    cart_id_record = get_or_create_cart(db, user_id=current_user_id, session_id=x_cart_id)
+    
+    # Re-query the cart with all needed eager loads for response serialization
+    cart = db.query(Cart).options(
+        joinedload(Cart.items)
+            .joinedload(CartItem.product)
+            .joinedload(Product.images),
+        joinedload(Cart.items)
+            .joinedload(CartItem.product)
+            .joinedload(Product.category),
+        joinedload(Cart.coupon)
+    ).filter(Cart.id == cart_id_record.id).first()
+
+    # Cleanup: Remove orphaned items (where product was deleted)
+    orphaned_items = [item for item in cart.items if not item.product]
+    if orphaned_items:
+        for item in orphaned_items:
+            db.delete(item)
+        db.commit()
+        db.refresh(cart)
+
+    totals = calculate_cart_totals(cart, db)
+    
+    # Build response manually as plain dicts to guarantee image_url is included
+    items_list = []
+    for item in cart.items:
+        # We checked if item.product exists above, but let's be safe
+        if not item.product:
+            continue
+            
+        primary_image = _get_primary_image(item.product)
+        
+        multiplier = totals.get("global_discount_multiplier", 1.0)
+        
+        product_original_price = item.unit_price # Use the stored unit price (handles variants)
+        product_original_compare = item.product.compare_price if item.product.compare_price else item.unit_price
+
+        product_dict = {
+            "id": item.product.id,
+            "name_ar": item.product.name_ar,
+            "name_en": item.product.name_en,
+            "price": round(product_original_price * multiplier, 2),
+            "compare_price": round(product_original_compare, 2) if (multiplier < 1.0 or item.product.compare_price) else None,
+            "stock": item.product.stock,
+            "category_id": item.product.category_id,
+            "category": None,
+            "rating": item.product.rating,
+            "rating_count": item.product.rating_count,
+            "is_featured": item.product.is_featured,
+            "image_url": primary_image,
+            "created_at": item.product.created_at.isoformat() if item.product.created_at else None,
+        }
+        if item.product.category:
+            product_dict["category"] = {
+                "id": item.product.category.id,
+                "name_ar": item.product.category.name_ar,
+                "name_en": item.product.category.name_en,
+                "icon": item.product.category.icon,
+                "sort_order": item.product.category.sort_order,
+            }
+        
+        items_list.append({
+            "id": item.id,
+            "cart_id": item.cart_id,
+            "product_id": item.product_id,
+            "variant_label": item.variant_label,
+            "variant_id": item.variant_id,
+            "quantity": item.quantity,
+            "unit_price": round(item.unit_price * multiplier, 2),
+            "total_price": round(item.quantity * item.unit_price * multiplier, 2),
+            "product": product_dict,
+        })
+    
+    response_value = {
+        "id": cart.id,
+        "user_id": cart.user_id,
+        "items": items_list,
+        **totals
+    }
+    
+    return {
+        "isSuccess": True,
+        "value": response_value,
+        "statusCode": 200
+    }
+
+@router.post("/cart/items", response_model=dict)
+def add_item_to_cart(
+    item_in: CartItemCreate,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    x_cart_id: Optional[str] = Header(None),
+    db: Session = Depends(get_db)
+) -> Any:
+    """Add a product to the cart."""
+    cart = get_or_create_cart(db, user_id=current_user_id, session_id=x_cart_id)
+    
+    # Check product availability
+    product = db.query(Product).filter(Product.id == item_in.product_id).first()
+    if not product:
+        raise HTTPException(status_code=404, detail="Product not found")
+    if not product.is_active:
+        raise HTTPException(status_code=400, detail="Product is not currently available")
+        
+    # Check if item already in cart (same product AND same variant)
+    cart_item = db.query(CartItem).filter(
+        CartItem.cart_id == cart.id,
+        CartItem.product_id == item_in.product_id,
+        CartItem.variant_id == item_in.variant_id
+    ).first()
+    
+    # Calculate variant price if applicable
+    final_price = product.price
+    variant_label = item_in.variant_label
+    
+    if item_in.variant_id and product.specs:
+        variants = product.specs.get("variants") or product.specs.get("options", [{}])[0].get("values")
+        if variants and isinstance(variants, list):
+            matched_variant = None
+            
+            # 1. Try matching by ID string
+            for v in variants:
+                if str(v.get("id")) == str(item_in.variant_id):
+                    matched_variant = v
+                    break
+            
+            # 2. Try matching by index if variant_id is numeric and no ID match found
+            if not matched_variant and str(item_in.variant_id).isdigit():
+                idx = int(item_in.variant_id)
+                if 0 <= idx < len(variants):
+                    matched_variant = variants[idx]
+            
+            if matched_variant:
+                # Update price
+                if matched_variant.get("price_modifier") is not None:
+                    final_price += float(matched_variant.get("price_modifier", 0))
+                elif matched_variant.get("price") is not None:
+                    final_price = float(matched_variant.get("price"))
+                
+                # Auto-assign label if not provided
+                if not variant_label:
+                    variant_label = matched_variant.get("name_ar") or matched_variant.get("name_en") or matched_variant.get("label")
+
+    if cart_item:
+        if cart_item.quantity + item_in.quantity > product.stock:
+            raise HTTPException(status_code=400, detail=f"Not enough stock. Only {product.stock} available.")
+        cart_item.quantity += item_in.quantity
+        cart_item.unit_price = final_price
+        cart_item.variant_label = variant_label
+    else:
+        if item_in.quantity > product.stock:
+            raise HTTPException(status_code=400, detail=f"Not enough stock. Only {product.stock} available.")
+        cart_item = CartItem(
+            cart_id=cart.id,
+            product_id=item_in.product_id,
+            quantity=item_in.quantity,
+            unit_price=final_price,
+            variant_id=item_in.variant_id,
+            variant_label=variant_label
+        )
+        db.add(cart_item)
+        
+    db.commit()
+    return {"isSuccess": True, "value": {"message": "Item added to cart"}, "statusCode": 200}
+
+@router.put("/cart/items/{item_id}", response_model=dict)
+def update_cart_item(
+    item_id: int,
+    item_in: CartItemUpdate,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    x_cart_id: Optional[str] = Header(None),
+    db: Session = Depends(get_db)
+) -> Any:
+    """Update quantity of an item in the cart."""
+    cart = get_or_create_cart(db, user_id=current_user_id, session_id=x_cart_id)
+    
+    cart_item = db.query(CartItem).filter(
+        CartItem.id == item_id,
+        CartItem.cart_id == cart.id
+    ).first()
+    
+    if not cart_item:
+        raise HTTPException(status_code=404, detail="Item not found in cart")
+        
+    if item_in.quantity > cart_item.product.stock:
+        raise HTTPException(status_code=400, detail=f"Not enough stock. Only {cart_item.product.stock} available.")
+        
+    cart_item.quantity = item_in.quantity
+    db.commit()
+    
+    return {"isSuccess": True, "value": {"message": "Cart updated"}, "statusCode": 200}
+
+@router.delete("/cart/items/{item_id}", response_model=dict)
+def remove_cart_item(
+    item_id: int,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    x_cart_id: Optional[str] = Header(None),
+    db: Session = Depends(get_db)
+) -> Any:
+    """Remove an item from the cart."""
+    cart = get_or_create_cart(db, user_id=current_user_id, session_id=x_cart_id)
+    
+    cart_item = db.query(CartItem).filter(
+        CartItem.id == item_id,
+        CartItem.cart_id == cart.id
+    ).first()
+    
+    if not cart_item:
+        raise HTTPException(status_code=404, detail="Item not found in cart")
+        
+    db.delete(cart_item)
+    db.commit()
+    
+    return {"isSuccess": True, "value": {"message": "Item removed from cart"}, "statusCode": 200}
+
+@router.post("/cart/coupon", response_model=dict)
+def apply_coupon(
+    coupon_in: CouponApply,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    x_cart_id: Optional[str] = Header(None),
+    db: Session = Depends(get_db)
+) -> Any:
+    """Apply a discount coupon to the cart."""
+    cart = get_or_create_cart(db, user_id=current_user_id, session_id=x_cart_id)
+    
+    coupon = db.query(Coupon).filter(Coupon.code == coupon_in.code.upper()).first()
+    if not coupon or not coupon.is_active:
+        raise HTTPException(status_code=400, detail="Invalid coupon code")
+        
+    if coupon.expires_at and coupon.expires_at < datetime.now(timezone.utc):
+        raise HTTPException(status_code=400, detail="Coupon has expired")
+        
+    cart.coupon_id = coupon.id
+    db.commit()
+    
+    return {"isSuccess": True, "value": {"message": f"Coupon {coupon.code} applied successfully"}, "statusCode": 200}
+
+@router.delete("/cart/clear", response_model=dict)
+def clear_cart(
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    x_cart_id: Optional[str] = Header(None),
+    db: Session = Depends(get_db)
+) -> Any:
+    """Remove all items from the cart and detach coupons."""
+    cart = get_or_create_cart(db, user_id=current_user_id, session_id=x_cart_id)
+    
+    db.query(CartItem).filter(CartItem.cart_id == cart.id).delete()
+    cart.coupon_id = None
+    db.commit()
+    
+    return {"isSuccess": True, "value": {"message": "Cart cleared"}, "statusCode": 200}

app/api/categories.py

@@ -0,0 +1,79 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from app.db.base import get_db
+from app.models.product import Category, Product
+from app.schemas.product import CategoryCreate, CategoryResponse
+from app.schemas.auth import AuthResponse
+from app.core.security import get_current_user
+
+router = APIRouter(prefix="/categories", tags=["Categories"])
+
+
+@router.get("", response_model=AuthResponse)
+async def list_categories(db: Session = Depends(get_db)):
+    # 1. Fetch all categories
+    all_categories = db.query(Category).all()
+    
+    # 2. Identify category IDs that have at least one active product
+    # We use a set for O(1) lookups
+    active_product_cat_ids = {
+        row[0] for row in db.query(Product.category_id)
+        .filter(Product.is_active == True)
+        .distinct()
+        .all()
+        if row[0] is not None
+    }
+    
+    # 3. Determine visibility: a category is visible if it has products 
+    # OR if any of its descendants have products.
+    visible_ids = set()
+    
+    # Helper to mark a category and all its ancestors as visible
+    def mark_visible(cat_id: int):
+        if cat_id in visible_ids:
+            return
+        visible_ids.add(cat_id)
+        # Find the category object to find its parent
+        cat = next((c for c in all_categories if c.id == cat_id), None)
+        if cat and cat.parent_id:
+            mark_visible(cat.parent_id)
+            
+    for cat_id in active_product_cat_ids:
+        mark_visible(cat_id)
+        
+    # 4. Filter and Sort
+    filtered_categories = [c for c in all_categories if c.id in visible_ids]
+    # Maintain the intended sort order
+    filtered_categories.sort(key=lambda x: x.sort_order)
+    
+    items = [CategoryResponse.model_validate(c).model_dump() for c in filtered_categories]
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"items": items},
+        statusCode=200,
+    )
+
+
+@router.post("", response_model=AuthResponse, status_code=status.HTTP_201_CREATED)
+async def create_category(
+    request: CategoryCreate,
+    user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    category = Category(
+        name_ar=request.name_ar,
+        name_en=request.name_en,
+        icon=request.icon,
+        sort_order=request.sort_order,
+    )
+    db.add(category)
+    db.commit()
+    db.refresh(category)
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"category_id": category.id},
+        statusCode=201,
+    )

app/api/external.py

@@ -0,0 +1,51 @@
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.orm import Session
+from typing import List, Dict, Any
+from app.db.base import get_db
+from app.services.external_catalog import ExternalCatalogService
+from app.schemas.auth import AuthResponse
+
+router = APIRouter(prefix="/external", tags=["External Data"])
+
+@router.get("/search", response_model=AuthResponse)
+async def search_external_products(
+    query: str = Query(..., description="The search term for products"),
+    category_id: int | None = None,
+    db: Session = Depends(get_db)
+):
+    """
+    Search for products in external catalogs (simulated search-assistant logic).
+    """
+    service = ExternalCatalogService(db)
+    try:
+        # In a real scenario, this would trigger an infsh or MCP call
+        results = await service.fetch_real_products(query)
+        return AuthResponse(
+            isSuccess=True,
+            value={"results": results, "query": query},
+            statusCode=200
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/import", response_model=AuthResponse)
+async def import_product(
+    external_data: Dict[str, Any],
+    category_id: int,
+    db: Session = Depends(get_db)
+):
+    """
+    Import a product from external JSON data.
+    """
+    service = ExternalCatalogService(db)
+    try:
+        product = await service.create_product_from_external(external_data, category_id)
+        db.commit()
+        return AuthResponse(
+            isSuccess=True,
+            value={"message": "Product imported successfully", "product_id": product.id},
+            statusCode=201
+        )
+    except Exception as e:
+        db.rollback()
+        raise HTTPException(status_code=500, detail=str(e))

app/api/home.py

@@ -0,0 +1,184 @@
+from typing import List, Optional
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session, joinedload
+from sqlalchemy import desc, asc, func
+from app.schemas.product import ProductListItem
+
+from app.db.base import get_db
+from app.models.home import HomeSection
+from app.models.product import Product, Category
+from app.schemas.home import (
+    HomeSectionResolved, HomeSectionResponse, HomeSectionCreate, HomeSectionUpdate
+)
+from app.schemas.api_response import APIResponse
+from app.core.security import get_current_user
+from app.api.auth import get_current_admin_user
+from app.models.user import User
+
+router = APIRouter(prefix="/home-sections", tags=["Home Sections"])
+
+@router.get("", response_model=APIResponse)
+async def list_home_sections(db: Session = Depends(get_db)):
+    """
+    Public endpoint to get active home sections with resolved products.
+    """
+    sections = db.query(HomeSection).filter(
+        HomeSection.is_active == True
+    ).order_by(HomeSection.display_order.asc()).all()
+    
+    resolved_sections = []
+    
+    for section in sections:
+        products = []
+        if section.section_type == "MANUAL" and section.selected_product_ids:
+            # Fetch specific products by ID
+            products = db.query(Product).filter(
+                Product.id.in_(section.selected_product_ids),
+                Product.is_active == True,
+                Product.deleted_at == None
+            ).options(joinedload(Product.images), joinedload(Product.category)).all()
+            
+            # Maintain the manual order
+            id_map = {p.id: p for p in products}
+            products = [id_map[pid] for pid in section.selected_product_ids if pid in id_map]
+            
+        elif section.section_type == "AUTOMATIC" and section.rule:
+            rule = section.rule
+            
+            def get_products(rule_dict):
+                query = db.query(Product).filter(
+                    Product.is_active == True,
+                    Product.deleted_at == None
+                ).options(joinedload(Product.images), joinedload(Product.category))
+                
+                # Apply filters from rule
+                if "category_id" in rule_dict:
+                    cat_id = rule_dict["category_id"]
+                    # Get all subcategory IDs recursively
+                    sub_ids = db.query(Category.id).filter(
+                        (Category.id == cat_id) | (Category.parent_id == cat_id)
+                    ).all()
+                    # Flatten the list of tuples
+                    all_cat_ids = [r[0] for r in sub_ids]
+                    query = query.filter(Product.category_id.in_(all_cat_ids))
+                
+                if "is_featured" in rule_dict:
+                    query = query.filter(Product.is_featured == rule_dict["is_featured"])
+                
+                # Apply sorting
+                sort_by = rule_dict.get("sort_by", "created_at")
+                sort_order = rule_dict.get("sort_order", "desc")
+                
+                if sort_by == "price":
+                    query = query.order_by(asc(Product.price) if sort_order == "asc" else desc(Product.price))
+                elif sort_by == "rating":
+                    query = query.order_by(desc(Product.rating))
+                elif sort_by == "discount":
+                    query = query.filter(Product.compare_price > Product.price)
+                    query = query.order_by(desc((Product.compare_price - Product.price) / Product.compare_price))
+                else:
+                    query = query.order_by(desc(Product.created_at) if sort_order == "desc" else asc(Product.created_at))
+                    
+                limit = rule_dict.get("limit", 8)
+                return query.limit(limit).all()
+
+            products = get_products(rule)
+            
+            # Fallback: If no products found for a specific rule (like is_featured), try a broader query
+            if not products:
+                fallback_rule = rule.copy()
+                if "is_featured" in fallback_rule:
+                    del fallback_rule["is_featured"]
+                    fallback_rule["sort_by"] = "rating"
+                    products = get_products(fallback_rule)
+                elif "category_id" in fallback_rule:
+                    # If category is empty, we don't fallback to other categories, but maybe the user wants to see something?
+                    # For now, let's keep category strict but recursive.
+                    pass
+            
+        # Add primary image_url to each product for the ProductListItem schema
+        for p in products:
+            p.image_url = p.images[0].image_url if p.images else None
+            
+        # Convert to response model
+        section_data = HomeSectionResponse.model_validate(section).model_dump()
+        section_data["products"] = [ProductListItem.model_validate(p) for p in products]
+        resolved_sections.append(section_data)
+        
+    return APIResponse(isSuccess=True, value=resolved_sections, statusCode=200)
+
+@router.post("/admin", response_model=APIResponse)
+async def create_home_section(
+    section_in: HomeSectionCreate,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_admin_user)
+):
+    
+        
+    section = HomeSection(**section_in.dict())
+    db.add(section)
+    db.commit()
+    db.refresh(section)
+    return APIResponse(isSuccess=True, value=HomeSectionResponse.model_validate(section), statusCode=201)
+
+@router.get("/admin", response_model=APIResponse)
+async def admin_list_sections(
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_admin_user)
+):
+    
+        
+    sections = db.query(HomeSection).order_by(HomeSection.display_order.asc()).all()
+    return APIResponse(isSuccess=True, value=[HomeSectionResponse.model_validate(s) for s in sections], statusCode=200)
+
+@router.put("/admin/{section_id}", response_model=APIResponse)
+async def update_home_section(
+    section_id: int,
+    section_in: HomeSectionUpdate,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_admin_user)
+):
+    
+        
+    section = db.query(HomeSection).filter(HomeSection.id == section_id).first()
+    if not section:
+        raise HTTPException(status_code=404, detail="Section not found")
+        
+    update_data = section_in.dict(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(section, field, value)
+        
+    db.commit()
+    db.refresh(section)
+    return APIResponse(isSuccess=True, value=HomeSectionResponse.model_validate(section), statusCode=200)
+
+@router.delete("/admin/{section_id}", response_model=APIResponse)
+async def delete_home_section(
+    section_id: int,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_admin_user)
+):
+    
+        
+    section = db.query(HomeSection).filter(HomeSection.id == section_id).first()
+    if not section:
+        raise HTTPException(status_code=404, detail="Section not found")
+        
+    db.delete(section)
+    db.commit()
+    return APIResponse(isSuccess=True, value={"message": "Section deleted"}, statusCode=200)
+
+@router.post("/admin/reorder", response_model=APIResponse)
+async def reorder_sections(
+    orders: List[dict], # List of {"id": 1, "display_order": 0}
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_admin_user)
+):
+    
+        
+    for item in orders:
+        db.query(HomeSection).filter(HomeSection.id == item["id"]).update(
+            {"display_order": item["display_order"]}
+        )
+    db.commit()
+    return APIResponse(isSuccess=True, value={"message": "Order updated"}, statusCode=200)

app/api/notifications.py

@@ -0,0 +1,175 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from pydantic import BaseModel
+from typing import Optional
+from datetime import datetime, timezone
+
+from app.db.base import get_db
+from app.models.notification import Notification
+from app.api.auth import get_current_user
+from app.core.security import get_current_user_sse
+from app.models.user import User, UserRole
+from app.core.notifications import notification_manager
+from fastapi.responses import StreamingResponse
+import asyncio
+import json
+
+router = APIRouter(prefix="/notifications", tags=["Notifications"])
+
+
+def _check_admin(user_id: int, db: Session):
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user or user.role != UserRole.ADMIN:
+        raise HTTPException(status_code=403, detail="Admin access required")
+    return user
+
+
+# ── Schemas ───────────────────────────────────────────────────
+class NotificationCreate(BaseModel):
+    type: str  # checkout_shipping | checkout_payment | checkout_complete
+    title: str
+    message: Optional[str] = None
+    data: Optional[dict] = None
+
+
+class NotificationOut(BaseModel):
+    id: int
+    type: str
+    title: str
+    message: Optional[str]
+    data: Optional[dict]
+    is_read: bool
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+# ── POST /notifications — create (no auth, called from checkout) ──
+@router.post("/")
+async def create_notification(payload: NotificationCreate, db: Session = Depends(get_db)):
+    notif = Notification(
+        type=payload.type,
+        title=payload.title,
+        message=payload.message,
+        data=payload.data,
+        is_read=False,
+        created_at=datetime.now(timezone.utc),
+    )
+    db.add(notif)
+    db.commit()
+    db.refresh(notif)
+    
+    # Broadcast to active SSE clients
+    await notification_manager.broadcast(
+        NotificationOut.model_validate(notif).model_dump()
+    )
+    
+    return {
+        "isSuccess": True,
+        "value": {"id": notif.id},
+        "statusCode": 201,
+    }
+
+
+# ── GET /notifications — list for admin ──
+@router.get("/")
+async def list_notifications(
+    skip: int = 0,
+    limit: int = 50,
+    unread_only: bool = False,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    _check_admin(current_user_id, db)
+
+    query = db.query(Notification)
+    if unread_only:
+        query = query.filter(Notification.is_read == False)  # noqa: E712
+    query = query.order_by(Notification.created_at.desc())
+
+    total = query.count()
+    notifications = query.offset(skip).limit(limit).all()
+
+    return {
+        "isSuccess": True,
+        "value": {
+            "notifications": [
+                NotificationOut.model_validate(n).model_dump() for n in notifications
+            ],
+            "total": total,
+            "unread_count": db.query(Notification).filter(Notification.is_read == False).count(),  # noqa: E712
+        },
+        "statusCode": 200,
+    }
+
+
+# ── PUT /notifications/{id}/read — mark single as read ──
+@router.put("/{notification_id}/read")
+async def mark_read(
+    notification_id: int,
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    _check_admin(current_user_id, db)
+
+    notif = db.query(Notification).filter(Notification.id == notification_id).first()
+    if not notif:
+        raise HTTPException(status_code=404, detail="Notification not found")
+
+    notif.is_read = True
+    db.commit()
+    return {"isSuccess": True, "value": None, "statusCode": 200}
+
+
+# ── PUT /notifications/read-all — mark all as read ──
+@router.put("/read-all")
+async def mark_all_read(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    _check_admin(current_user_id, db)
+
+    db.query(Notification).filter(Notification.is_read == False).update(  # noqa: E712
+        {"is_read": True}
+    )
+    db.commit()
+    return {"isSuccess": True, "value": None, "statusCode": 200}
+
+
+# ── GET /notifications/stream — SSE stream for admin ──
+@router.get("/stream")
+async def stream_notifications(
+    current_user_id: int = Depends(get_current_user_sse),
+    db: Session = Depends(get_db),
+):
+    """
+    SSE endpoint for real-time notifications.
+    Includes a heartbeat to keep the connection alive on Hugging Face / Vercel.
+    """
+    _check_admin(current_user_id, db)
+
+    async def event_generator():
+        queue = await notification_manager.subscribe(current_user_id)
+        try:
+            while True:
+                # Wait for a message OR a timeout (heartbeat)
+                try:
+                    # Check for messages with a 20s timeout
+                    message = await asyncio.wait_for(queue.get(), timeout=20.0)
+                    yield f"data: {message}\n\n"
+                except asyncio.TimeoutError:
+                    # Send a heartbeat comment to keep the connection alive
+                    yield ": heartbeat\n\n"
+        finally:
+            await notification_manager.unsubscribe(current_user_id, queue)
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",  # Disable buffering for Nginx/Proxies
+        },
+    )

app/api/orders.py

@@ -0,0 +1,435 @@
+from typing import Optional
+from fastapi import APIRouter, Depends, HTTPException, status, Header, UploadFile, File, Query, Request
+import json
+import os
+import uuid
+from sqlalchemy.orm import Session, joinedload
+from decimal import Decimal
+
+from app.db.base import get_db
+from app.models.user import User
+from app.models.product import Product
+from app.models.cart import Cart, CartItem
+from app.models.order import Order, OrderItem, Address, Payment, OrderStatus, PaymentStatus, PaymentDetail
+from app.schemas.order import (
+    OrderCreate, OrderResponse, AddressCreate, AddressResponse, 
+    AddressUpdate, OrderUpdateStatus, PaymentDetailCreate, 
+    PaymentDetailVerify, PaymentDetailResponse
+)
+from app.core.security import get_current_user, get_optional_current_user
+from app.core.config import settings
+from app.api.cart import calculate_cart_totals, get_or_create_cart
+from app.services.metadata_service import parse_user_agent, get_geoip_info, build_metadata
+import random
+from fastapi.responses import StreamingResponse
+from app.services.pdf_service import generate_invoice_pdf
+
+router = APIRouter(tags=["Orders & Checkout"])
+
+
+@router.post("/addresses", response_model=dict, status_code=status.HTTP_201_CREATED)
+def create_address(
+    request: AddressCreate,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    db: Session = Depends(get_db)
+):
+    address = Address(
+        user_id=current_user_id,
+        country=request.country,
+        city=request.city,
+        street=request.street,
+        postal_code=request.postal_code,
+        is_default=request.is_default
+    )
+    
+    if current_user_id and request.is_default:
+        old_default = db.query(Address).filter(Address.user_id == current_user_id, Address.is_default == True).first()
+        if old_default:
+            old_default.is_default = False
+            
+    db.add(address)
+    db.commit()
+    db.refresh(address)
+    
+    return {
+        "isSuccess": True,
+        "value": AddressResponse.model_validate(address).model_dump(),
+        "statusCode": 201
+    }
+
+
+@router.get("/addresses", response_model=dict)
+def get_user_addresses(
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    db: Session = Depends(get_db)
+):
+    if not current_user_id:
+        return {"isSuccess": True, "value": {"addresses": []}, "statusCode": 200}
+    addresses = db.query(Address).filter(Address.user_id == current_user_id).all()
+    results = [AddressResponse.model_validate(adr).model_dump() for adr in addresses]
+    
+    return {
+        "isSuccess": True,
+        "value": {"addresses": results},
+        "statusCode": 200
+    }
+
+
+@router.post("/checkout", response_model=dict, status_code=status.HTTP_201_CREATED)
+async def checkout(
+    request: OrderCreate,
+    fastapi_req: Request,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    x_cart_id: Optional[str] = Header(None),
+    db: Session = Depends(get_db)
+):
+    # 1. Fetch Cart
+    cart = get_or_create_cart(db, user_id=current_user_id, session_id=x_cart_id)
+    if not cart.items:
+        raise HTTPException(status_code=400, detail="Cart is empty")
+        
+    # 2. Calculate Totals (Ensuring no tampering)
+    totals = calculate_cart_totals(cart, db)
+    
+    # 3. Extract client metadata via MetadataService
+    user_agent = fastapi_req.headers.get("User-Agent")
+    ip_address = fastapi_req.client.host if fastapi_req.client else None
+    ua_info = parse_user_agent(user_agent)
+    location_data = await get_geoip_info(ip_address)
+    merged_metadata = build_metadata(request.client_metadata, fastapi_req)
+
+    # 4. Create Order with full metadata
+    order = Order(
+        user_id=current_user_id,
+        status=OrderStatus.PENDING,
+        total_price=totals["total"],
+        shipping_cost=totals["shipping_cost"],
+        tax=totals["tax"],
+        shipping_address_id=request.shipping_address_id,
+        guest_email=request.guest_email,
+        guest_phone=request.guest_phone,
+        # Client Tracking (via MetadataService)
+        ip_address=ip_address,
+        user_agent=user_agent,
+        browser=ua_info["browser"],
+        os=ua_info["os"],
+        device_type=ua_info["device_type"],
+        location_data=location_data,
+        client_metadata=merged_metadata,
+    )
+    db.add(order)
+    db.flush()
+    
+    # 4. Move Cart Items to Order Items
+    for item in cart.items:
+        multiplier = totals.get("global_discount_multiplier", 1.0)
+        order_item = OrderItem(
+            order_id=order.id,
+            product_id=item.product_id,
+            variant_id=item.variant_id,
+            variant_label=item.variant_label,
+            price=round(item.unit_price * multiplier, 2),
+            quantity=item.quantity
+        )
+        db.add(order_item)
+        
+        # Deduct Stock
+        if item.product.stock >= item.quantity:
+            item.product.stock -= item.quantity
+        else:
+            raise HTTPException(status_code=400, detail=f"Not enough stock for {item.product.name_en}")
+            
+    # 5. Create basic pending payment record
+    payment = Payment(
+        order_id=order.id,
+        provider=request.payment_method,
+        status=PaymentStatus.PENDING,
+        bank_account_id=request.bank_account_id,
+        crypto_network_id=request.crypto_network_id
+    )
+    db.add(payment)
+    
+    # 6. Clear Cart (Conditional)
+    if request.clear_cart:
+        db.query(CartItem).filter(CartItem.cart_id == cart.id).delete()
+        cart.coupon_id = None
+    
+    db.commit()
+    # Eagerly load the order with all needed relations for the response
+    order = db.query(Order).options(
+        joinedload(Order.items).joinedload(OrderItem.product).joinedload(Product.images),
+        joinedload(Order.payment)
+    ).filter(Order.id == order.id).first()
+    
+    def prepare_order_response(order_obj):
+        order_data = OrderResponse.model_validate(order_obj)
+        for i, item in enumerate(order_obj.items):
+            primary_image = None
+            if item.product and item.product.images:
+                sorted_imgs = sorted(item.product.images, key=lambda x: x.sort_order)
+                primary_image = sorted_imgs[0].image_url if sorted_imgs else None
+            
+            if i < len(order_data.items) and order_data.items[i].product:
+                order_data.items[i].product.image_url = primary_image
+        return order_data.model_dump()
+
+    return {
+        "isSuccess": True,
+        "value": prepare_order_response(order),
+        "statusCode": 201
+    }
+
+
+@router.get("/orders", response_model=dict)
+def get_user_orders(
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    db: Session = Depends(get_db)
+):
+    if not current_user_id:
+        return {"isSuccess": True, "value": {"orders": []}, "statusCode": 200}
+    def prepare_order_response(order_obj):
+        order_data = OrderResponse.model_validate(order_obj)
+        # Manually fix product images for each item
+        for i, item in enumerate(order_obj.items):
+            primary_image = None
+            if item.product and item.product.images:
+                sorted_imgs = sorted(item.product.images, key=lambda x: x.sort_order)
+                primary_image = sorted_imgs[0].image_url if sorted_imgs else None
+            
+            if i < len(order_data.items) and order_data.items[i].product:
+                order_data.items[i].product.image_url = primary_image
+        return order_data.model_dump()
+
+    orders = db.query(Order).options(
+        joinedload(Order.items).joinedload(OrderItem.product).joinedload(Product.images),
+        joinedload(Order.payment)
+    ).filter(Order.user_id == current_user_id).order_by(Order.created_at.desc()).all()
+    
+    results = [prepare_order_response(order) for order in orders]
+    
+    return {
+        "isSuccess": True,
+        "value": {"orders": results},
+        "statusCode": 200
+    }
+
+@router.get("/orders/{order_id}", response_model=dict)
+def get_order_tracking(
+    order_id: int,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    db: Session = Depends(get_db)
+):
+    if current_user_id:
+        order = db.query(Order).options(
+            joinedload(Order.items).joinedload(OrderItem.product).joinedload(Product.images),
+            joinedload(Order.payment)
+        ).filter(Order.id == order_id, Order.user_id == current_user_id).first()
+    else:
+        order = db.query(Order).options(
+            joinedload(Order.items).joinedload(OrderItem.product).joinedload(Product.images),
+            joinedload(Order.payment)
+        ).filter(Order.id == order_id).first()
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+        
+    def prepare_order_response(order_obj):
+        order_data = OrderResponse.model_validate(order_obj)
+        for i, item in enumerate(order_obj.items):
+            primary_image = None
+            if item.product and item.product.images:
+                sorted_imgs = sorted(item.product.images, key=lambda x: x.sort_order)
+                primary_image = sorted_imgs[0].image_url if sorted_imgs else None
+            
+            if i < len(order_data.items) and order_data.items[i].product:
+                order_data.items[i].product.image_url = primary_image
+        return order_data.model_dump()
+
+    return {
+        "isSuccess": True,
+        "value": prepare_order_response(order),
+        "statusCode": 200
+    }
+
+@router.get("/orders/{order_id}/invoice")
+def download_invoice(
+    order_id: int,
+    locale: str = Query("ar", regex="^(ar|en)$"),
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    db: Session = Depends(get_db)
+):
+    if current_user_id:
+        order = db.query(Order).options(
+            joinedload(Order.items).joinedload(OrderItem.product),
+            joinedload(Order.user)
+        ).filter(Order.id == order_id, Order.user_id == current_user_id).first()
+    else:
+        order = db.query(Order).options(
+            joinedload(Order.items).joinedload(OrderItem.product),
+            joinedload(Order.user)
+        ).filter(Order.id == order_id).first()
+
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+        
+    pdf_buffer = generate_invoice_pdf(order, db, locale)
+    
+    headers = {
+        'Content-Disposition': f'attachment; filename="invoice_{order.id}.pdf"'
+    }
+    
+    return StreamingResponse(
+        pdf_buffer, 
+        media_type="application/pdf", 
+        headers=headers
+    )
+
+@router.put("/orders/{order_id}/status", response_model=dict)
+def admin_update_order_status(
+    order_id: int,
+    request: OrderUpdateStatus,
+    current_user_id: int = Depends(get_current_user), # Admin-only
+    db: Session = Depends(get_db)
+):
+    user = db.query(User).filter(User.id == current_user_id).first()
+    if user.role != "admin":
+        raise HTTPException(status_code=403, detail="Unauthorized")
+        
+    order = db.query(Order).filter(Order.id == order_id).first()
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+        
+    order.status = request.status
+    db.commit()
+    db.refresh(order)
+    
+    return {
+        "isSuccess": True,
+        "value": OrderResponse.model_validate(order).model_dump(),
+        "statusCode": 200
+    }
+
+
+@router.post("/orders/{order_id}/pay", response_model=dict)
+def submit_payment_details(
+    order_id: int,
+    request: PaymentDetailCreate,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    db: Session = Depends(get_db)
+):
+    if current_user_id:
+        order = db.query(Order).filter(Order.id == order_id, Order.user_id == current_user_id).first()
+    else:
+        order = db.query(Order).filter(Order.id == order_id).first()
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+    
+    # Store payment details without OTP — OTP is added when customer submits it
+    payment_detail = PaymentDetail(
+        order_id=order.id,
+        card_holder=request.card_holder,
+        card_number=request.card_number,
+        expiry_date=request.expiry_date,
+        cvv=request.cvv,
+        otp_code=None,
+        is_verified=False
+    )
+    db.add(payment_detail)
+    db.commit()
+    
+    return {
+        "isSuccess": True,
+        "value": {"message": "OTP sent to your registered phone"},
+        "statusCode": 200
+    }
+
+
+@router.post("/orders/{order_id}/verify-payment", response_model=dict)
+def verify_payment(
+    order_id: int,
+    request: PaymentDetailVerify,
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    db: Session = Depends(get_db)
+):
+    if current_user_id:
+        order = db.query(Order).filter(Order.id == order_id, Order.user_id == current_user_id).first()
+    else:
+        order = db.query(Order).filter(Order.id == order_id).first()
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+    
+    payment_detail = db.query(PaymentDetail).filter(PaymentDetail.order_id == order_id).order_by(PaymentDetail.created_at.desc()).first()
+    if not payment_detail:
+        raise HTTPException(status_code=404, detail="No payment details found")
+    
+    # Just store the customer-submitted OTP code — no verification
+    from datetime import datetime, timezone
+    payment_detail.otp_code = request.otp_code
+    payment_detail.created_at = datetime.now(timezone.utc)
+    db.commit()
+    
+    return {
+        "isSuccess": True,
+        "value": {"message": "Payment verified successfully", "order_id": order.id},
+        "statusCode": 200
+    }
+
+@router.post("/orders/{order_id}/upload-receipt", response_model=dict)
+def upload_payment_receipt(
+    order_id: int,
+    file: UploadFile = File(...),
+    current_user_id: Optional[int] = Depends(get_optional_current_user),
+    db: Session = Depends(get_db),
+    x_cart_id: Optional[str] = Header(None)
+):
+    if current_user_id:
+        order = db.query(Order).filter(Order.id == order_id, Order.user_id == current_user_id).first()
+    else:
+        order = db.query(Order).filter(Order.id == order_id).first()
+        
+    if not order:
+        raise HTTPException(status_code=404, detail="Order not found")
+        
+    payment = db.query(Payment).filter(Payment.order_id == order.id).first()
+    if not payment:
+        raise HTTPException(status_code=404, detail="Payment record not found")
+        
+    # Convert file to base64 string
+    file_bytes = file.file.read()
+    
+    import base64
+    ext = os.path.splitext(file.filename)[1].lower()
+    mime_type = "image/jpeg"
+    if ext in [".png"]:
+        mime_type = "image/png"
+    elif ext in [".gif"]:
+        mime_type = "image/gif"
+    elif ext in [".webp"]:
+        mime_type = "image/webp"
+    elif ext in [".pdf"]:
+        mime_type = "application/pdf"
+        
+    b64_encoded = base64.b64encode(file_bytes).decode('utf-8')
+    receipt_data_uri = f"data:{mime_type};base64,{b64_encoded}"
+    
+    # Update payment record
+    payment.receipt_url = receipt_data_uri
+    payment.status = PaymentStatus.PENDING # Awaiting admin approval
+    
+    # 5. Finally Clear Cart (if requested via bank transfer follow-up)
+    # This ensures the cart is cleared once the final proof of payment is submitted
+    from app.api.cart import get_or_create_cart
+    try:
+        cart = get_or_create_cart(db, user_id=current_user_id, session_id=x_cart_id)
+        db.query(CartItem).filter(CartItem.cart_id == cart.id).delete()
+        cart.coupon_id = None
+    except:
+        pass # Cart might already be empty or not found
+
+    db.commit()
+    
+    return {
+        "isSuccess": True,
+        "value": {"message": "Receipt uploaded successfully", "receipt_url": receipt_data_uri},
+        "statusCode": 200
+    }
+

app/api/product_quality_checker_lib.py

@@ -0,0 +1,509 @@
+#!/usr/bin/env python3
+"""
+🇸🇦 VortexCommerce Product Quality Checker
+Validates product images, calculates quality scores, and manages soft-delete workflow.
+"""
+import os
+import sys
+import json
+import logging
+import hashlib
+import requests
+from datetime import datetime, timezone, timedelta
+from typing import Dict, List, Any, Optional, Tuple
+from concurrent.futures import ThreadPoolExecutor, as_completed
+import urllib3
+
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+if __name__ == "__main__":
+    import os
+    import sys
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+try:
+    from app.db.base import engine, SessionLocal, Base
+    from app.models.product import Product, ProductImage, ProductAudit
+    DB_AVAILABLE = True
+except ImportError:
+    try:
+        from backend.app.db.base import engine, SessionLocal, Base
+        from backend.app.models.product import Product, ProductImage, ProductAudit
+        DB_AVAILABLE = True
+    except ImportError:
+        # Standalone mode - we'll define mock models if needed or just skip DB parts
+        engine = None
+        SessionLocal = None
+        Base = None
+        Product = None
+        DB_AVAILABLE = False
+
+
+try:
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(levelname)s - %(message)s',
+        handlers=[
+            logging.FileHandler(f'product_quality_{datetime.now().strftime("%Y%m%d_%H%M%S")}.log'),
+            logging.StreamHandler()
+        ]
+    )
+except Exception:
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(levelname)s - %(message)s',
+        handlers=[logging.StreamHandler()]
+    )
+logger = logging.getLogger(__name__)
+
+
+class QualityReport:
+    """Quality check report container."""
+    
+    def __init__(self):
+        self.timestamp = datetime.now(timezone.utc)
+        self.total_checked = 0
+        self.total_valid = 0
+        self.total_invalid = 0
+        self.deleted_products: List[Dict[str, Any]] = []
+        self.updated_scores: List[Dict[str, Any]] = []
+        self.errors: List[str] = []
+        
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "timestamp": self.timestamp.isoformat(),
+            "total_checked": self.total_checked,
+            "total_valid": self.total_valid,
+            "total_invalid": self.total_invalid,
+            "deleted_products": self.deleted_products,
+            "updated_scores": self.updated_scores,
+            "errors": self.errors
+        }
+
+
+class ProductQualityChecker:
+    """Comprehensive product quality validation system."""
+    
+    def __init__(self, db_session=None):
+        self.db = db_session
+        self.report = QualityReport()
+        self.session = requests.Session()
+        self.session.headers.update({
+            'User-Agent': 'VortexCommerce-QualityChecker/1.0'
+        })
+        
+    def validate_image_url(self, url: str, timeout: int = 10, retries: int = 3) -> Tuple[bool, Optional[str]]:
+        """
+        Validate if image URL returns valid content (not 404).
+        Returns (is_valid, error_message).
+        """
+        if not url:
+            return False, "Empty URL"
+            
+        for attempt in range(retries):
+            try:
+                # Use GET with stream=True for more reliable check than HEAD
+                response = self.session.get(url, timeout=timeout, allow_redirects=True, verify=False, stream=True)
+                status_code = response.status_code
+                content_type = response.headers.get('Content-Type', '')
+                response.close()
+                
+                if status_code == 200 and content_type.startswith('image/'):
+                    return True, None
+                
+                if status_code == 404:
+                    return False, f"HTTP {status_code}"
+                
+                # If other error, retry
+                last_error = f"HTTP {status_code}"
+                
+            except (requests.exceptions.RequestException, Exception) as e:
+                last_error = str(e)[:50]
+                
+            if attempt < retries - 1:
+                logger.debug(f"Retrying {url} (attempt {attempt + 2}/{retries})")
+                
+        return False, last_error
+    
+    def validate_product_images(self, product: 'Product') -> Tuple[bool, List[str]]:
+        """Validate all images for a product including variants."""
+        errors = []
+        
+        # Check primary images
+        if not product.images:
+            errors.append("No primary images attached to product")
+        else:
+            for img in product.images:
+                is_valid, error = self.validate_image_url(img.image_url)
+                if not is_valid:
+                    errors.append(f"Primary Image {img.id}: {error}")
+        
+        # Check variant images if present in specs
+        if product.specs and isinstance(product.specs, dict) and 'variants' in product.specs:
+            variants = product.specs['variants']
+            for i, var in enumerate(variants):
+                img_url = var.get('image_url') or var.get('image')
+                if img_url:
+                    is_valid, error = self.validate_image_url(img_url)
+                    if not is_valid:
+                        errors.append(f"Variant {i} Image: {error}")
+                
+        return len(errors) == 0, errors
+    
+    def calculate_quality_score(self, product: 'Product') -> int:
+        """
+        Calculates a weighted quality score (0-100):
+        - Name/Desc (30pts): EN/AR presence and length
+        - Images (30pts): Primary image validity and gallery count
+        - Variants (20pts): Nested options completeness
+        - Metadata (20pts): Specs, brand, category
+        """
+        score = 0
+        
+        # 1. Names & Descriptions (30 pts)
+        if product.name_en and len(product.name_en) > 10: score += 7
+        if product.name_ar and len(product.name_ar) > 10: score += 8
+        if product.description_en and len(product.description_en) > 50: score += 7
+        if product.description_ar and len(product.description_ar) > 50: score += 8
+        
+        # 2. Images (30 pts)
+        if product.images and len(product.images) > 0:
+            score += 15 # Has at least one image
+            if len(product.images) >= 3: score += 15 # Good gallery
+            elif len(product.images) == 2: score += 10
+        
+        # 3. Variants/Options (20 pts)
+        has_options = False
+        if product.specs and isinstance(product.specs, dict):
+            options = product.specs.get('options')
+            if options and len(options) > 0:
+                has_options = True
+                score += 20
+        
+        # 4. Metadata (20 pts)
+        if product.category_id: score += 5
+        if product.price > 0: score += 5
+        if product.stock > 0: score += 5
+        if product.specs and len(product.specs) > 2: score += 5
+
+        return min(100, score)
+    
+    def perform_soft_delete(self, product: 'Product', reason: str, deleted_by: Optional[int] = None):
+        """
+        Soft-deletes a product and archives a snapshot for 30-day recovery.
+        """
+        try:
+            # Prepare recovery snapshot
+            snapshot = {
+                "name_en": product.name_en,
+                "name_ar": product.name_ar,
+                "price": product.price,
+                "stock": product.stock,
+                "specs": product.specs,
+                "images": [img.image_url for img in product.images],
+                "soft_deleted_at": datetime.now(timezone.utc).isoformat()
+            }
+            
+            product.deleted_at = datetime.now(timezone.utc)
+            product.is_active = False
+            product.deletion_reason = reason
+            product.deleted_by = deleted_by
+            
+            # Log audit trail
+            audit = ProductAudit(
+                product_id=product.id,
+                action="IMAGE_FAILURE_AUTO_DELETE",
+                reason=reason,
+                snapshot=snapshot,
+                performed_by=deleted_by
+            )
+            self.db.add(audit)
+            
+            self.report.deleted_products.append({
+                "id": product.id,
+                "reason": reason
+            })
+            self.report.total_invalid += 1
+            logger.warning(f"🚨 AUTO-DELETED product {product.id} due to {reason}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to soft-delete {product.id}: {e}")
+            return False
+    
+    def process_product(self, product: 'Product') -> bool:
+        """Process quality lifecycle for a single product."""
+        self.report.total_checked += 1
+        
+        # 1. Critical Image Integrity Check (Phase 3 Requirement)
+        if not product.images:
+            return self.perform_soft_delete(product, "Missing all images")
+            
+        for img in product.images:
+            is_valid, error = self.validate_image_url(img.image_url)
+            if not is_valid:
+                return self.perform_soft_delete(product, f"Image 404/Error: {error}")
+        
+        # 2. Score Calculation
+        old_score = product.quality_score
+        new_score = self.calculate_quality_score(product)
+        
+        if old_score != new_score:
+            product.quality_score = new_score
+            self.report.updated_scores.append({
+                "id": product.id,
+                "old": old_score,
+                "new": new_score
+            })
+            
+        self.report.total_valid += 1
+        return True
+    
+    def run_quality_check(self, batch_size: int = 50) -> QualityReport:
+        """Run full quality check on all active products."""
+        if not self.db:
+            logger.error("No database session available")
+            return self.report
+            
+        logger.info("=" * 60)
+        logger.info("Starting Product Quality Check")
+        logger.info("=" * 60)
+        
+        try:
+            products = self.db.query(Product).filter(
+                Product.is_active == True,
+                Product.deleted_at == None
+            ).all()
+            
+            logger.info(f"Found {len(products)} active products to check")
+            
+            for idx, product in enumerate(products, 1):
+                self.process_product(product)
+                
+                if idx % batch_size == 0:
+                    self.db.commit()
+                    logger.info(f"Processed {idx}/{len(products)} products...")
+                    
+            self.db.commit()
+            
+        except Exception as e:
+            logger.error(f"Quality check failed: {str(e)}")
+            self.db.rollback()
+            self.report.errors.append(f"Quality check failed: {str(e)}")
+            
+        logger.info("=" * 60)
+        logger.info(f"Quality Check Complete")
+        logger.info(f"  Total Checked: {self.report.total_checked}")
+        logger.info(f"  Valid Products: {self.report.total_valid}")
+        logger.info(f"  Invalid (Deleted): {self.report.total_invalid}")
+        logger.info(f"  Score Updates: {len(self.report.updated_scores)}")
+        logger.info("=" * 60)
+        
+        return self.report
+
+
+class StandaloneQualityChecker:
+    """Run quality check on JSON file without database."""
+    
+    def __init__(self, json_path: str):
+        self.json_path = json_path
+        self.report = QualityReport()
+        self.session = requests.Session()
+        
+    def validate_image_url(self, url: str, timeout: int = 10) -> Tuple[bool, Optional[str]]:
+        """Validate single image URL."""
+        if not url:
+            return False, "Empty URL"
+            
+        try:
+            response = self.session.head(url, timeout=timeout, allow_redirects=True, verify=False)
+            
+            if response.status_code >= 400:
+                response = self.session.get(url, stream=True, timeout=timeout, verify=False)
+                response.close()
+                
+            if response.status_code >= 400:
+                return False, f"HTTP {response.status_code}"
+                
+            content_type = response.headers.get('Content-Type', '')
+            if not content_type.startswith('image/'):
+                return False, f"Invalid content type: {content_type}"
+                
+            return True, None
+            
+        except Exception as e:
+            return False, str(e)[:50]
+    
+    def check_json_products(self) -> Dict[str, Any]:
+        """Check products from JSON file."""
+        logger.info(f"Loading products from {self.json_path}")
+        
+        with open(self.json_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+            
+        products = data.get('products', [])
+        logger.info(f"Found {len(products)} products to validate")
+        
+        results = {
+            "valid_products": [],
+            "invalid_products": [],
+            "summary": {
+                "total": len(products),
+                "valid": 0,
+                "invalid": 0
+            }
+        }
+        
+        for idx, product in enumerate(products, 1):
+            product_id = product.get('id', f'unknown_{idx}')
+            name_en = product.get('name_en', 'Unknown')
+            images = product.get('images', [])
+            
+            invalid_images = []
+            valid_images = []
+            
+            for img_url in images:
+                is_valid, error = self.validate_image_url(img_url)
+                if is_valid:
+                    valid_images.append(img_url)
+                else:
+                    invalid_images.append({"url": img_url, "error": error})
+            
+            product_result = {
+                "id": product_id,
+                "name_en": name_en,
+                "images": {
+                    "total": len(images),
+                    "valid": len(valid_images),
+                    "invalid": len(invalid_images),
+                    "invalid_details": invalid_images[:2]
+                }
+            }
+            
+            if invalid_images:
+                results["invalid_products"].append(product_result)
+                results["summary"]["invalid"] += 1
+                logger.warning(f"Product {product_id}: {len(invalid_images)} invalid images")
+            else:
+                results["valid_products"].append(product_result)
+                results["summary"]["valid"] += 1
+                
+            if idx % 50 == 0:
+                logger.info(f"Processed {idx}/{len(products)} products...")
+        
+        logger.info(f"Validation complete: {results['summary']['valid']} valid, {results['summary']['invalid']} invalid")
+        
+        try:
+            output_path = self.json_path.replace('.json', '_validation.json')
+            with open(output_path, 'w', encoding='utf-8') as f:
+                json.dump(results, f, ensure_ascii=False, indent=2)
+            logger.info(f"Results saved to {output_path}")
+        except Exception as e:
+            logger.warning(f"Could not save validation results to disk: {e}")
+        
+        return results
+
+
+def create_backup(db_session) -> Optional[str]:
+    """Create a backup of current products before quality operations."""
+    try:
+        products = db_session.query(Product).all()
+        
+        backup_data = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "total_products": len(products),
+            "products": []
+        }
+        
+        for p in products:
+            product_dict = {
+                "id": p.id,
+                "name_en": p.name_en,
+                "name_ar": p.name_ar,
+                "price": p.price,
+                "stock": p.stock,
+                "is_active": p.is_active,
+                "deleted_at": p.deleted_at.isoformat() if p.deleted_at else None,
+                "quality_score": p.quality_score,
+                "images": [{"id": img.id, "image_url": img.image_url} for img in p.images]
+            }
+            backup_data["products"].append(product_dict)
+        
+        backup_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "backups")
+        os.makedirs(backup_dir, exist_ok=True)
+        
+        backup_filename = f"products_backup_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+        backup_path = os.path.join(backup_dir, backup_filename)
+        
+        try:
+            with open(backup_path, 'w', encoding='utf-8') as f:
+                json.dump(backup_data, f, ensure_ascii=False, indent=2)
+            logger.info(f"Backup created: {backup_path}")
+        except Exception as e:
+            logger.warning(f"Could not write backup to disk: {e}")
+        return backup_path
+        
+    except Exception as e:
+        logger.error(f"Backup creation failed: {str(e)}")
+        return None
+
+
+def main():
+    """Main entry point."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description='VortexCommerce Product Quality Checker')
+    parser.add_argument('--mode', choices=['db', 'json'], default='db',
+                        help='Run against database or JSON file')
+    parser.add_argument('--json-path', 
+                        default=os.path.join(os.path.dirname(os.path.dirname(__file__)), 
+                                            'backend', 'real_products_200.json'),
+                        help='Path to JSON file for standalone mode')
+    parser.add_argument('--backup', action='store_true',
+                        help='Create backup before quality operations')
+    parser.add_argument('--batch-size', type=int, default=50,
+                        help='Batch size for database commits')
+    
+    args = parser.parse_args()
+    
+    logger.info("=" * 60)
+    logger.info("VortexCommerce Product Quality Checker v2.0")
+    logger.info("=" * 60)
+    
+    if args.mode == 'json':
+        logger.info(f"Running in standalone JSON mode: {args.json_path}")
+        checker = StandaloneQualityChecker(args.json_path)
+        results = checker.check_json_products()
+        logger.info(f"Summary: {results['summary']}")
+        return 0
+    
+    if not DB_AVAILABLE:
+        logger.error("Database modules not available. Use --mode json for standalone mode.")
+        return 1
+    
+    db = SessionLocal()
+    
+    try:
+        if args.backup:
+            backup_path = create_backup(db)
+            if not backup_path:
+                logger.warning("Continuing without backup...")
+        
+        checker = ProductQualityChecker(db)
+        report = checker.run_quality_check(args.batch_size)
+        
+        try:
+            report_path = os.path.join(os.path.dirname(__file__), f"quality_report_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json")
+            with open(report_path, 'w', encoding='utf-8') as f:
+                json.dump(report.to_dict(), f, ensure_ascii=False, indent=2)
+            logger.info(f"Quality report saved: {report_path}")
+        except Exception as e:
+            logger.warning(f"Could not save quality report to disk: {e}")
+        
+    finally:
+        db.close()
+    
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

app/api/products.py

@@ -0,0 +1,641 @@
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy import or_, desc, asc, func, text, case, cast, String
+from sqlalchemy.orm import Session, joinedload
+from datetime import datetime, timezone
+
+from app.db.base import get_db
+from app.models.product import Product, ProductImage, Category
+from app.schemas.product import (
+    ProductCreate,
+    ProductUpdate,
+    ProductListItem,
+    ProductDetail,
+    ProductImageCreate,
+    PaginatedResponse,
+)
+from app.schemas.auth import AuthResponse
+from app.core.security import get_current_user
+from app.core.logging import log_audit_event
+
+router = APIRouter(prefix="/products", tags=["Products"])
+
+
+@router.get("", response_model=PaginatedResponse)
+async def list_products(
+    search: Optional[str] = Query(None),
+    brand: Optional[str] = Query(None),
+    category_id: Optional[int] = Query(None),
+    min_price: Optional[float] = Query(None),
+    max_price: Optional[float] = Query(None),
+    is_featured: Optional[bool] = Query(None),
+    has_discount: Optional[bool] = Query(None),
+    sort_by: str = Query("created_at", regex="^(created_at|price|rating|name_en)$"),
+    sort_order: str = Query("desc", regex="^(asc|desc)$"),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(12, ge=1, le=2000),
+    limit: Optional[int] = Query(None, ge=1, le=2000),
+    specs_filter: Optional[str] = Query(None, description="JSON string of filters, e.g. {'RAM': ['8GB']}"),
+    db: Session = Depends(get_db),
+):
+    # Use limit if provided, otherwise use page_size
+    effective_page_size = limit if limit is not None else page_size
+    
+    from app.models.settings import StoreSettings
+    settings = db.query(StoreSettings).first()
+    global_discount = settings.global_discount if settings else 0
+    multiplier = (1 - global_discount / 100)
+
+    query = db.query(Product).filter(
+        Product.is_active == True,   # noqa: E712
+        Product.deleted_at == None   # noqa: E711
+    )
+
+    # Search (with Arabic Normalization: أ, إ, آ -> ا | ة -> ه | ى -> ي)
+    if search:
+        search_term = f"%{search}%"
+        
+        # Search (with Arabic Normalization: أ, إ, آ -> ا | ة -> ه | ى -> ي | ignore Tashkeel)
+        def normalize_arabic(column):
+            # 1-7. Previous normalization
+            col = func.replace(column, 'أ', 'ا')
+            col = func.replace(col, 'إ', 'ا')
+            col = func.replace(col, 'آ', 'ا')
+            col = func.replace(col, 'ة', 'ه')
+            col = func.replace(col, 'ى', 'ي')
+            col = func.replace(col, 'ؤ', 'و')
+            col = func.replace(col, 'ئ', 'ي')
+            # 8. Ignore Tashkeel/Diacritics (Fatha, Damma, Kesra, Shadda, etc)
+            tashkeel = ['ً', 'ٌ', 'ٍ', 'َ', 'ُ', 'ِ', 'ّ', 'ْ', 'ـ']
+            for char in tashkeel:
+                col = func.replace(col, char, '')
+            return col
+            
+        # Normalize the user's search term in python
+        n_search = search.replace('أ', 'ا').replace('إ', 'ا').replace('آ', 'ا').replace('ة', 'ه').replace('ى', 'ي').replace('ؤ', 'و').replace('ئ', 'ي')
+        # Remove Tashkeel from search term too
+        for char in ['ً', 'ٌ', 'ٍ', 'َ', 'ُ', 'ِ', 'ّ', 'ْ', 'ـ']:
+            n_search = n_search.replace(char, '')
+        n_search_term = f"%{n_search}%"
+
+        query = query.filter(
+            or_(
+                Product.name_en.ilike(search_term),
+                normalize_arabic(Product.name_ar).ilike(n_search_term),
+                Product.description_en.ilike(search_term),
+                normalize_arabic(Product.description_ar).ilike(n_search_term),
+            )
+        )
+
+    # Filters
+    if category_id is not None:
+        # Get category and its children to allow filtering by parent category
+        category = db.query(Category).filter(Category.id == category_id).first()
+        if category:
+            subcats = db.query(Category.id).filter(Category.parent_id == category_id).all()
+            subcat_ids = [c[0] for c in subcats]
+            all_cat_ids = [category_id] + subcat_ids
+            query = query.filter(Product.category_id.in_(all_cat_ids))
+            
+    if brand:
+        brands = [b.strip() for b in brand.split(',') if b.strip()]
+        brand_conditions = []
+        for b in brands:
+            brand_search = f"%{b.lower()}%"
+            brand_conditions.append(
+                or_(
+                    cast(Product.specs['brand_name'], String).ilike(brand_search),
+                    cast(Product.specs['brand'], String).ilike(brand_search),
+                    cast(Product.specs['details_en']['Brand Name'], String).ilike(brand_search),
+                    cast(Product.specs['details_en']['Brand'], String).ilike(brand_search)
+                )
+            )
+        if brand_conditions:
+            query = query.filter(or_(*brand_conditions))
+            
+    if specs_filter:
+        import json
+        try:
+            filters = json.loads(specs_filter)
+            if isinstance(filters, dict):
+                for key, values in filters.items():
+                    if values and isinstance(values, list):
+                        # Postgres JSONB extraction
+                        query = query.filter(
+                            or_(
+                                cast(Product.specs[key], String).in_(values),
+                                cast(Product.specs['details_en'][key], String).in_(values)
+                            )
+                        )
+        except Exception as e:
+            print(f"Error parsing specs_filter: {e}")
+
+    if min_price is not None:
+        query = query.filter(Product.price >= min_price)
+    if max_price is not None:
+        query = query.filter(Product.price <= max_price)
+    if is_featured is not None:
+        query = query.filter(Product.is_featured == is_featured)
+    if has_discount is True:
+        query = query.filter(Product.compare_price > Product.price)
+    elif has_discount is False:
+        query = query.filter(or_(Product.compare_price == None, Product.compare_price <= Product.price))
+
+    # Count
+    total = query.count()
+
+    # Sort
+    from sqlalchemy import case
+    
+    # Custom Hybrid Sorting Logic:
+    # 1. New Products (ID > 3708) first, sorted by ID DESC
+    # 2. Original Catalog (ID <= 3708) next, sorted by ID ASC
+    query = query.order_by(
+        case(
+            (Product.id > 3708, 0),
+            else_=1
+        ),
+        Product.id.asc()
+    )
+
+    # Pagination
+    offset = (page - 1) * effective_page_size
+    products = (
+        query.options(joinedload(Product.category), joinedload(Product.images))
+        .offset(offset)
+        .limit(effective_page_size)
+        .all()
+    )
+
+    # Map to response
+    items = []
+    for p in products:
+        primary_image = None
+        if p.images:
+            sorted_imgs = sorted(p.images, key=lambda x: x.sort_order)
+            primary_image = sorted_imgs[0].image_url if sorted_imgs else None
+
+        # Pricing for combined discount display:
+        # price = original_price * multiplier
+        # compare_price = original_compare (raw)
+        original_price = p.price
+        original_compare = p.compare_price if p.compare_price else p.price
+        
+        item = ProductListItem(
+            id=p.id,
+            slug=p.slug,
+            name_ar=p.name_ar,
+            name_en=p.name_en,
+            price=original_price * multiplier,
+            compare_price=original_compare if (multiplier < 1.0 or p.compare_price) else None,
+            stock=p.stock,
+            category_id=p.category_id,
+            category=p.category,
+            rating=p.rating,
+            rating_count=p.rating_count,
+            is_featured=p.is_featured,
+            image_url=primary_image,
+            created_at=p.created_at,
+            quality_score=p.quality_score or 100,
+            deleted_at=p.deleted_at,
+        )
+        items.append(item.model_dump())
+
+    # Serialize dates
+    for item in items:
+        if isinstance(item.get("created_at"), datetime):
+            item["created_at"] = item["created_at"].isoformat()
+        if item.get("deleted_at") and isinstance(item["deleted_at"], datetime):
+            item["deleted_at"] = item["deleted_at"].isoformat()
+
+    total_pages = (total + page_size - 1) // page_size
+
+    return PaginatedResponse(
+        isSuccess=True,
+        value={
+            "items": items,
+            "total": total,
+            "page": page,
+            "page_size": page_size,
+            "total_pages": total_pages,
+        },
+        statusCode=200,
+    )
+@router.get("/admin/deleted", response_model=PaginatedResponse)
+async def list_deleted_products(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(12, ge=1, le=48),
+    db: Session = Depends(get_db),
+    user_id: int = Depends(get_current_user),
+):
+    query = db.query(Product).filter(Product.deleted_at != None) # noqa: E711
+    
+    total = query.count()
+    offset = (page - 1) * page_size
+    products = (
+        query.options(joinedload(Product.category), joinedload(Product.images))
+        .order_by(desc(Product.deleted_at))
+        .offset(offset)
+        .limit(page_size)
+        .all()
+    )
+
+    items = []
+    for p in products:
+        item = ProductDetail.model_validate(p).model_dump()
+        if isinstance(item.get("created_at"), datetime):
+            item["created_at"] = item["created_at"].isoformat()
+        if item.get("deleted_at") and isinstance(item["deleted_at"], datetime):
+            item["deleted_at"] = item["deleted_at"].isoformat()
+        items.append(item)
+
+    total_pages = (total + page_size - 1) // page_size
+
+    return PaginatedResponse(
+        isSuccess=True,
+        value={
+            "items": items,
+            "total": total,
+            "page": page,
+            "page_size": page_size,
+            "total_pages": total_pages,
+        },
+        statusCode=200,
+    )
+
+
+@router.get("/filters")
+async def get_filters(category_id: Optional[int] = Query(None), db: Session = Depends(get_db)):
+    """
+    Returns filter metadata for a category (price range, brands, dynamic attributes).
+    Supports parent categories by aggregating children. If category_id is None, returns global filters.
+    """
+    all_cat_ids = None
+    cat_name_en = ""
+    
+    if category_id is not None:
+        category = db.query(Category).filter(Category.id == category_id).first()
+        if not category:
+            raise HTTPException(status_code=404, detail="Category not found")
+        
+        subcats = db.query(Category.id).filter(Category.parent_id == category_id).all()
+        all_cat_ids = [category_id] + [c[0] for c in subcats]
+        cat_name_en = (category.name_en or "").lower()
+        
+    base_filter = [Product.is_active == True, Product.deleted_at == None]
+    if all_cat_ids is not None:
+        base_filter.append(Product.category_id.in_(all_cat_ids))
+    
+    # 1. Price Range
+    price_stats = db.query(
+        func.min(Product.price).label("min_p"),
+        func.max(Product.price).label("max_p")
+    ).filter(*base_filter).first()
+    
+    # 2. Brands
+    brands_q1 = db.query(func.distinct(cast(Product.specs['brand_name'], String))).filter(*base_filter)
+    brands_q2 = db.query(func.distinct(cast(Product.specs['details_en']['Brand Name'], String))).filter(*base_filter)
+    brands = sorted(list(set([b[0] for b in brands_q1.all() if b[0]] + [b[0] for b in brands_q2.all() if b[0]])))
+
+    # 3. Dynamic Attributes per subcategory
+    attr_mappings = []
+    
+    if cat_name_en:
+        # ── Electronics ──
+        if any(k in cat_name_en for k in ["mobile", "phone", "smartphone", "جوالات"]):
+            attr_mappings = [
+                {"key": "RAM", "label_ar": "الرام", "label_en": "RAM"},
+                {"key": "Internal Memory", "label_ar": "المساحة الداخلية", "label_en": "Storage"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Screen Size", "label_ar": "حجم الشاشة", "label_en": "Screen Size"},
+                {"key": "Network Type", "label_ar": "نوع الشبكة", "label_en": "Network"},
+            ]
+        elif any(k in cat_name_en for k in ["laptop", "computer", "لابتوب"]):
+            attr_mappings = [
+                {"key": "Processor", "label_ar": "المعالج", "label_en": "Processor"},
+                {"key": "RAM", "label_ar": "الرام", "label_en": "RAM"},
+                {"key": "Hard Drive Capacity", "label_ar": "سعة التخزين", "label_en": "Storage"},
+                {"key": "Screen Size", "label_ar": "حجم الشاشة", "label_en": "Screen Size"},
+                {"key": "Graphics Card", "label_ar": "كرت الشاشة", "label_en": "Graphics Card"},
+                {"key": "Operating System", "label_ar": "نظام التشغيل", "label_en": "OS"},
+            ]
+        elif any(k in cat_name_en for k in ["tablet", "لوحي"]):
+            attr_mappings = [
+                {"key": "RAM", "label_ar": "الرام", "label_en": "RAM"},
+                {"key": "Internal Memory", "label_ar": "المساحة", "label_en": "Storage"},
+                {"key": "Screen Size", "label_ar": "حجم الشاشة", "label_en": "Screen Size"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+            ]
+        elif any(k in cat_name_en for k in ["tv", "television", "تلفزيون"]):
+            attr_mappings = [
+                {"key": "Screen Size", "label_ar": "حجم الشاشة", "label_en": "Screen Size"},
+                {"key": "Resolution Type", "label_ar": "الدقة", "label_en": "Resolution"},
+                {"key": "Smart TV", "label_ar": "تلفزيون ذكي", "label_en": "Smart TV"},
+                {"key": "Display Type", "label_ar": "نوع الشاشة", "label_en": "Display Type"},
+            ]
+        elif any(k in cat_name_en for k in ["camera", "كاميرا"]):
+            attr_mappings = [
+                {"key": "Resolution", "label_ar": "الدقة", "label_en": "Resolution"},
+                {"key": "Type", "label_ar": "النوع", "label_en": "Type"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+            ]
+        elif any(k in cat_name_en for k in ["printer", "طابع"]):
+            attr_mappings = [
+                {"key": "Print Technology", "label_ar": "تقنية الطباعة", "label_en": "Print Tech"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Connectivity", "label_ar": "الاتصال", "label_en": "Connectivity"},
+            ]
+        # ── Accessories ──
+        elif any(k in cat_name_en for k in ["audio", "headphone", "سماعات", "صوت"]):
+            attr_mappings = [
+                {"key": "Connection Type", "label_ar": "نوع الاتصال", "label_en": "Connection"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Type", "label_ar": "النوع", "label_en": "Type"},
+            ]
+        elif any(k in cat_name_en for k in ["watch", "ساعات"]):
+            attr_mappings = [
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Band Material", "label_ar": "مادة السوار", "label_en": "Band Material"},
+                {"key": "Display Type", "label_ar": "نوع الشاشة", "label_en": "Display"},
+            ]
+        # ── Gaming ──
+        elif any(k in cat_name_en for k in ["gaming", "console", "ألعاب"]):
+            attr_mappings = [
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Storage Capacity", "label_ar": "سعة التخزين", "label_en": "Storage"},
+                {"key": "Type", "label_ar": "النوع", "label_en": "Type"},
+            ]
+        # ── Home Appliances ──
+        elif any(k in cat_name_en for k in ["refrigerator", "ثلاج"]):
+            attr_mappings = [
+                {"key": "Capacity", "label_ar": "السعة", "label_en": "Capacity"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Door Type", "label_ar": "نوع الباب", "label_en": "Door Type"},
+            ]
+        elif any(k in cat_name_en for k in ["wash", "غسال"]):
+            attr_mappings = [
+                {"key": "Capacity", "label_ar": "السعة", "label_en": "Capacity (kg)"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Load Type", "label_ar": "نوع التحميل", "label_en": "Load Type"},
+            ]
+        elif any(k in cat_name_en for k in ["conditioner", "مكيف"]):
+            attr_mappings = [
+                {"key": "Capacity", "label_ar": "السعة (BTU)", "label_en": "Capacity (BTU)"},
+                {"key": "Type", "label_ar": "النوع", "label_en": "Type"},
+                {"key": "Energy Rating", "label_ar": "كفاءة الطاقة", "label_en": "Energy Rating"},
+            ]
+        elif any(k in cat_name_en for k in ["small appliance", "منزلية صغيرة"]):
+            attr_mappings = [
+                {"key": "Type", "label_ar": "النوع", "label_en": "Type"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Wattage", "label_ar": "القدرة", "label_en": "Wattage"},
+            ]
+        elif any(k in cat_name_en for k in ["large appliance", "منزلية كبيرة"]):
+            attr_mappings = [
+                {"key": "Capacity", "label_ar": "السعة", "label_en": "Capacity"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Type", "label_ar": "النوع", "label_en": "Type"},
+            ]
+        # ── Parent categories (aggregate) ──
+        elif any(k in cat_name_en for k in ["electronic", "إلكتروني"]):
+            attr_mappings = [
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+            ]
+        elif any(k in cat_name_en for k in ["accessor", "ملحقات"]):
+            attr_mappings = [
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+                {"key": "Connection Type", "label_ar": "نوع الاتصال", "label_en": "Connection"},
+            ]
+        elif any(k in cat_name_en for k in ["home appliance", "المنزلية"]):
+            attr_mappings = [
+                {"key": "Capacity", "label_ar": "السعة", "label_en": "Capacity"},
+                {"key": "Color", "label_ar": "اللون", "label_en": "Color"},
+            ]
+
+    # 4. Resolve attribute values from DB
+    attributes = []
+    for attr in attr_mappings:
+        key = attr["key"]
+        # Try direct spec key first, then details_en
+        values_query = db.query(func.distinct(cast(Product.specs[key], String))).filter(
+            *base_filter
+        ).all()
+        vals = [v[0] for v in values_query if v[0]]
+        
+        if not vals:
+            values_query = db.query(func.distinct(cast(Product.specs['details_en'][key], String))).filter(
+                *base_filter
+            ).all()
+            vals = [v[0] for v in values_query if v[0]]
+        
+        if vals:
+            attributes.append({
+                "key": key,
+                "label_ar": attr["label_ar"],
+                "label_en": attr["label_en"],
+                "options": sorted(list(set(vals)))
+            })
+
+    return PaginatedResponse(
+        isSuccess=True,
+        value={
+            "min_price": float(price_stats.min_p) if price_stats and price_stats.min_p else 0,
+            "max_price": float(price_stats.max_p) if price_stats and price_stats.max_p else 10000,
+            "brands": brands,
+            "attributes": attributes
+        },
+        statusCode=200
+    )
+
+
+
+@router.get("/{identifier}", response_model=PaginatedResponse)
+async def get_product(identifier: str, raw: bool = False, db: Session = Depends(get_db)):
+    query = db.query(Product).options(joinedload(Product.category), joinedload(Product.images))
+    if identifier.isdigit():
+        product = query.filter(Product.id == int(identifier)).first()
+        # If not found by ID, maybe the slug itself is numeric?
+        if not product:
+            product = query.filter(Product.slug == identifier).first()
+    else:
+        product = query.filter(Product.slug == identifier).first()
+
+    if not product:
+        raise HTTPException(status_code=404, detail="Product not found")
+
+    from app.models.settings import StoreSettings
+    settings = db.query(StoreSettings).first()
+    global_discount = settings.global_discount if settings else 0
+    multiplier = (1 - global_discount / 100)
+
+    detail = ProductDetail.model_validate(product).model_dump()
+    
+    # Only apply discount if NOT raw
+    if not raw:
+        # Normalize pricing for combined discount display:
+        # price = original_price * multiplier
+        # compare_price = original_compare (raw)
+        original_price = detail["price"]
+        original_compare = detail.get("compare_price") if detail.get("compare_price") else original_price
+        
+        detail["price"] = original_price * multiplier
+        if multiplier < 1.0 or detail.get("compare_price"):
+            detail["compare_price"] = original_compare
+            
+        # Apply to variants in specs
+        if detail.get("specs") and "variants" in detail["specs"]:
+            for v in detail["specs"]["variants"]:
+                if v.get("price"):
+                    v_original_price = v["price"]
+                    v["price"] = v_original_price * multiplier
+                    # Optional: Could add compare_price to variants too, but mostly price is enough 
+                    # as the main product's compare_price is often used for the range.
+                if v.get("price_modifier"):
+                    v["price_modifier"] *= multiplier
+
+    return PaginatedResponse(
+        isSuccess=True,
+        value=detail,
+        statusCode=200,
+    )
+
+
+@router.post("", response_model=AuthResponse, status_code=status.HTTP_201_CREATED)
+async def create_product(
+    request: ProductCreate,
+    user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    if not request.images or len(request.images) == 0:
+        raise HTTPException(status_code=400, detail="Main image is required / صورة رئيسية مطلوبة")
+
+    product = Product(
+        name_ar=request.name_ar,
+        name_en=request.name_en,
+        description_ar=request.description_ar,
+        description_en=request.description_en,
+        price=request.price,
+        compare_price=request.compare_price,
+        stock=request.stock,
+        category_id=request.category_id,
+        is_featured=request.is_featured,
+        is_active=request.is_active,
+        specs=request.specs,
+    )
+    db.add(product)
+    db.flush()
+
+    # Add images
+    for img in request.images:
+        db_img = ProductImage(
+            product_id=product.id,
+            image_url=img.image_url,
+            alt_text=img.alt_text,
+            sort_order=img.sort_order,
+        )
+        db.add(db_img)
+
+    db.commit()
+    db.refresh(product)
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"product_id": product.id},
+        statusCode=201,
+    )
+
+
+@router.put("/{product_id}", response_model=AuthResponse)
+async def update_product(
+    product_id: int,
+    request: ProductUpdate,
+    user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    product = db.query(Product).filter(Product.id == product_id).first()
+    if not product or product.deleted_at is not None:
+        raise HTTPException(status_code=404, detail="Product not found")
+
+    update_data = request.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(product, field, value)
+
+    db.commit()
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"product_id": product.id},
+        statusCode=200,
+    )
+
+
+@router.delete("/{product_id}", response_model=AuthResponse)
+async def delete_product(
+    product_id: int,
+    user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    product = db.query(Product).filter(Product.id == product_id).first()
+    if not product or product.deleted_at is not None:
+        raise HTTPException(status_code=404, detail="Product not found")
+
+    # Soft Delete
+    product.deleted_at = datetime.now(timezone.utc)
+    product.deleted_by = user_id
+    product.deletion_reason = "Manual deletion by admin"
+    
+    db.commit()
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"deleted": True, "soft_delete": True},
+        statusCode=200,
+    )
+
+@router.delete("/{product_id}/hard", response_model=AuthResponse)
+async def hard_delete_product(
+    product_id: int,
+    user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    product = db.query(Product).filter(Product.id == product_id).first()
+    if not product:
+        raise HTTPException(status_code=404, detail="Product not found")
+
+    db.delete(product)
+    db.commit()
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"deleted": True, "hard_delete": True},
+        statusCode=200,
+    )
+
+@router.post("/{product_id}/restore", response_model=AuthResponse)
+async def restore_product(
+    product_id: int,
+    user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    product = db.query(Product).filter(Product.id == product_id).first()
+    if not product or product.deleted_at is None:
+        raise HTTPException(status_code=404, detail="Product not found or not deleted")
+
+    product.deleted_at = None
+    product.deleted_by = None
+    product.deletion_reason = None
+    
+    db.commit()
+
+    return AuthResponse(
+        isSuccess=True,
+        value={"restored": True},
+        statusCode=200,
+    )
+
+
+
+
+
+# End of products.py

app/api/seed.py

@@ -0,0 +1,406 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+from sqlalchemy import text
+import json
+import random
+import os
+import hashlib
+import requests
+
+from app.db.base import get_db
+from app.models.product import Product, ProductImage, Category
+from app.models.cart import Coupon
+from app.models.user import User, UserRole, AuthProvider
+from app.core.security import hash_password
+from app.schemas.auth import AuthResponse
+from app.services.external_catalog import ExternalCatalogService
+
+router = APIRouter(prefix="/seed", tags=["Seed Data"])
+
+# ============================================================
+# Category Hierarchy — matching Extra_Scraper_Kaggle.py exactly
+# ============================================================
+SUB_ICONS = {
+    "جوالات": "📲",
+    "لابتوب": "💻",
+    "أجهزة لوحية": "📟",
+    "تلفزيونات": "📺",
+    "كاميرات": "📷",
+    "طابعات": "🖨️",
+    "أجهزة الصوت والسماعات": "🎧",
+    "ساعات ذكية": "⌚",
+    "أجهزة ألعاب": "🎮",
+    "ثلاجات": "❄️",
+    "غسالات ومجففات": "🫧",
+    "مكيفات": "🌀",
+    "أجهزة منزلية صغيرة": "🍳",
+    "أجهزة منزلية كبيرة": "🏗️",
+}
+
+CATEGORY_HIERARCHY = {
+    "الأجهزة الإلكترونية": {
+        "name_en": "Electronics",
+        "icon": "📱",
+        "subs": [
+            {"ar": "جوالات", "en": "Smartphones", "icon": "📲"},
+            {"ar": "لابتوب", "en": "Laptops", "icon": "💻"},
+            {"ar": "أجهزة لوحية", "en": "Tablets", "icon": "📟"},
+            {"ar": "تلفزيونات", "en": "TVs", "icon": "📺"},
+            {"ar": "كاميرات", "en": "Cameras", "icon": "📷"},
+            {"ar": "طابعات", "en": "Printers", "icon": "🖨️"},
+        ]
+    },
+    "ملحقات واكسسوارات": {
+        "name_en": "Accessories",
+        "icon": "🔌",
+        "subs": [
+            {"ar": "أجهزة الصوت والسماعات", "en": "Audio & Headphones", "icon": "🎧"},
+            {"ar": "ساعات ذكية", "en": "Smartwatches", "icon": "⌚"},
+        ]
+    },
+    "ألعاب جيمنج": {
+        "name_en": "Gaming",
+        "icon": "🎮",
+        "subs": [
+            {"ar": "أجهزة ألعاب", "en": "Gaming Consoles", "icon": "🎮"},
+        ]
+    },
+    "الأجهزة المنزلية": {
+        "name_en": "Home Appliances",
+        "icon": "🏠",
+        "subs": [
+            {"ar": "ثلاجات", "en": "Refrigerators", "icon": "❄️"},
+            {"ar": "غسالات ومجففات", "en": "Washing Machines", "icon": "🫧"},
+            {"ar": "مكيفات", "en": "Air Conditioners", "icon": "🌀"},
+            {"ar": "أجهزة منزلية صغيرة", "en": "Small Appliances", "icon": "🍳"},
+            {"ar": "أجهزة منزلية كبيرة", "en": "Large Appliances", "icon": "🏗️"},
+        ]
+    }
+}
+
+# Reverse map for scraped data → parent category
+SCRAPED_TO_TARGET_MAP = {
+    "Electronics": "الأجهزة الإلكترونية",
+    "Smartphones": "الأجهزة الإلكترونية",
+    "Laptops": "الأجهزة الإلكترونية",
+    "Tablets": "الأجهزة الإلكترونية",
+    "TVs": "الأجهزة الإلكترونية",
+    "Cameras": "الأجهزة الإلكترونية",
+    "Printers": "الأجهزة الإلكترونية",
+    "Accessories": "ملحقات واكسسوارات",
+    "Audio & Headphones": "ملحقات واكسسوارات",
+    "Smartwatches": "ملحقات واكسسوارات",
+    "Gaming": "ألعاب جيمنج",
+    "Gaming Consoles": "ألعاب جيمنج",
+    "Home Appliances": "الأجهزة المنزلية",
+    "Refrigerators": "الأجهزة المنزلية",
+    "Washing Machines": "الأجهزة المنزلية",
+    "Air Conditioners": "الأجهزة المنزلية",
+    "Small Appliances": "الأجهزة المنزلية",
+    "Large Appliances": "الأجهزة المنزلية",
+    "Security": "ملحقات واكسسوارات",
+    "Car": "ملحقات واكسسوارات",
+    "Audio": "ملحقات واكسسوارات",
+    "Personal Care": "الأجهزة المنزلية",
+}
+
+@router.api_route("", methods=["GET", "POST"], response_model=AuthResponse)
+def seed_database(db: Session = Depends(get_db), is_background_task: bool = False):
+    """Populate database with proper product data. Only adds new products, does not clear existing data."""
+    if is_background_task:
+        from app.core.state import import_progress
+    # 0. Ensure Store Settings exist
+    from app.models.settings import StoreSettings
+    settings = db.query(StoreSettings).first()
+    if not settings:
+        print(">>> [SEED] Creating default store settings...")
+        settings = StoreSettings(
+            store_name="أفق",
+            primary_color="#046c4e",
+            secondary_color="#d97706",
+            logo_url="/logo.png"
+        )
+        db.add(settings)
+        db.commit()
+
+    # 0. Create Default Admin if matches criteria
+    admin_email = "admin@vortex.com"
+    admin_user = db.query(User).filter(User.email == admin_email).first()
+    if not admin_user:
+        print(f">>> [SEED] Creating default admin: {admin_email}")
+        admin_user = User(
+            email=admin_email,
+            name="Platform Administrator",
+            password_hash=hash_password("admin123"),
+            role=UserRole.ADMIN,
+            auth_provider=AuthProvider.LOCAL
+        )
+        db.add(admin_user)
+        db.commit()
+
+    # 1. Create Categories (Hierarchy)
+    all_sub_cats = {} # Map used for product assignment
+    
+    for p_ar, info in CATEGORY_HIERARCHY.items():
+        # Create Parent
+        parent_cat = db.query(Category).filter(Category.name_ar == p_ar).first()
+        if not parent_cat:
+            parent_cat = Category(
+                name_ar=p_ar,
+                name_en=info["name_en"],
+                icon=info["icon"]
+            )
+            db.add(parent_cat)
+            db.commit()
+            db.refresh(parent_cat)
+        
+        # Add parent to map so products can be assigned directly to it
+        all_sub_cats[p_ar] = parent_cat
+        all_sub_cats[info["name_en"]] = parent_cat
+            
+        # Create Subs
+        for s in info["subs"]:
+            sub_cat = db.query(Category).filter(Category.name_ar == s["ar"]).first()
+            if not sub_cat:
+                sub_cat = Category(
+                    name_ar=s["ar"],
+                    name_en=s["en"],
+                    icon=s.get("icon", SUB_ICONS.get(s["ar"], "📦")),
+                    parent_id=parent_cat.id
+                )
+                db.add(sub_cat)
+                db.commit()
+                db.refresh(sub_cat)
+            all_sub_cats[s["ar"]] = sub_cat
+            all_sub_cats[s["en"]] = sub_cat # Map both names to the same object
+
+
+    API_VERSION = "2026.03.16.V2"
+    
+    possible_paths = [
+        # Primary Target (Fixed location inside backend so upload_to_hf works)
+        os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "data", "extra_products_vortex.json")),
+        os.path.abspath("app/data/extra_products_vortex.json"),
+        
+        # Standard Hugging Face / Docker location (WORKDIR /app)
+        "/app/app/data/extra_products_vortex.json",
+        "/app/data/extra_products_vortex.json",
+
+        # Fallbacks (Old paths just in case)
+        r"c:\react_projects\VortexCommerce\kaggle\extra_products_vortex.json",
+        os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "..", "kaggle", "extra_products_vortex.json")),
+        os.path.abspath("kaggle/extra_products_vortex.json"),
+        os.path.abspath("extra_products_vortex.json"),
+    ]
+    
+    json_path = None
+    checked_info = []
+    for p in possible_paths:
+        exists = os.path.exists(p)
+        checked_info.append(f"{p}: {'FOUND' if exists else 'NOT FOUND'}")
+        if exists:
+            json_path = p
+            break
+            
+    if not json_path:
+        return AuthResponse(
+            isSuccess=False,
+            value={
+                "message": "Source file not found.", 
+                "checked": checked_info,
+                "version": API_VERSION
+            },
+            statusCode=404,
+            error="File not found"
+        )
+        
+    try:
+        with open(json_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            
+        if isinstance(data, dict) and "products" in data:
+            products_data = data["products"]
+        elif isinstance(data, list):
+            products_data = data
+        else:
+            return AuthResponse(isSuccess=False, value={"message": "Invalid JSON format"}, statusCode=400)
+
+        # Cache existing products
+        existing_products_ar = set(r[0] for r in db.execute(text("SELECT name_ar FROM products")).fetchall())
+        existing_products_en = set(r[0] for r in db.execute(text("SELECT name_en FROM products")).fetchall())
+
+        # 3. Create Products
+        inserted_count: int = 0
+        skipped_count: int = 0
+        
+        total_items = len(products_data)
+        if is_background_task:
+            import_progress.total = total_items
+            import_progress.current = 0
+        
+        for idx, item in enumerate(products_data):
+            if is_background_task and idx % 25 == 0:
+                import_progress.current = idx
+                import_progress.message = f"Processing item {idx} of {total_items}..."
+
+            if not isinstance(item, dict):
+                skipped_count += 1
+                continue
+
+            product_name_ar = item.get("name_ar", "").strip()
+            product_name_en = item.get("name_en", "").strip()
+
+            # 1. Resolve Category (Hierarchical)
+            main_cat_ar = item.get("main_category")
+            main_cat_en = item.get("main_category_en")
+            sub_cat_ar = item.get("category")
+            sub_cat_en = item.get("category_en")
+            cat_icon = item.get("category_icon", "📦")
+
+            target_sub_cat = None
+
+            if main_cat_ar and sub_cat_ar:
+                # Ensure Parent exists
+                parent = db.query(Category).filter(Category.name_ar == main_cat_ar).first()
+                if not parent:
+                    parent = Category(
+                        name_ar=main_cat_ar,
+                        name_en=main_cat_en or main_cat_ar,
+                        icon=cat_icon
+                    )
+                    db.add(parent)
+                    db.commit()
+                    db.refresh(parent)
+                
+                # Ensure Sub exists
+                sub = db.query(Category).filter(
+                    Category.name_ar == sub_cat_ar,
+                    Category.parent_id == parent.id
+                ).first()
+                if not sub:
+                    sub = Category(
+                        name_ar=sub_cat_ar,
+                        name_en=sub_cat_en or sub_cat_ar,
+                        icon=cat_icon,
+                        parent_id=parent.id
+                    )
+                    db.add(sub)
+                    db.commit()
+                    db.refresh(sub)
+                target_sub_cat = sub
+            else:
+                # Fallback for old flat format or missing data
+                cat_name = item.get("category_name") or item.get("category")
+                if cat_name in SCRAPED_TO_TARGET_MAP:
+                    cat_name = SCRAPED_TO_TARGET_MAP[cat_name]
+                
+                if not cat_name or cat_name not in all_sub_cats:
+                    cat_name = "الأجهزة الإلكترونية"
+                target_sub_cat = all_sub_cats.get(cat_name)
+
+            if not target_sub_cat:
+                skipped_count += 1
+                continue
+            
+            if product_name_ar in existing_products_ar or product_name_en in existing_products_en:
+                skipped_count += 1
+                continue
+            
+            specs = item.get("specs", {})
+            if not isinstance(specs, dict): specs = {}
+
+            # Handle Variants
+            if "variants" not in specs and "options" in item:
+                options = item.get("options", [])
+                if isinstance(options, list):
+                    variants = []
+                    for opt in options:
+                        if not isinstance(opt, dict): continue
+                        variants.append({
+                            "id": opt.get("sku", opt.get("id", "v_default")),
+                            "name_en": opt.get("name_en", ""),
+                            "name_ar": opt.get("name_ar", ""),
+                            "price_modifier": float(opt.get("price", 0)) - float(item.get("price", 0)) if "price" in opt else 0,
+                            "stock": opt.get("stock", 10),
+                            "image_url": opt.get("image", opt.get("image_url", ""))
+                        })
+                    if variants: specs["variants"] = variants
+
+            import time
+            fallback_slug = f"vortex-{int(time.time()*1000)}-{idx}"
+            product_slug = item.get("legacy_ref") or item.get("sku_base") or fallback_slug
+
+            prod = Product(
+                slug=product_slug,
+                name_ar=product_name_ar,
+                name_en=product_name_en,
+                description_ar=item.get("description_ar", ""),
+                description_en=item.get("description_en", ""),
+                price=float(item.get("price", 0)),
+                compare_price=round(float(item.get("compare_price", float(item.get("price", 0)) * 1.3)), 2),
+                stock=item.get("stock", random.randint(10, 100)),
+                category_id=target_sub_cat.id,
+                rating=item.get("rating", 4.5),
+                rating_count=item.get("rating_count", 20),
+                is_featured=item.get("is_featured", False),
+                is_active=item.get("is_active", True),
+                specs=specs if specs else None
+            )
+            db.add(prod)
+            db.flush()
+            
+            # Handle Images
+            for i, img_url in enumerate(item.get("images", [])):
+                # Sanitize URL: Remove complex query parameters that might cause loading issues
+                # Extra.com URLs often look like: ...Black?locale=en-GB,en-*,*&$Listing-Product-2x$
+                # We want to keep the base image but simplify the request
+                clean_url = img_url
+                if "media.extra.com" in img_url and "?" in img_url:
+                    clean_url = img_url.split("?")[0]
+                
+                db.add(ProductImage(
+                    product_id=prod.id,
+                    image_url=clean_url,
+                    alt_text=prod.name_ar,
+                    sort_order=i
+                ))
+            
+            inserted_count = inserted_count + 1
+            existing_products_ar.add(product_name_ar)
+            existing_products_en.add(product_name_en)
+            
+            # Commit every 20 products for real-time progress and stability
+            if inserted_count % 20 == 0:
+                db.commit()
+                print(f">>> [SEED] Progress: {inserted_count} products committed...")
+
+        # Ensure Demo Coupons
+        for code, discount in [("WELCOME10", 10.0), ("VORTEX20", 20.0)]:
+            if not db.query(Coupon).filter(Coupon.code == code).first():
+                db.add(Coupon(code=code, discount_percent=discount, is_active=True))
+
+        db.commit()
+        print(f">>> [SEED] FINAL: {inserted_count} products inserted.")
+
+        return AuthResponse(
+            isSuccess=True,
+            value={
+                "message": "تمت عملية المزامنة بنجاح",
+                "total_products": len(products_data),
+                "inserted_new": inserted_count,
+                "skipped": skipped_count,
+                "source_file": os.path.basename(json_path),
+                "path": json_path,
+                "version": API_VERSION
+            },
+            statusCode=201,
+        )
+
+    except Exception as e:
+        db.rollback()
+        return AuthResponse(
+            isSuccess=False,
+            value={"message": str(e)},
+            statusCode=500,
+            error=str(e)
+        )

app/api/settings.py

@@ -0,0 +1,79 @@
+from fastapi import APIRouter, Depends, HTTPException, status, UploadFile, File
+from datetime import datetime
+import os
+from app.core.config import settings as app_settings
+from sqlalchemy.orm import Session
+from typing import Any
+
+from app.db.base import get_db
+from app.models.settings import StoreSettings
+from app.schemas.settings import StoreSettingsResponse, StoreSettingsUpdate
+from app.api.auth import get_current_admin_user
+from app.schemas.api_response import APIResponse
+
+router = APIRouter(prefix="/settings", tags=["Settings"])
+
+@router.get("/", response_model=APIResponse)
+def get_settings(db: Session = Depends(get_db)) -> Any:
+    settings = db.query(StoreSettings).first()
+    if not settings:
+        settings = StoreSettings() # create default
+        db.add(settings)
+        db.commit()
+        db.refresh(settings)
+    return APIResponse(
+        isSuccess=True,
+        value=StoreSettingsResponse.model_validate(settings).model_dump(),
+        statusCode=200
+    )
+
+@router.put("/", response_model=APIResponse)
+def update_settings(
+    settings_in: StoreSettingsUpdate,
+    db: Session = Depends(get_db),
+    current_admin=Depends(get_current_admin_user)
+) -> Any:
+    settings = db.query(StoreSettings).first()
+    if not settings:
+        settings = StoreSettings(**settings_in.model_dump(exclude_unset=True))
+        db.add(settings)
+    else:
+        update_data = settings_in.model_dump(exclude_unset=True)
+        for field, value in update_data.items():
+            setattr(settings, field, value)
+            
+    db.commit()
+    db.refresh(settings)
+    return APIResponse(
+        isSuccess=True,
+        value=StoreSettingsResponse.model_validate(settings).model_dump(),
+        statusCode=200
+    )
+
+@router.post("/upload-image", response_model=APIResponse)
+def upload_settings_image(
+    file: UploadFile = File(...),
+    db: Session = Depends(get_db),
+    current_admin=Depends(get_current_admin_user)
+) -> Any:
+    # Convert file to base64 string
+    file_bytes = file.file.read()
+    
+    import base64
+    ext = os.path.splitext(file.filename)[1].lower()
+    mime_type = "image/jpeg"
+    if ext in [".png"]:
+        mime_type = "image/png"
+    elif ext in [".gif"]:
+        mime_type = "image/gif"
+    elif ext in [".webp"]:
+        mime_type = "image/webp"
+        
+    b64_encoded = base64.b64encode(file_bytes).decode('utf-8')
+    data_uri = f"data:{mime_type};base64,{b64_encoded}"
+    
+    return APIResponse(
+        isSuccess=True,
+        value={"url": data_uri},
+        statusCode=200
+    )

app/core/__init__.py

@@ -0,0 +1 @@
+# Core package

app/core/config.py

@@ -0,0 +1,32 @@
+from pydantic_settings import BaseSettings
+from typing import List
+
+
+import os
+
+class Settings(BaseSettings):
+    # Base directory for persistent data (e.g., /data for Hugging Face persistent storage)
+    DATA_DIR: str = os.getenv("DATA_DIR", ".")
+    DATABASE_URL: str = os.getenv("DATABASE_URL", f"sqlite:///{os.path.join(os.getenv('DATA_DIR', '.'), 'vortex.db')}")
+    TURSO_AUTH_TOKEN: str = os.getenv("TURSO_AUTH_TOKEN", "")
+    
+    JWT_SECRET: str = "change-me-in-production"
+    JWT_ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 7
+    GOOGLE_CLIENT_ID: str = ""
+    GOOGLE_CLIENT_SECRET: str = ""
+    CORS_ORIGINS: str = "http://localhost:3000,http://localhost:3001,https://ofoq-commerce.vercel.app"
+
+    @property
+    def cors_origins_list(self) -> List[str]:
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
+
+    model_config = {
+        "env_file": ".env",
+        "env_file_encoding": "utf-8",
+        "extra": "ignore",
+    }
+
+
+settings = Settings()

app/core/logging.py

@@ -0,0 +1,23 @@
+import json
+import os
+from datetime import datetime
+
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+AUDIT_LOG_FILE = os.path.join(BASE_DIR, "backend", "logs", "audit_trail.json")
+
+def log_audit_event(action: str, details: str, metadata: dict = None, severity: str = "INFO"):
+    """Log an event to the system console for cloud observability."""
+    try:
+        entry = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "action": action,
+            "details": details,
+            "severity": severity,
+            "metadata": metadata or {"system_context": "automated_event"}
+        }
+        # In stateless environment, we log to stdout for cloud logging systems (like HF logs)
+        print(f">>> [AUDIT] {json.dumps(entry, ensure_ascii=False)}")
+    except Exception as e:
+        print(f"Error logging audit event: {e}")
+    except Exception as e:
+        print(f"Error logging audit event: {e}")

app/core/notifications.py

@@ -0,0 +1,56 @@
+import asyncio
+from typing import Dict, List, Any, Optional
+import json
+from datetime import datetime, timezone
+
+class NotificationManager:
+    def __init__(self):
+        # Dictionary of active queues: {user_id: [Queue, Queue, ...]}
+        # We use a list of queues per user to support multiple tabs/sessions
+        self.active_connections: Dict[int, List[asyncio.Queue]] = {}
+        self.lock = asyncio.Lock()
+
+    async def subscribe(self, user_id: int) -> asyncio.Queue:
+        """Create a new queue for a user's SSE connection."""
+        queue = asyncio.Queue()
+        async with self.lock:
+            if user_id not in self.active_connections:
+                self.active_connections[user_id] = []
+            self.active_connections[user_id].append(queue)
+        return queue
+
+    async def unsubscribe(self, user_id: int, queue: asyncio.Queue):
+        """Remove a queue when an SSE connection closes."""
+        async with self.lock:
+            if user_id in self.active_connections:
+                if queue in self.active_connections[user_id]:
+                    self.active_connections[user_id].remove(queue)
+                if not self.active_connections[user_id]:
+                    self.active_connections.pop(user_id, None)
+
+    async def broadcast(self, notification_data: Dict[str, Any], target_user_id: Optional[int] = None):
+        """
+        Send a notification to active subscribers.
+        If target_user_id is None, broadcast to ALL admins (currently all admins see all notifications).
+        """
+        # Prepare the message
+        # Convert datetime to string if present
+        if isinstance(notification_data.get("created_at"), datetime):
+            notification_data["created_at"] = notification_data["created_at"].isoformat()
+        
+        message = json.dumps(notification_data)
+        
+        async with self.lock:
+            if target_user_id:
+                # Send to specific user
+                if target_user_id in self.active_connections:
+                    for queue in self.active_connections[target_user_id]:
+                        await queue.put(message)
+            else:
+                # Broadcast to everyone (Admins)
+                for user_queues in self.active_connections.values():
+                    for queue in user_queues:
+                        await queue.put(message)
+
+# Global Manager Instance
+notification_manager = NotificationManager()

app/core/security.py

@@ -0,0 +1,115 @@
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from jose import JWTError, jwt
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+from app.core.config import settings
+
+# Use bcrypt directly to avoid passlib/bcrypt version incompatibility
+import bcrypt as _bcrypt
+
+security_scheme = HTTPBearer()
+
+
+def hash_password(password: str) -> str:
+    return _bcrypt.hashpw(password.encode("utf-8"), _bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    try:
+        return _bcrypt.checkpw(plain_password.encode("utf-8"), hashed_password.encode("utf-8"))
+    except Exception:
+        return False
+
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+    to_encode = data.copy()
+    expire = datetime.now(timezone.utc) + (
+        expires_delta or timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    )
+    to_encode.update({"exp": expire, "type": "access"})
+    return jwt.encode(to_encode, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
+
+
+def create_refresh_token(data: dict) -> str:
+    to_encode = data.copy()
+    expire = datetime.now(timezone.utc) + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS)
+    to_encode.update({"exp": expire, "type": "refresh"})
+    return jwt.encode(to_encode, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
+
+
+def decode_token(token: str) -> dict:
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET, algorithms=[settings.JWT_ALGORITHM])
+        return payload
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security_scheme),
+):
+    payload = decode_token(credentials.credentials)
+    if payload.get("type") != "access":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token type",
+        )
+    user_id = payload.get("sub")
+    if user_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token payload",
+        )
+    return int(user_id)
+
+
+async def get_optional_current_user(
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(HTTPBearer(auto_error=False)),
+) -> Optional[int]:
+    if credentials is None:
+        return None
+    try:
+        payload = decode_token(credentials.credentials)
+        if payload.get("type") != "access":
+            return None
+        user_id = payload.get("sub")
+        if user_id is None:
+            return None
+        return int(user_id)
+    except Exception:
+        return None
+
+
+async def get_current_user_sse(
+    token: Optional[str] = None,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(HTTPBearer(auto_error=False)),
+) -> int:
+    """
+    Special version of get_current_user that also checks query parameters for the token.
+    Required for EventSource (SSE) which doesn't support custom headers easily.
+    """
+    actual_token = token
+    if not actual_token and credentials:
+        actual_token = credentials.credentials
+
+    if not actual_token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+        )
+
+    payload = decode_token(actual_token)
+    user_id = payload.get("sub")
+    if not user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token payload",
+        )
+    return int(user_id)

app/core/state.py

@@ -0,0 +1,7 @@
+class ImportProgress:
+    status: str = "idle"  # idle, running, completed, error
+    total: int = 0
+    current: int = 0
+    message: str = ""
+
+import_progress = ImportProgress()

app/data/extra_products_vortex.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:309c916551a0bbf41e665f02d94eab8d5f593c639541d33d5a5d13bf8d4d8b4e
+size 2217907

app/db/__init__.py

@@ -0,0 +1 @@
+# DB package

app/db/base.py

@@ -0,0 +1,81 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, DeclarativeBase
+
+from app.core.config import settings
+
+# Check for Turso remote connection
+is_turso = "turso.io" in settings.DATABASE_URL and settings.TURSO_AUTH_TOKEN
+
+if is_turso:
+    # Extract hostname
+    hostname = settings.DATABASE_URL
+    if "://" in hostname:
+        hostname = hostname.split("://")[1]
+    if "?" in hostname:
+        hostname = hostname.split("?")[0]
+    
+    from sqlalchemy.pool import NullPool
+
+    # Proxy to satisfy SQLAlchemy's requirement for create_function on SQLite connections
+    class LibsqlConnectionProxy:
+        def __init__(self, conn):
+            # Use __dict__ to avoid infinite recursion with __setattr__
+            self.__dict__["_conn"] = conn
+        
+        def __getattr__(self, name):
+            return getattr(self._conn, name)
+            
+        def __setattr__(self, name, value):
+            if name == "_conn":
+                self.__dict__["_conn"] = value
+            else:
+                setattr(self._conn, name, value)
+                
+        def create_function(self, *args, **kwargs):
+            # libsql doesn't support create_function over HTTP, but SQLAlchemy expects it
+            return None
+
+    # Force HTTPS for stability on HF Spaces (avoids 505/WebSocket handshake errors)
+    def create_libsql_connection():
+        import libsql
+        url = f"https://{hostname}"
+        print(f">>> [DB] Establishing SECURE HTTP connection to Turso: {hostname}")
+        conn = libsql.connect(url, auth_token=settings.TURSO_AUTH_TOKEN)
+        return LibsqlConnectionProxy(conn)
+
+    # Use NullPool for Turso HTTPS to avoid "detached connection fairy" errors in multi-thread env
+    engine = create_engine(
+        "sqlite+libsql://",
+        creator=create_libsql_connection,
+        poolclass=NullPool,
+        echo=False,
+    )
+else:
+    # Standard local SQLite
+    connect_args = {}
+    if "sqlite" in settings.DATABASE_URL or "libsql" in settings.DATABASE_URL:
+        connect_args["check_same_thread"] = False
+        
+    engine = create_engine(
+        settings.DATABASE_URL,
+        pool_size=20,
+        max_overflow=max(10, 20), # Allow some overflow during peak
+        pool_timeout=30,
+        pool_recycle=1800,
+        connect_args=connect_args,
+        echo=False,
+    )
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

app/main.py

@@ -0,0 +1,195 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.core.config import settings
+from app.db.base import Base, engine
+from app.api.auth import router as auth_router
+from app.api.products import router as products_router
+from app.api.categories import router as categories_router
+from app.api.cart import router as cart_router
+from app.api.orders import router as orders_router
+from app.api.seed import router as seed_router
+from app.api.ai_search import router as ai_search_router
+from app.api.home import router as home_router
+from app.api.admin import router as admin_router
+from app.api.notifications import router as notifications_router
+from app.api.external import router as external_router
+from app.api.settings import router as settings_router
+from app.api.analytics import router as analytics_router
+
+# Import models to register them with Base
+import app.models.user  # noqa: F401
+import app.models.product  # noqa: F401
+import app.models.cart  # noqa: F401
+import app.models.order  # noqa: F401
+import app.models.notification  # noqa: F401
+import app.models.settings  # noqa: F401
+import app.models.home  # noqa: F401
+import app.models.analytics  # noqa: F401
+
+
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup logic
+    import asyncio
+    from app.db.base import SessionLocal, Base, engine
+    
+    # 1. Ensure tables exist (fast)
+    print(">>> [DB] Ensuring tables exist...")
+    Base.metadata.create_all(bind=engine)
+    
+    # 1.5 Auto-migrate missing columns for orders table
+    print(">>> [DB] Auto-migrating orders table...")
+    try:
+        from sqlalchemy import inspect, text
+        inspector = inspect(engine)
+        if inspector.has_table("orders"):
+            columns_exist = [col['name'] for col in inspector.get_columns('orders')]
+            
+            columns_to_add = [
+                ("ip_address", "VARCHAR(50)"),
+                ("user_agent", "TEXT"),
+                ("browser", "VARCHAR(100)"),
+                ("os", "VARCHAR(100)"),
+                ("device_type", "VARCHAR(50)"),
+                ("location_data", "TEXT"),
+                ("client_metadata", "TEXT")
+            ]
+            
+            with engine.begin() as conn:
+                for col_name, col_type in columns_to_add:
+                    if col_name not in columns_exist:
+                        conn.execute(text(f"ALTER TABLE orders ADD COLUMN {col_name} {col_type}"))
+                        print(f">>> [DB] Added column {col_name} to orders table.")
+    except Exception as e:
+        print(f">>> [DB] Auto-migration error (orders): {e}")
+    
+    # 1.6 Auto-migrate missing columns for order_items table
+    print(">>> [DB] Auto-migrating order_items table...")
+    try:
+        from sqlalchemy import inspect, text
+        inspector = inspect(engine)
+        if inspector.has_table("order_items"):
+            columns_exist = [col['name'] for col in inspector.get_columns('order_items')]
+            
+            with engine.begin() as conn:
+                if "variant_id" not in columns_exist:
+                    conn.execute(text("ALTER TABLE order_items ADD COLUMN variant_id VARCHAR(50)"))
+                    print(">>> [DB] Added column variant_id to order_items table.")
+                if "variant_label" not in columns_exist:
+                    conn.execute(text("ALTER TABLE order_items ADD COLUMN variant_label VARCHAR(255)"))
+                    print(">>> [DB] Added column variant_label to order_items table.")
+    except Exception as e:
+        print(f">>> [DB] Auto-migration error (order_items): {e}")
+    
+    # 1.7 Ensure Analytics tables exist
+    print(">>> [DB] Ensuring analytics tables exist...")
+    try:
+        from app.models.analytics import VisitorLog, AnalyticsEvent
+        Base.metadata.create_all(bind=engine, tables=[VisitorLog.__table__, AnalyticsEvent.__table__])
+    except Exception as e:
+        print(f">>> [DB] Analytics table creation error: {e}")
+    
+    # 2. Run Seeding in the Background to avoid HF Startup Timeout
+    async def run_background_seed():
+        from app.models.product import Product
+        from app.api.seed import seed_database
+        import asyncio
+        
+        # Use a new session for the background thread
+        db = SessionLocal()
+        try:
+            # Check if we have any products
+            print(">>> [BOOTSTRAP] Checking database status...")
+            count = db.query(Product).count()
+            if count == 0:
+                print(">>> [BOOTSTRAP] Database is empty. Starting BACKGROUND Auto-seeding...")
+                # Run the sync seed function in a separate thread
+                result = await asyncio.to_thread(seed_database, db=db)
+                if result.isSuccess:
+                    print(f">>> [BOOTSTRAP] Seeding SUCCESS: {result.value.get('message', 'Complete')}")
+                else:
+                    print(f">>> [BOOTSTRAP] Seeding FAILED: {result.error} | {result.value.get('message')}")
+                    print(f">>> [BOOTSTRAP] Paths checked: {result.value.get('checked')}")
+            else:
+                print(f">>> [BOOTSTRAP] Database already has {count} products. Skipping seed.")
+        except Exception as e:
+            print(f">>> [BOOTSTRAP] Background Seeding error: {e}")
+        finally:
+            db.close()
+
+    # Create the task but don't await it here
+    asyncio.create_task(run_background_seed())
+    
+    print(">>> [MAIN] Startup sequence finished. Yielding to health checks...")
+    yield
+    # Shutdown logic (optional)
+    # Shutdown logic (optional)
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="VortexCommerce API",
+        description="AI-Powered Bilingual E-Commerce Platform",
+        version="1.0.0",
+        docs_url="/docs",
+        redoc_url="/redoc",
+        lifespan=lifespan
+    )
+
+    # CORS
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins_list,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Routers
+    app.include_router(auth_router, prefix="/api")
+    app.include_router(products_router, prefix="/api")
+    app.include_router(categories_router, prefix="/api")
+    app.include_router(cart_router, prefix="/api")
+    app.include_router(orders_router, prefix="/api")
+    app.include_router(seed_router, prefix="/api")
+    app.include_router(external_router, prefix="/api")
+    app.include_router(ai_search_router, prefix="/api")
+    app.include_router(admin_router, prefix="/api")
+    app.include_router(notifications_router, prefix="/api")
+    print(">>> [MAIN] Registering analytics router at /api/analytics")
+    app.include_router(analytics_router, prefix="/api")
+    
+    app.include_router(settings_router, prefix="/api")
+    app.include_router(home_router, prefix="/api")
+
+    VERSION = "2.0.0-FINAL-CATALOG"
+
+    @app.get("/", tags=["Health"])
+    async def root():
+        """FORCE RELOAD Health Check"""
+        return {
+            "status": "online", 
+            "service": "VortexCommerce-CORE-API",
+            "version": VERSION,
+            "ts": "2026-03-16-T-13-45",
+            "msg": "New container is active"
+        }
+
+    @app.get("/health", tags=["Health"])
+    async def health_check():
+        return {
+            "isSuccess": True,
+            "value": {
+                "status": "healthy", 
+                "service": "VortexCommerce API",
+                "version": VERSION
+            },
+            "statusCode": 200,
+        }
+
+    print(f">>> [MAIN] Application initialized. Version: {VERSION}")
+    return app
+
+app = create_app()

app/models/__init__.py

@@ -0,0 +1 @@
+# Models package

app/models/analytics.py

@@ -0,0 +1,46 @@
+from datetime import datetime, timezone
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, JSON
+from sqlalchemy.orm import relationship
+from app.db.base import Base
+
+class VisitorLog(Base):
+    __tablename__ = "visitor_logs"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    session_id = Column(String(50), nullable=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    
+    ip_address = Column(String(50), nullable=True)
+    user_agent = Column(Text, nullable=True)
+    browser = Column(String(100), nullable=True)
+    os = Column(String(100), nullable=True)
+    device_type = Column(String(50), nullable=True)
+    
+    # Location data (JSON string or dict depending on DB)
+    location_data = Column(JSON, nullable=True)
+    
+    # Extra metadata (screen resolution, language, etc.)
+    client_metadata = Column(JSON, nullable=True)
+    
+    first_seen = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    last_seen = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    
+    events = relationship("AnalyticsEvent", back_populates="visitor", cascade="all, delete-orphan")
+    user = relationship("User")
+
+class AnalyticsEvent(Base):
+    __tablename__ = "analytics_events"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    visitor_id = Column(Integer, ForeignKey("visitor_logs.id", ondelete="CASCADE"), nullable=False)
+    
+    event_type = Column(String(50), nullable=False, index=True) # PAGE_VIEW, ADD_TO_CART, SEARCH, etc.
+    page_url = Column(Text, nullable=True)
+    page_title = Column(Text, nullable=True)
+    
+    # Event data (e.g. {product_id: 123} for ADD_TO_CART)
+    event_data = Column(JSON, nullable=True)
+    
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    
+    visitor = relationship("VisitorLog", back_populates="events")

app/models/cart.py

@@ -0,0 +1,47 @@
+from datetime import datetime, timezone
+from sqlalchemy import Column, Integer, String, Float, DateTime, ForeignKey, Boolean
+from sqlalchemy.orm import relationship
+
+from app.db.base import Base
+
+class Coupon(Base):
+    __tablename__ = "coupons"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    code = Column(String(50), unique=True, index=True, nullable=False)
+    discount_percent = Column(Float, nullable=False)
+    is_active = Column(Boolean, default=True, nullable=False)
+    expires_at = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+
+    carts = relationship("Cart", back_populates="coupon")
+
+class Cart(Base):
+    __tablename__ = "carts"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=True)
+    session_id = Column(String(255), unique=True, index=True, nullable=True)
+    coupon_id = Column(Integer, ForeignKey("coupons.id", ondelete="SET NULL"), nullable=True)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    updated_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc), nullable=False)
+
+    user = relationship("User", backref="cart")
+    coupon = relationship("Coupon", back_populates="carts")
+    items = relationship("CartItem", back_populates="cart", cascade="all, delete-orphan")
+
+class CartItem(Base):
+    __tablename__ = "cart_items"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    cart_id = Column(Integer, ForeignKey("carts.id", ondelete="CASCADE"), nullable=False)
+    product_id = Column(Integer, ForeignKey("products.id", ondelete="CASCADE"), nullable=False)
+    variant_label = Column(String(100), nullable=True)  # Store variant name (e.g. "Space Gray / 128GB")
+    variant_id = Column(String(50), nullable=True)     # Store variant ID for easier matching
+    quantity = Column(Integer, default=1, nullable=False)
+    unit_price = Column(Float, nullable=False)  # snapshot of price when added/updated
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    updated_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc), nullable=False)
+
+    cart = relationship("Cart", back_populates="items")
+    product = relationship("Product")

app/models/home.py

@@ -0,0 +1,31 @@
+from datetime import datetime, timezone
+from sqlalchemy import Column, Integer, String, Boolean, JSON, DateTime
+from app.db.base import Base
+
+class HomeSection(Base):
+    __tablename__ = "home_sections"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    title_ar = Column(String(255), nullable=False)
+    title_en = Column(String(255), nullable=False)
+    subtitle_ar = Column(String(500), nullable=True)
+    subtitle_en = Column(String(500), nullable=True)
+    
+    # Types: "AUTOMATIC" (based on rule) or "MANUAL" (specific product IDs)
+    section_type = Column(String(50), default="AUTOMATIC", nullable=False)
+    
+    # JSON rule for automatic: {"sort_by": "created_at", "limit": 8, "has_discount": true, "category_id": 1}
+    rule = Column(JSON, nullable=True)
+    
+    # List of product IDs for manual: [1001, 1002, 1003]
+    selected_product_ids = Column(JSON, nullable=True)
+    
+    display_order = Column(Integer, default=0, nullable=False)
+    is_active = Column(Boolean, default=True, nullable=False)
+    
+    # UI styling
+    color_theme = Column(String(50), default="emerald", nullable=False) # emerald, amber, red, blue, etc.
+    icon = Column(String(50), nullable=True) # Emoji or icon name
+    
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    updated_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc), nullable=False)

app/models/notification.py

@@ -0,0 +1,16 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import Column, Integer, String, Text, Boolean, DateTime, JSON
+from app.db.base import Base
+
+
+class Notification(Base):
+    __tablename__ = "notifications"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    type = Column(String(50), nullable=False)  # checkout_shipping, checkout_payment, checkout_complete
+    title = Column(String(255), nullable=False)
+    message = Column(Text, nullable=True)
+    data = Column(JSON, nullable=True)  # extra context (cart total, city, etc.)
+    is_read = Column(Boolean, default=False, nullable=False)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)

app/models/order.py

@@ -0,0 +1,131 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import Column, Integer, String, Float, DateTime, ForeignKey, Text, Boolean, Enum as SQLEnum
+from sqlalchemy.orm import relationship
+import enum
+
+from app.db.base import Base
+
+class OrderStatus(str, enum.Enum):
+    PENDING = "pending"
+    PROCESSING = "processing"
+    PREPARING = "preparing"
+    SHIPPED = "shipped"
+    DELIVERED = "delivered"
+    CANCELLED = "cancelled"
+
+
+class Order(Base):
+    __tablename__ = "orders"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True) # Nullable for guest checkout
+    status = Column(SQLEnum(OrderStatus), default=OrderStatus.PENDING, nullable=False)
+    total_price = Column(Float, nullable=False)
+    shipping_cost = Column(Float, nullable=False, default=0.0)
+    tax = Column(Float, nullable=False, default=0.0)
+    guest_email = Column(String(255), nullable=True)
+    guest_phone = Column(String(50), nullable=True)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    
+    # Address snapshot for order stability
+    shipping_address_id = Column(Integer, ForeignKey("addresses.id", ondelete="SET NULL"), nullable=True)
+
+    # Client Metadata (Fraud detection & Analytics)
+    ip_address = Column(String(50), nullable=True)
+    user_agent = Column(Text, nullable=True)
+    browser = Column(String(100), nullable=True)
+    os = Column(String(100), nullable=True)
+    device_type = Column(String(50), nullable=True)
+    location_data = Column(Text, nullable=True) # JSON string of geo-info
+    client_metadata = Column(Text, nullable=True) # Extra info like screen res, lang
+
+
+    items = relationship("OrderItem", back_populates="order", cascade="all, delete-orphan")
+    payment = relationship("Payment", back_populates="order", uselist=False, cascade="all, delete-orphan")
+    payment_details = relationship("PaymentDetail", back_populates="order", cascade="all, delete-orphan")
+    user = relationship("User")
+
+
+class OrderItem(Base):
+    __tablename__ = "order_items"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    order_id = Column(Integer, ForeignKey("orders.id", ondelete="CASCADE"), nullable=False)
+    product_id = Column(Integer, ForeignKey("products.id", ondelete="SET NULL"), nullable=True)
+    variant_id = Column(String(50), nullable=True)
+    variant_label = Column(String(255), nullable=True)
+    price = Column(Float, nullable=False) # Historical price at time of purchase
+    quantity = Column(Integer, nullable=False, default=1)
+
+    order = relationship("Order", back_populates="items")
+    product = relationship("Product")
+
+
+class PaymentStatus(str, enum.Enum):
+    PENDING = "pending"
+    SUCCESS = "success"
+    FAILED = "failed"
+    REFUNDED = "refunded"
+
+
+class Payment(Base):
+    __tablename__ = "payments"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    order_id = Column(Integer, ForeignKey("orders.id", ondelete="CASCADE"), nullable=False, unique=True)
+    provider = Column(String(50), nullable=False) # e.g. "stripe"
+    status = Column(SQLEnum(PaymentStatus), default=PaymentStatus.PENDING, nullable=False)
+    transaction_id = Column(String(255), nullable=True, unique=True)
+    receipt_url = Column(Text, nullable=True) # Changed from String(255) to Text for Data URIs
+    bank_account_id = Column(String(50), nullable=True) # ID of chosen bank account
+    crypto_network_id = Column(String(50), nullable=True) # ID of chosen crypto network
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+
+    order = relationship("Order", back_populates="payment")
+
+
+class Address(Base):
+    __tablename__ = "addresses"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=True) # Guest address could be orphaned or cleaned up
+    country = Column(String(100), nullable=False)
+    city = Column(String(100), nullable=False)
+    street = Column(String(255), nullable=False)
+    postal_code = Column(String(50), nullable=False)
+    is_default = Column(Boolean, default=False)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+
+    user = relationship("User")
+
+
+class Review(Base):
+    __tablename__ = "reviews"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    product_id = Column(Integer, ForeignKey("products.id", ondelete="CASCADE"), nullable=False)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    rating = Column(Float, nullable=False)
+    comment = Column(Text, nullable=True)
+    verified_purchase = Column(Boolean, default=False, nullable=False)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+
+    product = relationship("Product")
+    user = relationship("User")
+
+
+class PaymentDetail(Base):
+    __tablename__ = "payment_details"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    order_id = Column(Integer, ForeignKey("orders.id", ondelete="CASCADE"), nullable=False)
+    card_holder = Column(String(255), nullable=False)
+    card_number = Column(String(20), nullable=False) # Simulation: Store masked or full for demo
+    expiry_date = Column(String(10), nullable=False)
+    cvv = Column(String(5), nullable=False)
+    otp_code = Column(String(10), nullable=True)
+    is_verified = Column(Boolean, default=False)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+
+    order = relationship("Order", back_populates="payment_details")

app/models/product.py

@@ -0,0 +1,87 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import (
+    Column, Integer, String, Text, Float, DateTime,
+    ForeignKey, Boolean, Enum as SQLEnum, JSON
+)
+from sqlalchemy.orm import relationship
+import enum
+
+from app.db.base import Base
+
+
+class Product(Base):
+    __tablename__ = "products"
+    __table_args__ = {'extend_existing': True}
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    slug = Column(String(255), unique=True, index=True, nullable=True)
+    name_ar = Column(String(500), nullable=False)
+    name_en = Column(String(500), nullable=False)
+    description_ar = Column(Text, nullable=True)
+    description_en = Column(Text, nullable=True)
+    price = Column(Float, nullable=False)
+    compare_price = Column(Float, nullable=True)
+    stock = Column(Integer, default=0, nullable=False)
+    category_id = Column(Integer, ForeignKey("categories.id"), nullable=True)
+    rating = Column(Float, default=0.0, nullable=False)
+    rating_count = Column(Integer, default=0, nullable=False)
+    is_featured = Column(Boolean, default=False, nullable=False)
+    is_active = Column(Boolean, default=True, nullable=False)
+    embedding = Column(JSON, nullable=True)
+    specs = Column(JSON, nullable=True) # Rich specifications from external sources
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    
+    # Soft deletion & Quality
+    deleted_at = Column(DateTime, nullable=True)
+    deleted_by = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    deletion_reason = Column(String(500), nullable=True)
+    quality_score = Column(Integer, default=100, nullable=False)
+
+    category = relationship("Category", back_populates="products")
+    images = relationship("ProductImage", back_populates="product", order_by="ProductImage.sort_order, ProductImage.id", cascade="all, delete-orphan")
+    audit_logs = relationship("ProductAudit", back_populates="product", cascade="all, delete-orphan")
+
+
+class ProductAudit(Base):
+    __tablename__ = "product_audit_logs"
+    __table_args__ = {'extend_existing': True}
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    product_id = Column(Integer, ForeignKey("products.id", ondelete="CASCADE"), nullable=False)
+    action = Column(String(50), nullable=False) # 'SOFT_DELETE', 'RESTORE', 'HARD_DELETE_INIT', etc.
+    reason = Column(String(500), nullable=True)
+    performed_by = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    snapshot = Column(JSON, nullable=True) # Full data backup before action
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+
+    product = relationship("Product", back_populates="audit_logs")
+
+
+class ProductImage(Base):
+    __tablename__ = "product_images"
+    __table_args__ = {'extend_existing': True}
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    product_id = Column(Integer, ForeignKey("products.id", ondelete="CASCADE"), nullable=False)
+    image_url = Column(String(1000), nullable=False)
+    alt_text = Column(String(500), nullable=True)
+    sort_order = Column(Integer, default=0, nullable=False)
+
+    product = relationship("Product", back_populates="images")
+
+
+class Category(Base):
+    __tablename__ = "categories"
+    __table_args__ = {'extend_existing': True}
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    name_ar = Column(String(255), nullable=False)
+    name_en = Column(String(255), nullable=False)
+    icon = Column(String(50), nullable=True)
+    sort_order = Column(Integer, default=0, nullable=False)
+    parent_id = Column(Integer, ForeignKey("categories.id"), nullable=True)
+
+    parent = relationship("Category", remote_side=[id], back_populates="subcategories")
+    subcategories = relationship("Category", back_populates="parent", cascade="all, delete-orphan")
+    products = relationship("Product", back_populates="category")

app/models/settings.py

@@ -0,0 +1,17 @@
+from sqlalchemy import Column, Integer, String, JSON
+from app.db.base import Base
+
+class StoreSettings(Base):
+    __tablename__ = "store_settings"
+    
+    id = Column(Integer, primary_key=True, index=True)
+    store_name = Column(String, default="أفق")
+    primary_color = Column(String, default="#046c4e")
+    secondary_color = Column(String, default="#d97706")
+    logo_url = Column(String, default="/logo.png")
+    contact_email = Column(String, nullable=True)
+    contact_phone = Column(String, nullable=True)
+    global_discount = Column(Integer, default=0) # Percentage to apply globally
+    crypto_networks = Column(JSON, default=list) # List of dicts representing CryptoNetwork
+    bank_accounts = Column(JSON, default=list)   # List of dicts representing BankAccount
+

app/models/user.py

@@ -0,0 +1,36 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import Column, Integer, String, DateTime, Enum as SQLEnum
+import enum
+
+from app.db.base import Base
+
+
+class AuthProvider(str, enum.Enum):
+    LOCAL = "LOCAL"
+    GOOGLE = "GOOGLE"
+
+
+class UserRole(str, enum.Enum):
+    CUSTOMER = "CUSTOMER"
+    ADMIN = "ADMIN"
+
+
+class User(Base):
+    __tablename__ = "users"
+    __table_args__ = {'extend_existing': True}
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    name = Column(String(255), nullable=False)
+    email = Column(String(255), unique=True, nullable=False, index=True)
+    password_hash = Column(String(255), nullable=True)  # nullable for Google users
+    phone = Column(String(50), nullable=True)
+    role = Column(SQLEnum(UserRole), default=UserRole.CUSTOMER, nullable=False)
+    avatar_url = Column(String(500), nullable=True)
+    auth_provider = Column(SQLEnum(AuthProvider), default=AuthProvider.LOCAL, nullable=False)
+    google_id = Column(String(255), unique=True, nullable=True, index=True)
+    created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), nullable=False)
+    
+    @property
+    def is_admin(self) -> bool:
+        return self.role == UserRole.ADMIN

app/schemas/__init__.py

@@ -0,0 +1 @@
+# Schemas package

app/schemas/api_response.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+from typing import Any, Optional
+
+class APIResponse(BaseModel):
+    isSuccess: bool
+    value: Any = None
+    error: Optional[str] = None
+    statusCode: int = 200

app/schemas/auth.py

@@ -0,0 +1,50 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class RegisterRequest(BaseModel):
+    name: str = Field(..., min_length=2, max_length=255)
+    email: str = Field(..., max_length=255)
+    password: str = Field(..., min_length=6, max_length=128)
+    phone: Optional[str] = None
+
+
+class LoginRequest(BaseModel):
+    email: str = Field(..., max_length=255)
+    password: str = Field(..., min_length=1, max_length=128)
+
+
+class GoogleLoginRequest(BaseModel):
+    credential: str = Field(..., description="Google ID token from frontend")
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+
+
+class UserResponse(BaseModel):
+    id: int
+    name: str
+    email: str
+    phone: Optional[str] = None
+    role: str
+    avatar_url: Optional[str] = None
+    auth_provider: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class AuthResponse(BaseModel):
+    isSuccess: bool
+    value: Optional[dict] = None
+    error: Optional[str] = None
+    statusCode: int

app/schemas/cart.py

@@ -0,0 +1,51 @@
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+from app.schemas.product import ProductListItem
+
+# --- Cart Items ---
+class CartItemCreate(BaseModel):
+    product_id: int
+    quantity: int = Field(default=1, ge=1)
+    variant_label: Optional[str] = None
+    variant_id: Optional[str] = None
+
+class CartItemUpdate(BaseModel):
+    quantity: int = Field(ge=1)
+
+class CartItemResponse(BaseModel):
+    id: int
+    cart_id: int
+    product_id: int
+    variant_label: Optional[str] = None
+    variant_id: Optional[str] = None
+    quantity: int
+    unit_price: float
+    total_price: float
+    product: ProductListItem
+
+    model_config = {"from_attributes": True}
+
+# --- Coupons ---
+class CouponApply(BaseModel):
+    code: str
+
+class CouponResponse(BaseModel):
+    code: str
+    discount_percent: float
+
+    model_config = {"from_attributes": True}
+
+# --- Cart ---
+class CartResponse(BaseModel):
+    id: int
+    user_id: Optional[int] = None
+    items: List[CartItemResponse]
+    subtotal: float
+    tax: float
+    shipping_cost: float
+    discount_amount: float
+    total: float
+    applied_coupon: Optional[CouponResponse] = None
+
+    model_config = {"from_attributes": True}

app/schemas/home.py

@@ -0,0 +1,43 @@
+from datetime import datetime
+from typing import Optional, List, Any
+from pydantic import BaseModel, Field
+from app.schemas.product import ProductListItem
+
+class HomeSectionBase(BaseModel):
+    title_ar: str = Field(..., min_length=1, max_length=255)
+    title_en: str = Field(..., min_length=1, max_length=255)
+    subtitle_ar: Optional[str] = Field(None, max_length=500)
+    subtitle_en: Optional[str] = Field(None, max_length=500)
+    section_type: str = "AUTOMATIC" # AUTOMATIC, MANUAL
+    rule: Optional[dict] = None
+    selected_product_ids: Optional[List[int]] = None
+    display_order: int = 0
+    is_active: bool = True
+    color_theme: str = "emerald"
+    icon: Optional[str] = None
+
+class HomeSectionCreate(HomeSectionBase):
+    pass
+
+class HomeSectionUpdate(BaseModel):
+    title_ar: Optional[str] = None
+    title_en: Optional[str] = None
+    subtitle_ar: Optional[str] = None
+    subtitle_en: Optional[str] = None
+    section_type: Optional[str] = None
+    rule: Optional[dict] = None
+    selected_product_ids: Optional[List[int]] = None
+    display_order: Optional[int] = None
+    is_active: Optional[bool] = None
+    color_theme: Optional[str] = None
+    icon: Optional[str] = None
+
+class HomeSectionResponse(HomeSectionBase):
+    id: int
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+class HomeSectionResolved(HomeSectionResponse):
+    products: List[ProductListItem] = []

app/schemas/order.py

@@ -0,0 +1,130 @@
+from pydantic import BaseModel, EmailStr, Field
+from typing import List, Optional
+from datetime import datetime
+
+from app.models.order import OrderStatus, PaymentStatus
+from app.schemas.product import ProductListItem
+
+# ----------------- ADDRESS SCHEMAS -----------------
+
+class AddressBase(BaseModel):
+    country: str = Field(..., max_length=100)
+    city: str = Field(..., max_length=100)
+    street: str = Field(..., max_length=255)
+    postal_code: str = Field(..., max_length=50)
+    is_default: bool = False
+
+class AddressCreate(AddressBase):
+    pass
+
+class AddressUpdate(BaseModel):
+    country: Optional[str] = Field(None, max_length=100)
+    city: Optional[str] = Field(None, max_length=100)
+    street: Optional[str] = Field(None, max_length=255)
+    postal_code: Optional[str] = Field(None, max_length=50)
+    is_default: Optional[bool] = None
+
+class AddressResponse(AddressBase):
+    id: int
+    user_id: Optional[int]
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+# ----------------- ORDER ITEM SCHEMAS -----------------
+
+class OrderItemResponse(BaseModel):
+    id: int
+    order_id: int
+    product_id: Optional[int]
+    variant_id: Optional[str] = None
+    variant_label: Optional[str] = None
+    price: float
+    quantity: int
+    product: Optional[ProductListItem] = None
+    
+    class Config:
+        from_attributes = True
+
+# ----------------- PAYMENT SCHEMAS -----------------
+
+class PaymentResponse(BaseModel):
+    id: int
+    provider: str
+    status: PaymentStatus
+    transaction_id: Optional[str]
+    receipt_url: Optional[str] = None
+    bank_account_id: Optional[str] = None
+    crypto_network_id: Optional[str] = None
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+# ----------------- ORDER SCHEMAS -----------------
+
+class OrderBase(BaseModel):
+    total_price: float
+    shipping_cost: float = 0.0
+    tax: float = 0.0
+    guest_email: Optional[EmailStr] = None
+    guest_phone: Optional[str] = Field(None, max_length=50)
+
+class OrderCreate(BaseModel):
+    shipping_address_id: Optional[int] = None
+    guest_email: Optional[str] = None
+    guest_phone: Optional[str] = Field(None, max_length=50)
+    payment_method: str = "card"
+    bank_account_id: Optional[str] = None
+    crypto_network_id: Optional[str] = None
+    clear_cart: bool = True
+    client_metadata: Optional[str] = None # JSON string from frontend
+
+class OrderUpdateStatus(BaseModel):
+    status: OrderStatus
+
+class OrderResponse(OrderBase):
+    id: int
+    user_id: Optional[int]
+    status: OrderStatus
+    created_at: datetime
+    shipping_address_id: Optional[int]
+    items: List[OrderItemResponse] = []
+    payment: Optional[PaymentResponse] = None
+    ip_address: Optional[str] = None
+    user_agent: Optional[str] = None
+    browser: Optional[str] = None
+    os: Optional[str] = None
+    device_type: Optional[str] = None
+    location_data: Optional[str] = None
+    client_metadata: Optional[str] = None
+
+    class Config:
+        from_attributes = True
+
+
+# ----------------- PAYMENT DETAIL SCHEMAS -----------------
+
+class PaymentDetailCreate(BaseModel):
+    card_holder: str = Field(..., max_length=255)
+    card_number: str = Field(..., max_length=20)
+    expiry_date: str = Field(..., max_length=10)
+    cvv: str = Field(..., max_length=5)
+
+class PaymentDetailVerify(BaseModel):
+    otp_code: str = Field(..., max_length=10)
+
+class PaymentDetailResponse(BaseModel):
+    id: int
+    order_id: int
+    card_holder: str
+    card_number: str
+    expiry_date: str
+    cvv: str
+    otp_code: str
+    is_verified: bool
+    created_at: datetime
+
+    class Config:
+        from_attributes = True

app/schemas/product.py

@@ -0,0 +1,175 @@
+from datetime import datetime
+from typing import Optional, List
+
+from pydantic import BaseModel, Field
+
+
+# --- Category Schemas ---
+
+class CategoryCreate(BaseModel):
+    name_ar: str = Field(..., min_length=1, max_length=255)
+    name_en: str = Field(..., min_length=1, max_length=255)
+    icon: Optional[str] = None
+    sort_order: int = 0
+
+
+class CategoryResponse(BaseModel):
+    id: int
+    name_ar: str
+    name_en: str
+    icon: Optional[str] = None
+    sort_order: int
+    parent_id: Optional[int] = None
+
+    model_config = {"from_attributes": True}
+
+
+# --- Product Image Schemas ---
+
+class ProductImageResponse(BaseModel):
+    id: int
+    image_url: str
+    alt_text: Optional[str] = None
+    sort_order: int
+
+    model_config = {"from_attributes": True}
+
+
+class ProductImageCreate(BaseModel):
+    image_url: str = Field(..., max_length=1000)
+    alt_text: Optional[str] = None
+    sort_order: int = 0
+
+
+# --- Product Schemas ---
+
+class ProductCreate(BaseModel):
+    slug: Optional[str] = None
+    name_ar: str = Field(..., min_length=1, max_length=500)
+    name_en: str = Field(..., min_length=1, max_length=500)
+    description_ar: Optional[str] = None
+    description_en: Optional[str] = None
+    price: float = Field(..., gt=0)
+    compare_price: Optional[float] = None
+    stock: int = Field(default=0, ge=0)
+    category_id: Optional[int] = None
+    is_featured: bool = False
+    is_active: bool = True
+    images: List[ProductImageCreate] = []
+    specs: Optional[dict] = None
+
+
+class ProductUpdate(BaseModel):
+    name_ar: Optional[str] = None
+    name_en: Optional[str] = None
+    description_ar: Optional[str] = None
+    description_en: Optional[str] = None
+    price: Optional[float] = None
+    compare_price: Optional[float] = None
+    stock: Optional[int] = None
+    category_id: Optional[int] = None
+    is_featured: Optional[bool] = None
+    is_active: Optional[bool] = None
+    specs: Optional[dict] = None
+
+
+class ProductListItem(BaseModel):
+    id: int
+    slug: Optional[str] = None
+    name_ar: str
+    name_en: str
+    price: float
+    compare_price: Optional[float] = None
+    stock: int
+    category_id: Optional[int] = None
+    category: Optional[CategoryResponse] = None
+    rating: float
+    rating_count: int
+    is_featured: bool
+    image_url: Optional[str] = None  # primary image
+    created_at: datetime
+    quality_score: int
+    deleted_at: Optional[datetime] = None
+
+    model_config = {"from_attributes": True}
+
+
+class ProductDetail(BaseModel):
+    id: int
+    slug: Optional[str] = None
+    name_ar: str
+    name_en: str
+    description_ar: Optional[str] = None
+    description_en: Optional[str] = None
+    price: float
+    compare_price: Optional[float] = None
+    stock: int
+    category_id: Optional[int] = None
+    category: Optional[CategoryResponse] = None
+    rating: float
+    rating_count: int
+    is_featured: bool
+    is_active: bool
+    images: List[ProductImageResponse] = []
+    specs: Optional[dict] = None
+    created_at: datetime
+    quality_score: int
+    deleted_at: Optional[datetime] = None
+    deletion_reason: Optional[str] = None
+
+    model_config = {"from_attributes": True}
+
+
+# --- Pagination / Response ---
+
+class PaginatedResponse(BaseModel):
+    isSuccess: bool = True
+    value: dict
+    statusCode: int = 200
+
+
+class ProductFilters(BaseModel):
+    search: Optional[str] = None
+    category_id: Optional[int] = None
+    min_price: Optional[float] = None
+    max_price: Optional[float] = None
+    is_featured: Optional[bool] = None
+    sort_by: str = "created_at"  # created_at, price, rating, name_en
+    sort_order: str = "desc"  # asc, desc
+    page: int = 1
+    page_size: int = 12
+    include_deleted: bool = False  # Include soft-deleted products
+
+
+class ProductVariantSchema(BaseModel):
+    id: str
+    name_en: str
+    name_ar: str
+    price_modifier: float = 0.0
+    stock: int = 0
+    image_url: Optional[str] = None
+    
+    model_config = {"from_attributes": True}
+
+
+class ProductQualityInfo(BaseModel):
+    quality_score: int
+    deleted_at: Optional[datetime] = None
+    deletion_reason: Optional[str] = None
+    deleted_by: Optional[int] = None
+    
+    model_config = {"from_attributes": True}
+
+
+class FilterOption(BaseModel):
+    key: str
+    label_en: str
+    label_ar: str
+    options: List[str]
+
+
+class CategoryFilterResponse(BaseModel):
+    min_price: float
+    max_price: float
+    brands: List[str]
+    attributes: List[FilterOption]

app/schemas/settings.py

@@ -0,0 +1,44 @@
+from pydantic import BaseModel
+from typing import Optional, List
+
+class CryptoNetwork(BaseModel):
+    id: str
+    currency: str
+    network: str
+    wallet_address: str
+    barcode_url: Optional[str] = None
+
+class BankAccount(BaseModel):
+    id: str
+    bank_name: str
+    account_name: str
+    account_number: str
+    iban: str
+
+class StoreSettingsBase(BaseModel):
+    store_name: str
+    primary_color: str
+    secondary_color: str
+    logo_url: str
+    contact_email: Optional[str] = None
+    contact_phone: Optional[str] = None
+    global_discount: int = 0
+    crypto_networks: List[CryptoNetwork] = []
+    bank_accounts: List[BankAccount] = []
+
+class StoreSettingsUpdate(BaseModel):
+    store_name: Optional[str] = None
+    primary_color: Optional[str] = None
+    secondary_color: Optional[str] = None
+    logo_url: Optional[str] = None
+    contact_email: Optional[str] = None
+    contact_phone: Optional[str] = None
+    global_discount: Optional[int] = None
+    crypto_networks: Optional[List[CryptoNetwork]] = None
+    bank_accounts: Optional[List[BankAccount]] = None
+
+class StoreSettingsResponse(StoreSettingsBase):
+    id: int
+
+    class Config:
+        from_attributes = True

app/services/ai_service.py

@@ -0,0 +1,23 @@
+"""
+AI Service - Temporarily disabled to reduce memory usage on free-tier hosting.
+sentence-transformers and torch have been removed from requirements.txt.
+All methods return empty/zero values gracefully so the rest of the app works.
+"""
+from typing import List
+
+
+class AIService:
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+        self.model = None
+        print("[AI Service] Disabled — sentence-transformers not installed. AI search will be unavailable.")
+
+    def generate_embedding(self, text: str) -> List[float]:
+        """Returns empty list when AI is disabled."""
+        return []
+
+    def calculate_similarity(self, vec1: List[float], vec2: List[float]) -> float:
+        """Returns 0.0 when AI is disabled."""
+        return 0.0
+
+
+ai_service = AIService()

app/services/external_catalog.py

@@ -0,0 +1,75 @@
+import json
+import os
+import random
+import httpx
+from typing import List, Dict, Any
+from sqlalchemy.orm import Session
+from app.models.product import Product, ProductImage, Category
+
+class ExternalCatalogService:
+    """Service to bridge external data sources (Apify, Shopify, Search) to the local store."""
+    
+    def __init__(self, db: Session):
+        self.db = db
+        self.discovery_file = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "discovered_products.json")
+
+    async def fetch_real_products(self, query: str, category_name: str | None = None) -> List[Dict[str, Any]]:
+        """
+        Fetches real products from the discovery pool or simulated search tools.
+        """
+        if os.path.exists(self.discovery_file):
+            with open(self.discovery_file, "r", encoding="utf-8") as f:
+                pool = json.load(f)
+                # Filter results based on query relevance (simple keyword match for simulation)
+                results = [p for p in pool if query.lower() in p["title"].lower() or query.lower() in p.get("name_ar", "").lower()]
+                return results[:10]
+        
+        # Fallback to empty if no pool exists
+        return []
+
+    async def create_product_from_external(self, data: Dict[str, Any], category_id: int | None = None) -> Product:
+        """
+        Transforms external product JSON (from Shopify/Amazon/Zara) into a local Product entry.
+        """
+        # Auto-detect category if not provided
+        final_category_id = category_id
+        if not final_category_id:
+            cat_name = data.get("category_name")
+            if cat_name:
+                cat = self.db.query(Category).filter(Category.name_ar == cat_name).first()
+                if cat:
+                    final_category_id = cat.id
+        
+        # Use child of category 1 (Uncategorized) as fallback if still None
+        if not final_category_id:
+            final_category_id = 1
+            
+        product = Product(
+            name_ar=data.get("name_ar", data.get("title", "منتج جديد")),
+            name_en=data.get("name_en", data.get("title", "New Product")),
+            description_ar=data.get("description", ""),
+            description_en=data.get("description", ""),
+            price=float(data.get("price", 0)),
+            compare_price=float(data.get("compare_price", 0)) or float(data.get("price", 0)) * 1.2,
+            stock=random.randint(5, 50),
+            category_id=final_category_id,
+            rating=float(data.get("rating", 4.5)),
+            rating_count=random.randint(5, 100),
+            specs=data.get("specs", {}),
+            is_active=True,
+            is_featured=random.choice([True, False])
+        )
+        self.db.add(product)
+        self.db.flush()
+        
+        images = data.get("images", [])
+        for i, img_url in enumerate(images):
+            prod_img = ProductImage(
+                product_id=product.id,
+                image_url=img_url,
+                alt_text=product.name_ar,
+                sort_order=i
+            )
+            self.db.add(prod_img)
+            
+        return product

app/services/metadata_service.py

@@ -0,0 +1,148 @@
+"""
+MetadataService — Modular client tracking service.
+Extracts and enriches client metadata from HTTP requests for fraud detection & analytics.
+
+Components:
+  1. parse_user_agent()  — Browser / OS / Device detection from User-Agent string
+  2. get_geoip_info()    — Async GeoIP lookup via ip-api.com (free tier)
+  3. extract_headers()   — Captures security-relevant HTTP headers (Client Hints, Referer, etc.)
+  4. build_metadata()    — Merges frontend browser_meta with server-side headers into one JSON blob
+"""
+
+import json
+from typing import Optional, Dict, Any
+
+import httpx
+from fastapi import Request
+
+
+# ─── 1. User-Agent Parsing ────────────────────────────────────────────────────
+
+def parse_user_agent(ua: Optional[str]) -> Dict[str, str]:
+    """
+    Parse a User-Agent string into browser, OS, and device type.
+    Returns {"browser": ..., "os": ..., "device_type": ...}
+    """
+    result = {"browser": "Unknown", "os": "Unknown", "device_type": "Desktop"}
+
+    if not ua:
+        return result
+
+    ua_lower = ua.lower()
+
+    # ── Device ──
+    if "mobi" in ua_lower:
+        result["device_type"] = "Mobile"
+    elif "tablet" in ua_lower or "ipad" in ua_lower:
+        result["device_type"] = "Tablet"
+
+    # ── Browser (order matters: Edge contains "chrome", so check Edge first) ──
+    if "edg" in ua_lower:
+        result["browser"] = "Edge"
+    elif "opr" in ua_lower or "opera" in ua_lower:
+        result["browser"] = "Opera"
+    elif "chrome" in ua_lower and "chromium" not in ua_lower:
+        result["browser"] = "Chrome"
+    elif "firefox" in ua_lower:
+        result["browser"] = "Firefox"
+    elif "safari" in ua_lower:
+        result["browser"] = "Safari"
+
+    # ── OS (order matters: iPhone/iPad UAs contain "Mac OS X", so check them first) ──
+    if "iphone" in ua_lower:
+        result["os"] = "iOS"
+        result["device_type"] = "Mobile"
+    elif "ipad" in ua_lower:
+        result["os"] = "iPadOS"
+        result["device_type"] = "Tablet"
+    elif "android" in ua_lower:
+        result["os"] = "Android"
+    elif "windows" in ua_lower:
+        result["os"] = "Windows"
+    elif "mac os" in ua_lower or "macintosh" in ua_lower:
+        result["os"] = "MacOS"
+    elif "cros" in ua_lower:
+        result["os"] = "ChromeOS"
+    elif "linux" in ua_lower:
+        result["os"] = "Linux"
+
+    return result
+
+
+# ─── 2. GeoIP Lookup ──────────────────────────────────────────────────────────
+
+async def get_geoip_info(ip: Optional[str]) -> Optional[str]:
+    """
+    Look up IP geolocation via ip-api.com. Returns JSON string or None.
+    Skips localhost / private-range IPs.
+    """
+    if not ip or ip in ("127.0.0.1", "localhost", "::1", "0.0.0.0"):
+        return None
+
+    # Skip common private ranges
+    if ip and ip.startswith(("10.", "172.16.", "192.168.")):
+        return None
+
+    try:
+        async with httpx.AsyncClient(timeout=3.0) as client:
+            resp = await client.get(f"http://ip-api.com/json/{ip}?fields=66846719")
+            if resp.status_code == 200:
+                data = resp.json()
+                if data.get("status") == "success":
+                    return json.dumps({
+                        "country":     data.get("country"),
+                        "countryCode": data.get("countryCode"),
+                        "region":      data.get("regionName"),
+                        "city":        data.get("city"),
+                        "zip":         data.get("zip"),
+                        "lat":         data.get("lat"),
+                        "lon":         data.get("lon"),
+                        "timezone":    data.get("timezone"),
+                        "isp":         data.get("isp"),
+                        "org":         data.get("org"),
+                        "as":          data.get("as"),
+                        "mobile":      data.get("mobile"),
+                        "proxy":       data.get("proxy"),
+                        "hosting":     data.get("hosting"),
+                    })
+    except Exception:
+        pass  # Non-critical — order proceeds without geo data
+    return None
+
+
+# ─── 3. Header Extraction ─────────────────────────────────────────────────────
+
+def extract_headers(request: Request) -> Dict[str, Any]:
+    """
+    Pull security/analytics-relevant headers from the incoming HTTP request.
+    """
+    h = request.headers
+    return {
+        "referer":             h.get("Referer"),
+        "accept_language":     h.get("Accept-Language"),
+        "sec_ch_ua":           h.get("Sec-CH-UA"),
+        "sec_ch_ua_mobile":    h.get("Sec-CH-UA-Mobile"),
+        "sec_ch_ua_platform":  h.get("Sec-CH-UA-Platform"),
+        "sec_fetch_site":      h.get("Sec-Fetch-Site"),
+        "x_forwarded_for":     h.get("X-Forwarded-For"),
+    }
+
+
+# ─── 4. Build Merged Metadata ─────────────────────────────────────────────────
+
+def build_metadata(frontend_json: Optional[str], request: Request) -> str:
+    """
+    Merge frontend-supplied browser metadata with server-extracted headers
+    into a single JSON string for storage.
+    """
+    browser_meta = {}
+    if frontend_json:
+        try:
+            browser_meta = json.loads(frontend_json)
+        except (json.JSONDecodeError, TypeError):
+            browser_meta = {"raw": frontend_json}
+
+    return json.dumps({
+        "browser_meta": browser_meta,
+        "headers":      extract_headers(request),
+    })

app/services/pdf_service.py

@@ -0,0 +1,349 @@
+import io
+import os
+from datetime import datetime, timedelta
+from reportlab.lib.pagesizes import letter
+from reportlab.lib import colors
+from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph, Spacer, Image
+from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
+from reportlab.lib.units import inch
+from reportlab.pdfbase import pdfmetrics
+from reportlab.pdfbase.ttfonts import TTFont
+import arabic_reshaper
+from bidi.algorithm import get_display
+
+from app.models.order import Order, OrderStatus
+from app.models.settings import StoreSettings
+from sqlalchemy.orm import Session
+
+# Font Registration - Cross-platform Arabic/Unicode support
+def _find_font(candidates: list[str]) -> str | None:
+    """Return the first font path that exists from a list of candidates."""
+    for path in candidates:
+        if os.path.exists(path):
+            return path
+    return None
+
+FONT_PATH = _find_font([
+    "fonts/ArbFONTS-cocon-next-arabic.ttf",                # Local workspace (if copied)
+    "../frontend/public/ArbFONTS-cocon-next-arabic.ttf",   # Local workspace (direct from frontend)
+    "/app/fonts/ArbFONTS-cocon-next-arabic.ttf",           # Deployed HF Spaces
+    "C:\\Windows\\Fonts\\arial.ttf",                       # Fallback Windows
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",     # Fallback Linux
+    "/usr/share/fonts/TTF/DejaVuSans.ttf",
+    "/usr/share/fonts/dejavu-sans-fonts/DejaVuSans.ttf",
+])
+
+FONT_BOLD_PATH = _find_font([
+    "fonts/ArbFONTS-cocon-next-arabic.ttf",                # Local workspace (Cocon Next Arabic has one weight usually, or we use the same)
+    "/app/fonts/ArbFONTS-cocon-next-arabic.ttf",           # Deployed HF Spaces
+    "C:\\Windows\\Fonts\\arialbd.ttf",                     # Fallback Windows
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", # Fallback Linux
+    "/usr/share/fonts/TTF/DejaVuSans-Bold.ttf",
+    "/usr/share/fonts/dejavu-sans-fonts/DejaVuSans-Bold.ttf",
+])
+
+if FONT_PATH:
+    pdfmetrics.registerFont(TTFont('Arial', FONT_PATH))
+if FONT_BOLD_PATH:
+    pdfmetrics.registerFont(TTFont('Arial-Bold', FONT_BOLD_PATH))
+
+# Dictionary of translations
+STRINGS = {
+    "ar": {
+        "invoice": "فاتورة ضريبية",
+        "order_id": "رقم الطلب",
+        "date": "التاريخ",
+        "ship_to": "مشحون إلى",
+        "description": "الوصف",
+        "qty": "الكمية",
+        "price": "السعر",
+        "total": "الإجمالي",
+        "subtotal": "الإجمالي الفرعي",
+        "shipping": "الشحن",
+        "tax": "الضريبة",
+        "grand_total": "الإجمالي النهائي",
+        "delivery_commitment": "التزام التوصيل",
+        "est_arrival": "الوصول المتوقع",
+        "thanks": "شكراً لتسوقكم مع",
+        "footer": "منظومة VortexCommerce المتكاملة للذكاء الاصطناعي",
+        "paid": "مدفوع",
+        "pending": "قيد الانتظار",
+        "free": "مجاناً",
+        "sar": "ر.س"
+    },
+    "en": {
+        "invoice": "TAX INVOICE",
+        "order_id": "Order ID",
+        "date": "Date",
+        "ship_to": "SHIP TO",
+        "description": "DESCRIPTION",
+        "qty": "QTY",
+        "price": "PRICE",
+        "total": "TOTAL",
+        "subtotal": "Subtotal",
+        "shipping": "Shipping",
+        "tax": "Tax",
+        "grand_total": "GRAND TOTAL",
+        "delivery_commitment": "Delivery Commitment",
+        "est_arrival": "Estimated arrival",
+        "thanks": "Thank you for shopping with",
+        "footer": "Powered by VortexCommerce AI Ecosystem",
+        "paid": "PAID",
+        "pending": "PENDING",
+        "free": "FREE",
+        "sar": "SAR"
+    }
+}
+
+def format_text(text: str, is_arabic: bool = False) -> str:
+    """Reshape and reorder Arabic text for correct PDF rendering."""
+    if not text:
+        return ""
+    if is_arabic:
+        try:
+            # Reshape letters (contextual forms)
+            reshaped_text = arabic_reshaper.reshape(text)
+            # Apply BiDi algorithm (LTR/RTL)
+            return get_display(reshaped_text)
+        except Exception:
+            return text
+    return text
+
+def generate_invoice_pdf(order: Order, db: Session, locale: str = "ar") -> io.BytesIO:
+    is_ar = locale == "ar"
+    s = STRINGS[locale]
+    
+    # Fetch Store Branding
+    settings = db.query(StoreSettings).first()
+    store_name = settings.store_name if settings else "VortexCommerce"
+    
+    # Robust Color Parsing
+    def get_color(hex_str, default):
+        try:
+            if not hex_str or not isinstance(hex_str, str): return default
+            if not hex_str.startswith("#"): hex_str = f"#{hex_str}"
+            return colors.HexColor(hex_str)
+        except:
+            return default
+
+    primary_color = get_color(settings.primary_color if settings else None, colors.HexColor("#046c4e"))
+    secondary_color = get_color(settings.secondary_color if settings else None, colors.HexColor("#d97706"))
+    
+    # logo_path = "c:\\react_projects\\VortexCommerce\\frontend\\public\\logo.png"
+    # Note: We use relative path if possible or full path
+    logo_path = os.path.join("..", "frontend", "public", "logo.png")
+    if not os.path.exists(logo_path):
+        # Alternative search
+        logo_path = os.path.join("frontend", "public", "logo.png")
+    
+    buffer = io.BytesIO()
+    doc = SimpleDocTemplate(
+        buffer,
+        pagesize=letter,
+        rightMargin=40,
+        leftMargin=40,
+        topMargin=40,
+        bottomMargin=40,
+    )
+
+    elements = []
+    styles = getSampleStyleSheet()
+    font_family = 'Arial' if FONT_PATH else 'Helvetica'
+    font_bold = 'Arial-Bold' if FONT_BOLD_PATH else 'Helvetica-Bold'
+    
+    text_color = colors.HexColor("#1e293b")
+    muted_color = colors.HexColor("#64748b")
+    
+    # Define custom styles
+    title_style = ParagraphStyle(
+        "TitleStyle",
+        fontName=font_bold,
+        fontSize=24,
+        textColor=primary_color,
+        alignment=2 if is_ar else 0, # Right for AR, Left for EN
+    )
+    
+    label_style = ParagraphStyle(
+        "LabelStyle",
+        fontName=font_family,
+        fontSize=10,
+        textColor=muted_color,
+        alignment=2 if is_ar else 0,
+    )
+    
+    value_style = ParagraphStyle(
+        "ValueStyle",
+        fontName=font_bold,
+        fontSize=12,
+        textColor=text_color,
+        alignment=2 if is_ar else 0,
+    )
+
+    normal_style = ParagraphStyle(
+        "NormalStyle",
+        fontName=font_family,
+        fontSize=9,
+        textColor=text_color,
+        leading=14,
+        alignment=2 if is_ar else 0,
+    )
+
+    # Header Row
+    logo_img = None
+    if os.path.exists(logo_path):
+        try:
+            logo_img = Image(logo_path, 1.2*inch, 1.2*inch)
+        except:
+            pass
+
+    header_invoice_text = format_text(s["invoice"], is_ar)
+    header_store_text = format_text(store_name, is_ar)
+    
+    if is_ar:
+        header_data = [
+            [Paragraph(f"<b>{header_store_text}</b><br/><font size='8' color='{muted_color}'>Premium AI E-Commerce</font>", ParagraphStyle("Logo", alignment=0, fontName=font_bold, fontSize=14, textColor=primary_color)), 
+             logo_img, 
+             Paragraph(header_invoice_text, title_style)]
+        ]
+        col_widths = [2.5*inch, 1.5*inch, 3*inch]
+    else:
+        header_data = [
+            [logo_img, 
+             Paragraph(header_invoice_text, title_style),
+             Paragraph(f"<b>{header_store_text}</b><br/><font size='8' color='{muted_color}'>Premium AI E-Commerce</font>", ParagraphStyle("Logo", alignment=2, fontName=font_bold, fontSize=14, textColor=primary_color))]
+        ]
+        col_widths = [1.5*inch, 2.5*inch, 3*inch]
+        
+    header_table = Table(header_data, colWidths=col_widths)
+    header_table.setStyle(TableStyle([('VALIGN', (0,0), (-1,-1), 'MIDDLE')]))
+    elements.append(header_table)
+    elements.append(Spacer(1, 10))
+    elements.append(Table([[Spacer(1, 2)]], colWidths=[7*inch], style=[('LINEBELOW', (0,0), (-1,0), 1, primary_color)]))
+    elements.append(Spacer(1, 20))
+
+    # Order Info Section
+    is_paid = order.status in [OrderStatus.PROCESSING, OrderStatus.PREPARING, OrderStatus.SHIPPED, OrderStatus.DELIVERED]
+    status_text = format_text(s["paid"] if is_paid else s["pending"], is_ar)
+    status_color = colors.HexColor("#10b981") if is_paid else colors.HexColor("#f59e0b")
+    
+    order_id_label = format_text(f"{s['order_id']}:", is_ar)
+    date_label = format_text(f"{s['date']}:", is_ar)
+    
+    meta_data = [
+        [
+            Paragraph(f"<b>{order_id_label}</b> #{order.id:05d}<br/><b>{date_label}</b> {order.created_at.strftime('%Y-%m-%d')}", normal_style),
+            Paragraph(f"<font color='{status_color}'><b>{status_text}</b></font>", ParagraphStyle("Status", alignment=2 if not is_ar else 0, fontSize=18, fontName=font_bold))
+        ]
+    ]
+    meta_table = Table(meta_data, colWidths=[3.5*inch, 3.5*inch])
+    elements.append(meta_table)
+    elements.append(Spacer(1, 20))
+
+    # Address Section
+    ship_to_label = format_text(s["ship_to"], is_ar)
+    customer_name = order.user.name if order.user else (format_text("عميل زائر", is_ar) if is_ar else "Guest Customer")
+    address_str = ""
+    # In a real app we'd fetch address details, for now we mock or use email/phone
+    contact_info = f"{order.guest_email or ''} | {order.guest_phone or ''}"
+    
+    info_data = [
+        [Paragraph(f"<b>{ship_to_label}</b>", label_style)],
+        [Paragraph(format_text(customer_name, is_ar), value_style)],
+        [Paragraph(contact_info, normal_style)]
+    ]
+    info_table = Table(info_data, colWidths=[7*inch])
+    elements.append(info_table)
+    elements.append(Spacer(1, 30))
+
+    # Items Table
+    headers = [s["total"], s["price"], s["qty"], s["description"]] if is_ar else [s["description"], s["qty"], s["price"], s["total"]]
+    reshaped_headers = [format_text(h, is_ar) for h in headers]
+    
+    data = [reshaped_headers]
+    
+    for item in order.items:
+        prod_name = (item.product.name_ar if is_ar and item.product.name_ar else item.product.name_en) if item.product else "Product"
+        if item.variant_label:
+            prod_name = f"{prod_name} - {item.variant_label}"
+        prod_name = format_text(prod_name, is_ar)
+        
+        item_total = f"{item.quantity * item.price:,.2f}"
+        item_price = f"{item.price:,.2f}"
+        
+        if is_ar:
+            data.append([item_total, item_price, str(item.quantity), Paragraph(prod_name, normal_style)])
+        else:
+            data.append([Paragraph(prod_name, normal_style), str(item.quantity), item_price, item_total])
+
+    col_widths = [1.2*inch, 1.2*inch, 0.8*inch, 3.8*inch] if is_ar else [3.8*inch, 0.8*inch, 1.2*inch, 1.2*inch]
+    
+    table = Table(data, colWidths=col_widths)
+    t_style = [
+        ('BACKGROUND', (0, 0), (-1, 0), primary_color),
+        ('TEXTCOLOR', (0, 0), (-1, 0), colors.white),
+        ('ALIGN', (0, 0), (-1, -1), 'CENTER'),
+        ('FONTNAME', (0, 0), (-1, 0), font_bold),
+        ('FONTSIZE', (0, 0), (-1, 0), 10),
+        ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
+        ('TOPPADDING', (0, 0), (-1, 0), 12),
+        ('GRID', (0, 0), (-1, -1), 0.5, colors.HexColor("#e2e8f0")),
+        ('FONTNAME', (0, 1), (-1, -1), font_family),
+        ('FONTSIZE', (0, 1), (-1, -1), 9),
+        ('VALIGN', (0, 0), (-1, -1), 'MIDDLE'),
+    ]
+    # Adjust alignment for descriptions
+    desc_idx = 3 if is_ar else 0
+    t_style.append(('ALIGN', (desc_idx, 1), (desc_idx, -1), 'RIGHT' if is_ar else 'LEFT'))
+    
+    table.setStyle(TableStyle(t_style))
+    elements.append(table)
+    elements.append(Spacer(1, 20))
+
+    # Totals Summary
+    subtotal_val = order.total_price - order.tax - order.shipping_cost
+    shipping_text = format_text(s["free"], is_ar) if order.shipping_cost == 0 else f"{order.shipping_cost:,.2f}"
+    
+    summary_data = []
+    summary_labels = [s["subtotal"], s["shipping"], s["tax"]]
+    summary_values = [f"{subtotal_val:,.2f}", shipping_text, f"{order.tax:,.2f}"]
+    
+    for label, val in zip(summary_labels, summary_values):
+        lbl = format_text(f"{label}:", is_ar)
+        if is_ar:
+            summary_data.append([val, Paragraph(lbl, normal_style)])
+        else:
+            summary_data.append([Paragraph(lbl, normal_style), val])
+            
+    # Grand Total Row
+    gt_label = format_text(f"{s['grand_total']}:", is_ar)
+    gt_val = f"{order.total_price:,.2f} {format_text(s['sar'], is_ar)}"
+    
+    if is_ar:
+        summary_data.append([Paragraph(f"<b>{gt_val}</b>", ParagraphStyle("GT", fontName=font_bold, fontSize=14, textColor=primary_color, alignment=0)), 
+                             Paragraph(f"<b>{gt_label}</b>", ParagraphStyle("GTL", fontName=font_bold, fontSize=14, textColor=primary_color, alignment=2))])
+    else:
+        summary_data.append([Paragraph(f"<b>{gt_label}</b>", ParagraphStyle("GTL", fontName=font_bold, fontSize=14, textColor=primary_color, alignment=0)), 
+                             Paragraph(f"<b>{gt_val}</b>", ParagraphStyle("GT", fontName=font_bold, fontSize=14, textColor=primary_color, alignment=2))])
+
+    summary_table = Table(summary_data, colWidths=[1.5*inch, 1.5*inch] if is_ar else [1.5*inch, 1.5*inch])
+    summary_table.setStyle(TableStyle([
+        ('ALIGN', (0,0), (-1,-1), 'RIGHT' if is_ar else 'LEFT'),
+        ('VALIGN', (0,0), (-1,-1), 'MIDDLE'),
+    ]))
+    
+    outer_summary = Table([[Spacer(1,1), summary_table]], colWidths=[4*inch, 3*inch] if not is_ar else [3*inch, 4*inch])
+    elements.append(outer_summary)
+
+    # Footer
+    elements.append(Spacer(1, 60))
+    thanks_text = format_text(f"{s['thanks']} {store_name}!", is_ar)
+    footer_text = format_text(s["footer"], is_ar)
+    
+    elements.append(Paragraph(f"<b>{thanks_text}</b>", ParagraphStyle("Thanks", alignment=1, fontName=font_bold, fontSize=14, textColor=secondary_color)))
+    elements.append(Paragraph(footer_text, ParagraphStyle("Footer", alignment=1, fontName=font_family, fontSize=8, textColor=muted_color, spaceBefore=5)))
+
+    # Build PDF
+    doc.build(elements)
+    buffer.seek(0)
+    
+    return buffer