A Kubernetes-native platform for provisioning and managing isolated e-commerce stores on demand. Supports WooCommerce (WordPress + MariaDB) and MedusaJS (Node.js + PostgreSQL) engines.

Note: The live demo is hosted on AWS EC2. If the URL is inactive or you need admin credentials, please reach out to the repository owner via email or open a GitHub Issue. The instance may be stopped periodically to manage AWS hosting costs and will be brought back online promptly upon request.

Security: Demo credentials are not published in this repository. Contact the project owner for access.

• Multi-engine support: WooCommerce and MedusaJS
• Namespace-per-store isolation: Each store runs in its own Kubernetes namespace
• Automated provisioning: Helm-based deployment with engine-conditional rendering
• Lifecycle management: State machine for store lifecycle (requested → provisioning → ready → failed/deleted)
• Tenant isolation: JWT-based authentication with role-based access control (admin/tenant)
• Audit logging: Full event history for every store
• Automated setup: Post-provisioning configuration via kubectl exec (WP-CLI for WooCommerce, Medusa CLI for MedusaJS)
• WooCommerce storefront: Theme selection (Astra / Storefront), seeded products, Cash-on-Delivery checkout, end-to-end order flow
• MedusaJS storefront SPA: Standalone React + Vite + Tailwind CSS storefront consuming Medusa Store API v1 — hero, product catalog, cart drawer, 3-step checkout, order confirmation
• Per-tenant branding: Storefronts are configurable per tenant via environment variables (VITE_STORE_NAME, VITE_MEDUSA_BACKEND_URL)

This section demonstrates the Multi-Tenant E-commerce Provisioning Platform in action — including the control plane dashboard, tenant workflows, WooCommerce engine, MedusaJS engine, and full end-to-end order flow.

All screenshots are taken from a live Kubernetes-backed environment with real provisioning, namespace isolation, Helm deployments, and automated engine setup enabled.

Provisioned via Helm with WordPress 6.7, WooCommerce 9.5, MariaDB 11.4, namespace isolation, and automated WP-CLI setup.

Provisioned with Medusa v1.20, PostgreSQL 16, and optional React storefront deployment.

See SYSTEM_DESIGN.md for a detailed write-up covering:

• Architecture choices and rationale (why Express + Helm + namespace-per-store)
• Idempotency, failure handling, and cleanup strategies
• State machine design with optimistic locking
• Circuit breaker and retry-with-backoff patterns
• Production changes required (DNS, TLS, storage, secrets, monitoring)
• Known tradeoffs and accepted limitations

┌─────────────────────────────────────────────────────────────────┐
│                      User-Facing Layer                          │
│                                                                 │
│              ┌─────────────────────────┐                        │
│              │   React Dashboard       │                        │
│              │   (frontend/ . :5173)   │                        │
│              │                         │                        │
│              │  Store CRUD, audit logs │                        │
│              │  user auth, monitoring  │                        │
│              │                         │                        │
│              └───────────┬─────────────┘                        │
│                          │ REST API (JWT)                       │
└──────────────────────────┼──────────────────────────────────────┘
                           │
┌──────────────────────────▼────────────────────┐
│       Node.js Control Plane (Backend)/ :3001  │
│       Express · PostgreSQL · Helm CLI         │
│   ┌──────────────────────────────────────┐    │
│   │ Provisioner · Helm · K8s · Setup     │    │
│   │ State Machine · Audit · Guardrails   │    │
│   │ Circuit Breaker · Retry · Metrics    │    │
│   └──────────────────────────────────────┘    │
│                                               │
└───────────────┬───────────────────────────────┘
                │ kubectl / helm CLI
┌───────────────▼──────────────────────────────────────────────────────────┐
│                        Kubernetes Cluster                                │
│                                                                          │
│   ┌──────────────────────────────────────────────────────────────┐       │
│   │ Namespace: store-abc12345 (WooCommerce)                      │       │
│   │                                                              │       │
│   │  ┌──────────────────┐  ┌────────────────────┐                │       │
│   │  │  WordPress Pod   │  │  MariaDB           │                │       │
│   │  │  WP 6.7 + PHP8.2 │  │  StatefulSet + PVC │                │       │
│   │  │  WooCommerce 9.5 │  │  MariaDB 11.4      │                │       │
│   │  │  Theme: Astra /  │  └────────────────────┘                │       │
│   │  │   Storefront     │                                        │       │
│   │  │  Products + COD  │  Ingress: store-abc12345.localhost     │       │
│   │  └──────────────────┘                                        │       │
│   └──────────────────────────────────────────────────────────────┘       │
│                                                                          │
│   ┌──────────────────────────────────────────────────────────────┐       │
│   │ Namespace: store-xyz98765 (MedusaJS)                         │       │
│   │                                                              │       │
│   │  ┌──────────────────┐  ┌────────────────────┐                │       │
│   │  │  Medusa Pod      │  │  PostgreSQL        │                │       │
│   │  │  v1.20 + Node.js │  │  StatefulSet + PVC │                │       │
│   │  │  Store API v1    │  │  PG 16 Alpine      │                │       │
│   │  └──────────────────┘  └────────────────────┘                │       │
│   │                                                              │       │
│   │  ┌──────────────────┐  Ingress: store-xyz98765.localhost     │       │
│   │  │  Storefront Pod  │  (opt-in, storefront.enabled=true)     │       │
│   │  │  nginx + SPA     │                                        │       │
│   │  └──────────────────┘                                        │       │
│   └──────────────────────────────────────────────────────────────┘       │
│                                                                          │
│   Per-namespace: NetworkPolicy · ResourceQuota · LimitRange              │
└──────────────────────────────────────────────────────────────────────────┘

.
├── SYSTEM_DESIGN.md           # Architecture decisions & tradeoffs
├── docker-compose.dev.yml     # Local PostgreSQL for development
├── backend/                   # Node.js control plane
│   ├── src/
│   │   ├── controllers/       # HTTP route handlers (auth, stores)
│   │   ├── services/          # Business logic
│   │   │   ├── provisionerService.js   # Store lifecycle orchestrator
│   │   │   ├── helmService.js          # Helm CLI wrapper
│   │   │   ├── kubernetesService.js    # K8s namespace/pod management
│   │   │   ├── storeSetupService.js    # WP-CLI / Medusa post-install setup
│   │   │   ├── ingressService.js       # Auto port-forward & hosts file management
│   │   │   ├── auditService.js         # Event audit trail
│   │   │   └── storeRegistry.js        # PostgreSQL store CRUD
│   │   ├── middleware/        # Auth, validation, error handling, rate limiting
│   │   ├── models/            # Store state machine (storeMachine.js)
│   │   ├── db/                # PostgreSQL pool, migrations, seed
│   │   └── utils/             # Logger, circuit breaker, retry, semaphore, metrics, errors
│   ├── tests/                 # Unit + integration tests (Jest)
│   ├── Dockerfile
│   └── package.json
├── frontend/                  # React admin dashboard (port 5173)
│   ├── src/
│   │   ├── pages/             # CreateStore, StoreList, StoreDetail, Login, etc.
│   │   ├── components/ui/     # UI components (shadcn/ui)
│   │   ├── context/           # AuthContext (JWT)
│   │   ├── layouts/           # AuthLayout, DashboardLayout
│   │   └── services/          # API client (axios)
│   ├── Dockerfile
│   └── package.json
├── storefront-medusa/         # MedusaJS storefront SPA (port 3000)
│   ├── src/
│   │   ├── api/               # Medusa Store API v1 client (pure fetch)
│   │   ├── components/
│   │   │   ├── layout/        # Navbar, Footer, CartDrawer, StoreLayout
│   │   │   ├── home/          # Hero, FeaturedProducts, CategoryGrid, PromoBar
│   │   │   └── products/      # ProductCard, ProductGrid, ProductFilter
│   │   ├── context/           # CartContext (localStorage), StoreContext
│   │   ├── pages/             # Home, Products, ProductDetail, Checkout,
│   │   │                      #   OrderConfirmation, Collections
│   │   └── lib/               # Utility helpers (formatPrice, cn, etc.)
│   ├── Dockerfile             # Multi-stage (node build → nginx serve)
│   └── package.json
├── docker/
│   └── medusa/                # Custom Medusa backend Docker image
├── helm/
│   └── ecommerce-store/       # Unified Helm chart
│       ├── templates/
│       │   ├── woocommerce/   # WordPress Deployment, MariaDB StatefulSet, Ingress
│       │   ├── medusa/        # Medusa Deployment, PostgreSQL StatefulSet,
│       │   │                  #   Storefront Deployment/Service (opt-in), Ingress
│       │   ├── network-policy.yaml
│       │   ├── resource-quota.yaml
│       │   └── limit-range.yaml
│       ├── values.yaml        # Defaults
│       ├── values-local.yaml  # Docker Desktop overrides
│       └── values-vps.yaml    # K3s production overrides
├── scripts/
│   ├── verify-deployment.sh   # Deployment verification checklist
│   └── helm-upgrade.sh        # Helm upgrade/rollback helper
└── .github/
    └── workflows/
        └── ci.yml             # GitHub Actions CI pipeline

• Docker Desktop (with Kubernetes enabled) or k3s/k3d
• kubectl (v1.28+)
• Helm (v3.16+)
• Node.js (v20+)
• PostgreSQL (v16+ for the control plane)

# From the project root — starts PostgreSQL 16 on port 5433
docker compose -f docker-compose.dev.yml up -d

cd backend
npm install

# Copy the example env file and adjust if needed
cp .env.example .env
# Default .env.example already contains the correct DATABASE_URL:
#   DATABASE_URL=postgresql://mtec:mtec_secret@localhost:5433/mtec_control_plane

# Run database migrations
npm run db:migrate

# Seed the admin user
npm run db:seed

# Start the backend
npm run dev          # Runs on http://localhost:3001

cd frontend
npm install
npm run dev          # Runs on http://localhost:5173

The Vite dev server proxies /api requests to the backend automatically.

Open Docker Desktop → Settings → Kubernetes → Enable Kubernetes and wait for the cluster to start. Then install NGINX Ingress:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml

1. Open http://localhost:5173 and register a new account (the first user becomes admin)
2. Click "Create Store"
3. Choose an engine (WooCommerce or MedusaJS)
4. Enter a store name and submit
5. The dashboard shows provisioning progress in real time
6. Once the status reaches ready, click the store to see its details and URLs

After the store reaches ready status the automated setup has already installed WooCommerce, the Storefront theme, configured Cash-on-Delivery (COD) payment, and created a Sample Product ($19.99).

1. Open the store URL shown on the dashboard (e.g. http://store-<id>.localhost:8080)
2. Browse the shop — you will see the "Sample Product"
3. Click Add to Cart → View Cart → Proceed to Checkout
4. Fill in billing details (any dummy data) and choose Cash on Delivery
5. Click Place Order — you will see an order confirmation with an order number
6. To verify in the admin panel, visit http://store-<id>.localhost:8080/wp-admin and go to WooCommerce → Orders

MedusaJS stores: The admin panel is available at port 9000 (/app). Use the admin credentials shown in the store detail page to log in, create products, and manage orders through the Medusa admin UI.

MedusaJS Storefront SPA: A standalone React storefront is available in storefront-medusa/. It consumes the Medusa Store API v1 and can be deployed alongside any Medusa store. See the Storefront section below for details.

1. Navigate to the store detail page on the dashboard
2. Click "Delete Store" and confirm
3. The platform tears down the Kubernetes namespace, Helm release, and all associated resources

The project includes a full CI/CD pipeline powered by GitHub Actions. Every push and pull request triggers automated validation; merges to main automatically deploy to the production EC2 instance.

Deploy only runs on pushes to main after all CI jobs pass. It uses appleboy/ssh-action with secrets (EC2_HOST, EC2_SSH_KEY) — no credentials are stored in code.

push / PR → Backend lint+test ──┐
            Frontend lint+build ─┤
            Helm chart lint ─────┤── all pass ──► Deploy to EC2 (main only)
            Docker build ────────┘

• .github/workflows/ci.yml

# Backend
cd backend
npm ci
npm run lint
npm run test:unit
npm run test:integration  # Requires PostgreSQL running

# Frontend
cd frontend
npm ci
npm run lint
npm run build

# Helm
helm lint helm/ecommerce-store
helm template test-woo helm/ecommerce-store --set engine=woocommerce --set storeId=test-woo
helm template test-medusa helm/ecommerce-store --set engine=medusa --set storeId=test-medusa

# Docker
docker build -t backend:local ./backend
docker build -t frontend:local ./frontend

# Backend unit tests
cd backend
npm run test:unit

# Backend integration tests (requires PostgreSQL)
npm run test:integration

# Run all tests
npm test

# Enable Kubernetes in Docker Desktop → Settings → Kubernetes
# Install NGINX Ingress Controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml

# The backend auto-starts a kubectl port-forward on port 8080 (configurable via INGRESS_PORT)
# Stores will be accessible at http://store-<id>.localhost:8080
# The backend uses values-local.yaml automatically (HELM_VALUES_FILE=values-local.yaml)

Docker Desktop Note: On Docker Desktop, the NGINX Ingress controller's LoadBalancer cannot bind to port 80 due to WSL2 networking. The backend automatically manages a kubectl port-forward to the ingress controller on port 8080 (configurable via INGRESS_PORT). All store URLs include the port automatically. This is handled transparently — no manual steps required.

# 1. Install k3s (comes with Traefik ingress & local-path storage)
curl -sfL https://get.k3s.io | sh -
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

# 2. Install cert-manager for automatic TLS certificates
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

# 3. Create a ClusterIssuer for Let's Encrypt
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: you@yourdomain.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - http01:
          ingress:
            class: traefik
EOF

# 4. Clone the repo and install backend dependencies
git clone https://github.com/abhimh33/Multi-Tenant_Ecommerce_Store.git
cd Multi-Tenant_Ecommerce_Store/backend
npm ci --production

# 5. Install PostgreSQL (or use a managed service)
sudo apt-get install -y postgresql-16
sudo -u postgres createuser mtec --pwprompt
sudo -u postgres createdb mtec_control_plane --owner=mtec

# 6. Configure the backend
cat > .env << 'EOF'
PORT=3001
NODE_ENV=production
DATABASE_URL=postgresql://mtec:<password>@localhost:5432/mtec_control_plane
JWT_SECRET=<generate-a-strong-random-secret>
KUBECONFIG=/etc/rancher/k3s/k3s.yaml
HELM_CHART_PATH=../helm/ecommerce-store
HELM_VALUES_FILE=values-vps.yaml
STORE_DOMAIN_SUFFIX=.yourdomain.com
MAX_STORES_PER_USER=5
LOG_LEVEL=info
EOF

# 7. Run migrations and seed the admin user
npm run db:migrate
npm run db:seed

# 8. Start the backend with a process manager
npm install -g pm2
pm2 start src/index.js --name mtec-backend
pm2 save && pm2 startup

# 9. Build and serve the frontend (behind Nginx)
cd ../frontend
npm ci && npm run build
# Copy dist/ to /var/www/mtec-frontend and configure Nginx to serve it
# with a reverse proxy for /api → http://localhost:3001

# 10. Update values-vps.yaml with your domain
#  ingress.hostSuffix: ".yourdomain.com"
#  medusa.image.repository: registry.yourdomain.com/medusa-backend

DNS: Create a wildcard DNS record *.yourdomain.com → <VPS_IP> so that all store subdomains resolve correctly.

All store management endpoints require a JWT token in the Authorization header:

Authorization: Bearer <token>

Every API request is scoped to the authenticated user's JWT. Tenant isolation is enforced at multiple levels:

When a user creates a store via POST /api/v1/stores, the following sequence executes:

  HTTP Request                    Database                  Kubernetes
  ──────────                      ────────                  ──────────
  POST /stores ──────────▶ INSERT store (REQUESTED) ──▶ 202 Accepted
                                    │
                                    ▼ (async)
                           UPDATE → PROVISIONING
                                    │
                                    ├──▶ 1. Create namespace
                                    ├──▶ 2. helm upgrade --install
                                    │      (engine-conditional chart)
                                    ├──▶ 3. Wait for deployment rollout
                                    ├──▶ 4. Wait for pod readiness
                                    ├──▶ 5. Post-install setup
                                    │      WooCommerce: wp core install,
                                    │        WooCommerce activate, theme,
                                    │        product seed, COD payment
                                    │      MedusaJS: medusa user create,
                                    │        seed data, admin dashboard
                                    ├──▶ 6. Extract store URL from Ingress
                                    │
                                    ▼
                           UPDATE → READY (with URL)

Each step is wrapped in retryWithBackoff (3 attempts, exponential delay + jitter) and the global provisioning semaphore (max 3 concurrent operations).

Deleting a store (DELETE /api/v1/stores/:id) removes all Kubernetes resources atomically:

1. Validate ownership (tenant owns the store, or admin)
2. Validate state machine allows deletion (canDelete())
3. Transition to DELETING with optimistic lock
4. Acquire semaphore slot
5. helm uninstall <release> -n <namespace> — idempotent (succeeds even if release doesn't exist)
6. kubectl delete namespace <namespace> — idempotent (succeeds even if namespace doesn't exist)
7. Poll for namespace deletion confirmation
8. Transition to DELETED

If any step fails, the store transitions to FAILED and can be retried or deleted again.

• Duplicate store names: If a store with the same name + owner exists in FAILED state, the existing record is reused (retry path). If it's READY, a ConflictError is returned.
• Duplicate Helm installs: Before running helm install, the provisioner checks helm status — if the release is already deployed, the install is skipped (race condition defense).
• Duplicate deletions: Both helm uninstall and namespace deletion are no-ops on non-existent resources.

Every provisioned namespace gets a ResourceQuota and LimitRange applied by Helm:

ResourceQuota (per-namespace caps):

LimitRange (per-container defaults):

After helm install, the provisioner verifies that both ResourceQuota and LimitRange exist in the namespace and logs a warning if either is missing.

All log entries use Winston with structured JSON format. Every store lifecycle event is tagged with:

• storeId — unique store identifier (correlation across all events)
• engine — woocommerce or medusa
• phase — lifecycle step (namespace_create, helm_install, pod_readiness, engine_setup, etc.)
• correlationId — HTTP requestId that initiated the operation (survives async provisioning)
• durationMs — per-step execution time

Example log output:

{"level":"info","message":"[lifecycle] Step completed: helm_install","storeId":"store-abc12345","engine":"medusa","phase":"helm_install","correlationId":"req-f7e2b3c4","durationMs":8234}

Accessible at GET /api/v1/metrics (requires admin JWT):

Security events are logged to the same audit_logs table as store lifecycle events, visible in the admin audit log page. Events include:

The current architecture is designed for single-instance operation (Docker Desktop / single VPS). Here's the documented path to horizontal scaling:

The backend uses stateless JWT tokens for authentication — no server-side session storage. This means:

• Any API replica can validate any request — the JWT signature is verified using a shared JWT_SECRET environment variable.
• No sticky sessions required — a load balancer can round-robin requests freely across replicas.
• No session store dependency — Redis/Memcached is not needed for auth (only for rate limiting in multi-instance mode).
• Token-based scaling: Deploy N replicas behind a load balancer; set the same JWT_SECRET on all instances.

The Express backend is nearly stateless — scale horizontally behind a load balancer with these considerations:

The provisioning system uses a two-layer concurrency control:

1. Global semaphore (Semaphore class): Limits the total number of parallel Helm installs/deletes to PROVISIONING_MAX_CONCURRENT (default: 3). Excess requests are queued (up to PROVISIONING_MAX_QUEUE=10) and rejected with 503 when the queue is full.
2. Per-store guard (activeOperations Map): Prevents concurrent operations on the same store (e.g., two provisioning attempts for the same store ID).

                    ┌─────────────────────┐
                    │  HTTP Request       │
                    │  POST /stores       │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │  DB: Create record  │
                    │  (REQUESTED state)  │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
          ┌────────│  Semaphore.acquire() │────────┐
          │ Full   │  maxConcurrent=3     │ OK     │
          │        │  maxQueue=10         │        │
          │        └──────────────────────┘        │
          ▼                                        ▼
  ┌───────────────┐                    ┌───────────────────┐
  │  503 Rejected │                    │  provisionAsync() │
  │  Store→FAILED │                    │  namespace → helm │
  └───────────────┘                    │  → pods → setup   │
                                       │  → READY          │
                                       └───────────────────┘

Environment variables:

For multi-instance scaling:

1. DB-level locking: Use PostgreSQL advisory locks (pg_advisory_xact_lock(store_id_hash)) before starting provisioning
2. Optimistic locking (already implemented): The expectedStatus guard ensures only one instance wins the state transition
3. Leader election: For recoverStuckStores(), use a Kubernetes lease or DB-based leader election to ensure only one instance runs recovery on startup

• PostgreSQL supports connection pooling via PgBouncer
• All queries use parameterized queries (no SQL injection risk)
• Schema supports Row-Level Security (RLS) as a future enhancement

Stores are inherently isolated (1 namespace per store). The Kubernetes cluster itself is the scaling boundary — add nodes to support more concurrent stores.

                    ┌─────────────────┐
                    │  Load Balancer  │
                    │  (Nginx/HAProxy)│
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ Backend 1│  │ Backend 2│  │ Backend 3│
        │ (Express)│  │ (Express)│  │ (Express)│
        └────┬─────┘  └────┬─────┘  └────┬─────┘
             │              │              │
        ┌────▼──────────────▼──────────────▼────┐
        │           Redis (shared state)        │
        │  Rate limits, lockouts, cooldowns     │
        └────────────────┬──────────────────────┘
                         │
        ┌────────────────▼───────────────────────┐
        │        PostgreSQL (primary)            │
        │  Stores, audit logs, users             │
        │  Advisory locks for provisioning       │
        └────────────────────────────────────────┘

The Helm chart uses values file separation to support both local development and production VPS deployment without code changes:

Every deviation from the base values.yaml is documented here. The backend selects a values file via the HELM_VALUES_FILE environment variable — no code changes required.

The platform handles secrets at three levels:

1. Control Plane Secrets (Backend .env)

# Generate production JWT secret
export JWT_SECRET=$(openssl rand -base64 48)

2. Per-Store Secrets (Helm Kubernetes Secrets)

Each store gets engine-specific Kubernetes Secrets created by Helm templates:

Production hardening: Override defaults via --set flags during helm install:

helm upgrade --install store-abc ./helm/ecommerce-store \
  --namespace store-abc \
  -f ./helm/ecommerce-store/values-vps.yaml \
  --set storeId=store-abc \
  --set engine=woocommerce \
  --set mariadb.rootPassword=$(openssl rand -base64 24) \
  --set mariadb.password=$(openssl rand -base64 24) \
  --set wordpress.admin.password=$(openssl rand -base64 24)

3. Infrastructure Secrets

Rotation policy: JWT_SECRET rotation requires all active tokens to be re-issued. Store secrets can be rotated by running helm upgrade with new --set values — pods will restart and pick up new Secret mounts.

The platform uses Helm 3's built-in revision tracking for safe upgrades and instant rollbacks of provisioned store releases. Every helm upgrade creates a new revision; rolling back restores the exact previous state.

                    ┌─────────────────────────────┐
                    │  1. Pre-flight              │
                    │  helm lint + template render│
                    └──────────┬──────────────────┘
                               │
                    ┌──────────▼──────────────────┐
                    │  2. Diff Preview (optional) │
                    │  helm diff upgrade          │
                    └──────────┬──────────────────┘
                               │
                    ┌──────────▼──────────────────┐
                    │  3. Upgrade                 │
                    │  helm upgrade --install     │
                    │  --atomic --cleanup-on-fail │
                    │  --wait --timeout 10m       │
                    └──────────┬──────────────────┘
                               │
                    ┌──────────▼──────────────────┐
                    │  4. Post-upgrade Verify     │
                    │  Pod health, PVC, Ingress   │
                    └──────────┬──────────────────┘
                               │
              ┌────────────────┼────────────────┐
              │ PASS                            │ FAIL
              ▼                                 ▼
    ┌──────────────┐                  ┌──────────────────┐
    │  Done ✓      │                  │  helm rollback   │
    │  New revision│                  │  Restore prev.   │
    └──────────────┘                  └──────────────────┘

A helper script is provided at scripts/helm-upgrade.sh:

# 1. Preview what will change (dry-run)
./scripts/helm-upgrade.sh diff store-abc12345 store-abc12345 values-vps.yaml

# 2. Perform the upgrade (with --atomic: auto-rollback on failure)
./scripts/helm-upgrade.sh upgrade store-abc12345 store-abc12345 values-vps.yaml

# 3. Verify the upgrade succeeded
./scripts/helm-upgrade.sh verify store-abc12345 store-abc12345

# 4. If verification fails, roll back immediately
./scripts/helm-upgrade.sh rollback store-abc12345 store-abc12345

# 5. View revision history
./scripts/helm-upgrade.sh history store-abc12345 store-abc12345

# Upgrade a WooCommerce store to new resource limits
helm upgrade store-abc12345 ./helm/ecommerce-store \
  --namespace store-abc12345 \
  -f ./helm/ecommerce-store/values-vps.yaml \
  --set engine=woocommerce \
  --set storeId=store-abc12345 \
  --set wordpress.resources.limits.memory=2Gi \
  --atomic \
  --wait \
  --timeout 10m

# Rollback to the previous revision
helm rollback store-abc12345 0 --namespace store-abc12345 --wait

# Rollback to a specific revision
helm rollback store-abc12345 2 --namespace store-abc12345 --wait

When modifying the Helm chart:

# 1. Update Chart.yaml version (SemVer)
#    Increment patch (1.0.0 → 1.0.1) for fixes
#    Increment minor (1.0.0 → 1.1.0) for new features
#    Increment major (1.0.0 → 2.0.0) for breaking changes

# 2. Validate the chart
helm lint ./helm/ecommerce-store
helm template test ./helm/ecommerce-store \
  --set engine=woocommerce --set storeId=test \
  -f ./helm/ecommerce-store/values-local.yaml --validate

# 3. Upgrade existing stores to new chart version
for NS in $(kubectl get ns -l mt-ecommerce/store-id -o name | cut -d/ -f2); do
  echo "Upgrading $NS..."
  ./scripts/helm-upgrade.sh upgrade "$NS" "$NS" values-vps.yaml
done

After a rollback, confirm these items:

Important: PersistentVolumeClaims are not deleted during rollback. Data in MariaDB and PostgreSQL is preserved across upgrades and rollbacks. Only the Deployment/StatefulSet spec is reverted.

A verification script is provided at scripts/verify-deployment.sh. Run it against any environment:

# Local development
./scripts/verify-deployment.sh

# VPS / production
./scripts/verify-deployment.sh https://api.yourdomain.com

Use this checklist after any deployment or environment change:

# Install and configure pm2
npm install -g pm2

# Start the backend with restart on crash
pm2 start src/index.js --name mtec-backend \
  --max-memory-restart 512M \
  --kill-timeout 20000 \
  --wait-ready \
  --listen-timeout 10000

# Save the process list for auto-start on reboot
pm2 save
pm2 startup   # Generates a systemd service

# View logs
pm2 logs mtec-backend --lines 100

# Zero-downtime restart (if behind a load balancer)
pm2 reload mtec-backend

# /etc/nginx/sites-available/mtec
server {
    listen 80;
    server_name admin.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name admin.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/admin.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/admin.yourdomain.com/privkey.pem;

    # Frontend SPA (React build)
    root /var/www/mtec-frontend/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # API reverse proxy
    location /api/ {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 600s;  # Long timeout for provisioning
    }
}

# Backup control plane database
pg_dump -U mtec mtec_control_plane > backup-$(date +%Y%m%d).sql

# Backup a store's MariaDB (WooCommerce)
kubectl exec -n store-abc $(kubectl get pod -n store-abc -l app.kubernetes.io/name=mariadb -o name) \
  -- mysqldump -u root -p$ROOT_PASSWORD wordpress > store-abc-backup.sql

# Backup a store's PostgreSQL (MedusaJS)
kubectl exec -n store-xyz $(kubectl get pod -n store-xyz -l app.kubernetes.io/name=postgresql -o name) \
  -- pg_dump -U medusa medusa > store-xyz-backup.sql

# Restore control plane
psql -U mtec mtec_control_plane < backup-20260215.sql

In production, pipe Winston JSON logs to a centralized log system:

# pm2 → journald → Promtail/Loki
pm2 start src/index.js --name mtec-backend --log-type json

# Or direct to file for Filebeat/Fluentd ingestion
pm2 start src/index.js --name mtec-backend \
  --output /var/log/mtec/out.log \
  --error /var/log/mtec/err.log \
  --merge-logs

These items are documented and accepted trade-offs for the current scope:

The storefront-medusa/ directory contains a standalone React storefront designed to work with any Medusa v1.x backend. It is fully decoupled from the control plane and communicates exclusively through the Medusa Store API.

cd storefront-medusa
npm install

# Point to a running Medusa backend (default: http://localhost:9000)
cp .env.example .env
# Edit VITE_MEDUSA_BACKEND_URL if needed

npm run dev    # http://localhost:3000
npm run build  # Production build → dist/ (280KB JS + 38KB CSS)

docker build \
  --build-arg VITE_MEDUSA_BACKEND_URL=http://medusa:9000 \
  --build-arg VITE_STORE_NAME="My Store" \
  -t storefront-medusa:latest \
  storefront-medusa/

The Dockerfile uses a multi-stage build: Node.js for the Vite build, then nginx to serve the SPA with API proxy and proper client-side routing fallback.

The storefront can be deployed alongside a Medusa store by enabling it in values.yaml:

storefront:
  enabled: true
  image:
    repository: storefront-medusa
    tag: latest
  storeName: "My Store"

This creates a Deployment + Service for the storefront pod within the same store namespace. The ingress routing (/ → storefront, /store/* → Medusa API) is a planned enhancement.

The platform is deployed on an AWS EC2 m7i-flex.large instance with the following stack:

# 1. SSH into EC2
ssh -i your-key.pem ubuntu@<ELASTIC_IP>

# 2. Install prerequisites
sudo apt update && sudo apt install -y docker.io nodejs npm nginx
curl -sfL https://get.k3s.io | sh -
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

# 3. Install ingress-nginx
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/baremetal/deploy.yaml

# 4. Clone and setup backend
git clone https://github.com/abhimh33/Multi-Tenant_Ecommerce_Store.git
cd Multi-Tenant_Ecommerce_Store/backend
npm ci --production
npm run db:migrate && npm run db:seed
pm2 start src/index.js --name mtec-backend
pm2 save && pm2 startup

# 5. Build and deploy frontend
cd ../frontend && npm ci && npm run build
sudo mkdir -p /var/www/mtec
sudo cp -r dist/* /var/www/mtec/

# 6. Configure Nginx (reverse proxy + wildcard store routing)
# See the Nginx config section below for the full configuration
sudo systemctl restart nginx

# /etc/nginx/sites-available/mtec
server {
    listen 80 default_server;
    server_name <ELASTIC_IP>;

    root /var/www/mtec;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 600s;
    }
}

server {
    listen 80;
    server_name ~^store-.*\.nip\.io$;

    location / {
        proxy_pass http://127.0.0.1:30080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

The platform is architected for extensibility. Below are planned features that would elevate it toward a production-grade SaaS offering:

An AI-driven store creation layer that allows tenants to describe their desired store in natural language. The orchestration engine will:

• Natural Language → Provisioning Config: Parse prompts like "Create a fashion store with WooCommerce and Astra theme" into engine selection, theme choice, and product category seeding
• AI Product Catalog Generation: Auto-generate product titles, descriptions, pricing, and placeholder images using LLM + image generation APIs
• Intelligent Theme Recommendation: Suggest optimal engine + theme combinations based on the tenant's industry and scale requirements
• Conversational Store Management: Enable tenants to manage inventory, pricing, and promotions through a chat interface
• Anomaly Detection: Monitor store health metrics and auto-trigger scaling or alerts using ML-based anomaly detection

The current architecture (state machine, Helm abstraction, multi-engine support, concurrency semaphore) has been designed with this extensibility in mind.

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025-2026 Abdulappa

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Contributions are welcome! Whether it's a bug fix, feature implementation, documentation improvement, or test coverage — every contribution helps make this platform better.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes with conventional commits (git commit -m 'feat: add amazing feature')
4. Push to your branch (git push origin feature/amazing-feature)
5. Open a Pull Request with a clear description of the changes

• Follow the existing code style (ESLint + Prettier configurations are included)
• Write or update tests for any new functionality
• Ensure all CI checks pass before requesting review (npm run lint, npm test, helm lint)
• Use conventional commits for commit messages
• Keep PRs focused — one feature or fix per pull request

Look for issues tagged with good first issue or help wanted to get started.

• New e-commerce engines: Shopify Headless, PrestaShop, Magento integration
• Gen AI orchestration: Natural language store creation, AI product seeding
• Monitoring & Observability: Grafana dashboards, Loki log aggregation
• Multi-cluster support: Federation, geo-distributed deployments
• UI/UX improvements: Dark mode, mobile responsiveness, accessibility
• Documentation: Tutorials, video walkthroughs, API examples

The CI pipeline will automatically validate your changes on every push and pull request.