diff --git a/ROADMAP.md b/ROADMAP.md
index d5075ea..8912295 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -13,10 +13,12 @@ Order is approximate. Each item is sized so the surrounding system remains shipp
- **Bulk recompute task.** Celery beat schedule that walks the catalog in shards, emits suggestions, applies the auto-approve set, queues the rest for review.
- **Webhook ingest.** Inbound `products/update` webhook with HMAC verification (already implemented in `shopify/client.py:verify_webhook`) drives a recompute task for the affected SKU.
- **Rate-limit-aware Shopify client.** Backoff on `X-Shopify-Shop-Api-Call-Limit`. Batch variant updates where possible.
+- **Per-merchant automation suspend.** Emergency-stop flag on the merchant row. Suspended merchants skip the auto-apply path; the audit trail still records manual changes. Complements rollback โ rollback fixes the past, suspend prevents the next move.
## Later
- **Pricing-signal layer.** Replace the toy `demand_signal - inventory_pressure` proposal with something that reads real signals. The guardrail layer is the safety surface โ the proposal is swappable.
- **Per-merchant policy.** Today `MerchantPolicy` is constructed with module defaults. Move to a per-merchant config row.
+- **Asymmetric guardrail caps.** Split `max_change_pct` into `max_increase_pct` and `max_decrease_pct`. Most merchants want prices to fall slower than they rise.
- **A/B price testing.** Treatment / control groups, lift measurement against an audited baseline.
- **Margin-based reporting.** Slice realized margin by SKU, by category, by guardrail-fired rate.
diff --git a/ecom-dynamic-pricing/.env.example b/ecom-dynamic-pricing/.env.example
deleted file mode 100644
index 11e3518..0000000
--- a/ecom-dynamic-pricing/.env.example
+++ /dev/null
@@ -1,28 +0,0 @@
-# FastAPI
-APP_ENV=local
-APP_DEBUG=true
-APP_HOST=0.0.0.0
-APP_PORT=8000
-
-# Database
-POSTGRES_USER=ecom
-POSTGRES_PASSWORD=ecom_password
-POSTGRES_DB=ecom_db
-POSTGRES_HOST=db
-POSTGRES_PORT=5432
-
-# Redis / Celery
-REDIS_URL=redis://redis:6379/0
-
-# Shopify
-SHOPIFY_APP_API_KEY=your_shopify_public_key_here
-SHOPIFY_APP_API_SECRET=your_shopify_api_secret_here
-SHOPIFY_APP_SCOPES=read_products,write_products,read_orders
-SHOPIFY_APP_REDIRECT_URI=https://your-ngrok-or-domain.com/api/shopify/oauth/callback
-
-# App
-JWT_SECRET=super_secret_change_me
-JWT_ALGORITHM=HS256
-
-# Error Monitoring (optional - leave empty to disable)
-SENTRY_DSN=
diff --git a/ecom-dynamic-pricing/.gitignore b/ecom-dynamic-pricing/.gitignore
deleted file mode 100644
index 2e0fe40..0000000
--- a/ecom-dynamic-pricing/.gitignore
+++ /dev/null
@@ -1,54 +0,0 @@
-# Environment variables (contains secrets)
-.env
-
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-env/
-venv/
-ENV/
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# IDEs
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Docker
-docker-compose.override.yml
-
-# Postgres data
-*.sql
-pgdata/
-
-# Logs
-*.log
-logs/
-
-# Testing
-.pytest_cache/
-.coverage
-htmlcov/
diff --git a/ecom-dynamic-pricing/HANDOFF.md b/ecom-dynamic-pricing/HANDOFF.md
deleted file mode 100644
index 02476f6..0000000
--- a/ecom-dynamic-pricing/HANDOFF.md
+++ /dev/null
@@ -1,566 +0,0 @@
-# System Handoff Document
-
-**Date**: 2025-01-13
-**Version**: 1.0.0
-**Status**: Production Ready โ
-
----
-
-## ๐ฏ Executive Summary
-
-This is a **complete, production-ready SaaS platform** for automated Shopify product pricing. It's been built with one goal in mind:
-
-> **"Make the system stable enough that someone else can run it without bothering you."**
-
-### โ What's Complete
-
-| Component | Status | Files | Lines of Code |
-|-----------|--------|-------|---------------|
-| Backend API | โ Complete | 15+ files | ~2,500 LOC |
-| Frontend UI | โ Complete | 20 files | ~1,400 LOC |
-| Database Schema | โ Complete | 3 models | ~150 LOC |
-| Documentation | โ Complete | 4 docs | ~3,500 lines |
-| Docker Setup | โ Complete | 2 files | ~100 LOC |
-| **Total** | **โ Ready** | **50+ files** | **~7,650 LOC** |
-
-### ๐ก Key Achievement
-
-**Zero Hand-Holding Required**
-
-- Merchants understand the system in 5 minutes (MERCHANT_QUICKSTART.md)
-- Operators can diagnose 95% of issues (OPERATOR_RUNBOOK.md)
-- Developers can extend features easily (README.md + inline docs)
-
----
-
-## ๐ฆ What You're Getting
-
-### **1. Backend Infrastructure**
-
-```
-FastAPI + PostgreSQL + Redis + Celery + Docker
-```
-
-**Capabilities:**
-- Shopify OAuth integration
-- Product sync (background jobs)
-- Dynamic pricing engine with guardrails
-- Preview mode (test before applying)
-- Rollback functionality (undo changes)
-- Suspend/resume automation
-- Rate limiting (Shopify API)
-- Retry logic (3 attempts, exponential backoff)
-- Timeout guardrails (no infinite loops)
-- Health checks (Postgres, Redis, Celery)
-- Structured logging
-- Sentry integration (error monitoring)
-
-**Stability Features:**
-- โ Tasks never hang (timeout limits)
-- โ API never crashes (retry logic)
-- โ Logs tell you exactly what happened
-- โ Errors auto-forward to Sentry
-- โ Health checks show system status in real-time
-
-### **2. Frontend Dashboards**
-
-```
-React 18 + TypeScript + Tailwind CSS + Vite
-```
-
-**Merchant Dashboard** (`/merchant`):
-- Control panel (suspend/resume/preview/rollback)
-- Guardrails editor (min/max prices, protection days)
-- Pricing history (full audit trail)
-- Real-time stats
-
-**Operator Panel** (`/operator`):
-- System health monitor
-- Worker status
-- Recent activity across stores
-- Quick actions
-- Runbook reference
-
-### **3. Documentation**
-
-| Document | Purpose | Audience |
-|----------|---------|----------|
-| `README.md` | Complete system overview | Everyone |
-| `MERCHANT_QUICKSTART.md` | 5-minute setup guide | Merchants |
-| `OPERATOR_RUNBOOK.md` | Operations manual | Support team |
-| `frontend/README.md` | Frontend development | Developers |
-| `HANDOFF.md` | This document | New team lead |
-
----
-
-## โ ๏ธ Before You Start
-
-**Read [TECHNICAL_DEBT.md](./TECHNICAL_DEBT.md) end-to-end. Treat it as the primary backlog for hardening.**
-
-This document gives you complete transparency on all known gaps, workarounds, and the prioritized remediation plan. No surprises.
-
----
-
-## ๐ Quick Start for New Owner
-
-### **Day 1: Get It Running (30 minutes)**
-
-```bash
-# 1. Clone repo
-git clone https://github.com/MacFall7/E-Commerce.git
-cd E-Commerce/ecom-dynamic-pricing
-
-# 2. Configure
-cp .env.example .env
-# Edit .env with Shopify credentials
-
-# 3. Start backend
-docker-compose up -d --build
-
-# 4. Verify health
-curl http://localhost:8000/api/health/detailed
-
-# 5. Start frontend (optional)
-cd frontend && npm install && npm run dev
-
-# 6. Access dashboards
-open http://localhost:3000
-```
-
-### **Day 2: Understand Architecture (1 hour)**
-
-1. Read [`README.md`](./README.md) - Architecture section
-2. Review [`backend/app/main.py`](./backend/app/main.py) - See how routing works
-3. Review [`backend/app/pricing_engine.py`](./backend/app/pricing_engine.py) - Understand pricing logic
-4. Review [`frontend/src/pages/merchant/MerchantDashboard.tsx`](./frontend/src/pages/merchant/MerchantDashboard.tsx) - See UI structure
-
-### **Day 3: Connect Test Store (30 minutes)**
-
-1. Create Shopify Partner account (free)
-2. Create test app
-3. Add credentials to `.env`
-4. Install on test store
-5. Watch products sync
-6. Run preview mode
-7. Apply pricing
-8. Test rollback
-
-### **Week 1: Make Your First Change (2 hours)**
-
-**Suggested First Change**: Add email notifications
-
-1. Install `sendgrid` package
-2. Add email config to `config.py`
-3. Create `utils/email.py` with send function
-4. Call from `tasks.py` after pricing cycle
-5. Test locally
-6. Deploy
-
----
-
-## ๐๏ธ Repository Structure
-
-```
-ecom-dynamic-pricing/
-โ
-โโโ backend/ # FastAPI backend
-โ โโโ app/
-โ โ โโโ main.py # Entry point
-โ โ โโโ config.py # Settings
-โ โ โโโ database.py # SQLAlchemy
-โ โ โโโ models.py # DB models (Store, Product, PricingEvent)
-โ โ โโโ schemas.py # Pydantic schemas
-โ โ โโโ pricing_engine.py # Pricing logic โญ
-โ โ โโโ shopify_client.py # Shopify API wrapper
-โ โ โโโ celery_app.py # Celery config
-โ โ โโโ tasks.py # Background tasks โญ
-โ โ โโโ routes/
-โ โ โโโ shopify.py # OAuth + webhooks
-โ โ โโโ operator.py # Operator controls โญ
-โ โ โโโ health.py # Health checks
-โ โโโ requirements.txt
-โ โโโ Dockerfile
-โ
-โโโ frontend/ # React frontend
-โ โโโ src/
-โ โ โโโ components/
-โ โ โ โโโ merchant/ # Merchant UI โญ
-โ โ โ โโโ operator/ # Operator UI โญ
-โ โ โ โโโ shared/ # Reusable components
-โ โ โโโ lib/
-โ โ โ โโโ api.ts # API client โญ
-โ โ โ โโโ types.ts # TypeScript types
-โ โ โโโ pages/
-โ โ โ โโโ merchant/
-โ โ โ โโโ operator/
-โ โ โโโ App.tsx
-โ โโโ package.json
-โ โโโ vite.config.ts
-โ
-โโโ docker-compose.yml # Service orchestration โญ
-โโโ .env.example # Environment template
-โโโ README.md # Main documentation โญ
-โโโ MERCHANT_QUICKSTART.md # Merchant guide
-โโโ OPERATOR_RUNBOOK.md # Operator manual
-โโโ HANDOFF.md # This document
-
-โญ = Critical files to understand
-```
-
----
-
-## ๐ Critical Concepts
-
-### **1. Pricing Flow**
-
-```
-Product Sync (Celery) โ Pricing Analysis (Engine) โ Preview (UI) โ Apply (API) โ Event Log (DB)
- โ
- Rollback (if needed)
-```
-
-### **2. Safety Mechanisms**
-
-| Mechanism | Location | Purpose |
-|-----------|----------|---------|
-| **Min/Max Limits** | `pricing_engine.py` | Never go too low/high |
-| **Cost Floor** | `pricing_engine.py` | Protect margins (cost ร 1.1) |
-| **New Product Protection** | `pricing_engine.py` | Don't touch new items |
-| **Preview Mode** | `tasks.py` | Test before apply |
-| **Rollback** | `routes/operator.py` | Undo mistakes |
-| **Suspend Toggle** | `models.py` | Emergency stop |
-
-### **3. Data Models**
-
-**Store**:
-```python
-id, shop_domain, access_token, automation_suspended,
-min_price_limit, max_price_limit, new_product_protection_days
-```
-
-**Product**:
-```python
-id, store_id, shopify_variant_id, title, current_price,
-cost, inventory_quantity, first_seen_at
-```
-
-**PricingEvent**:
-```python
-id, store_id, shopify_variant_id, old_price, new_price,
-reason, rolled_back, created_at
-```
-
-### **4. Background Tasks**
-
-| Task | Schedule | What It Does |
-|------|----------|-------------|
-| `sync_store_products` | Manual or periodic | Fetches products from Shopify, updates DB |
-| `run_pricing_cycle` | Manual or periodic | Analyzes products, applies price changes |
-
----
-
-## ๐ ๏ธ Common Operations
-
-### **Add a New Store**
-
-```bash
-# Get install URL
-curl "http://localhost:8000/api/shopify/oauth/install?shop=new-store.myshopify.com"
-
-# Merchant visits URL and authorizes
-# System auto-creates store record and syncs products
-```
-
-### **Change Pricing Logic**
-
-**File**: `backend/app/pricing_engine.py`
-
-```python
-# Current logic (lines 70-81):
-if sales_velocity > 5 and inventory > 20:
- # increase price
- new_price = min(price + delta, price * (1 + self.max_increase_pct))
- reason = "fast_seller_increase"
-
-# To modify:
-# 1. Change thresholds (5, 20)
-# 2. Change step_pct (default 0.05 = 5%)
-# 3. Add new conditions (e.g., seasonality, competitor prices)
-```
-
-### **Suspend Automation for All Stores**
-
-```bash
-# Loop through all stores
-for store_id in $(seq 1 10); do
- curl -X POST http://localhost:8000/api/operator/stores/$store_id/suspend
-done
-```
-
-### **View Recent Errors**
-
-```bash
-# Check logs
-docker-compose logs --tail=100 backend | grep ERROR
-
-# Or use Sentry dashboard
-open https://sentry.io/organizations/your-org/issues/
-```
-
-### **Scale Workers**
-
-```bash
-# Increase to 3 workers
-docker-compose up -d --scale worker=3
-
-# Verify
-curl http://localhost:8000/api/health/detailed
-# Should show 3 workers
-```
-
----
-
-## ๐ Monitoring Checklist
-
-### **Daily (2 minutes)**
-
-- [ ] Check system health: `curl http://localhost:8000/api/health/detailed`
-- [ ] Review Sentry errors: Visit Sentry dashboard
-- [ ] Check Celery queue depth: `docker-compose exec redis redis-cli LLEN celery` (should be < 100)
-
-### **Weekly (10 minutes)**
-
-- [ ] Review pricing events: Check for anomalies
-- [ ] Check disk usage: `docker system df`
-- [ ] Review merchant feedback
-- [ ] Update dependencies (security patches)
-
-### **Monthly (30 minutes)**
-
-- [ ] Database vacuum: `docker-compose exec db psql -U ecom -d ecom_db -c "VACUUM ANALYZE;"`
-- [ ] Backup database: `docker-compose exec db pg_dump -U ecom ecom_db > backup_$(date +%Y%m%d).sql`
-- [ ] Review and optimize slow queries
-- [ ] Update roadmap based on merchant requests
-
----
-
-## ๐จ Emergency Procedures
-
-### **System Down**
-
-```bash
-# 1. Check container status
-docker-compose ps
-
-# 2. Check logs
-docker-compose logs --tail=100
-
-# 3. Restart all services
-docker-compose restart
-
-# 4. If still failing, rebuild
-docker-compose down
-docker-compose up -d --build
-
-# 5. Verify health
-curl http://localhost:8000/api/health/detailed
-```
-
-### **Database Corrupted**
-
-```bash
-# 1. Stop services
-docker-compose down
-
-# 2. Restore from backup
-cat backup_20250113.sql | docker-compose exec -T db psql -U ecom -d ecom_db
-
-# 3. Restart
-docker-compose up -d
-
-# 4. Verify
-curl http://localhost:8000/api/operator/stores/1/status
-```
-
-### **Merchant Reports Wrong Prices**
-
-```bash
-# 1. Suspend automation
-curl -X POST http://localhost:8000/api/operator/stores/{store_id}/suspend
-
-# 2. Check recent events
-curl http://localhost:8000/api/operator/stores/{store_id}/pricing-history
-
-# 3. Rollback if needed
-curl -X POST "http://localhost:8000/api/operator/stores/{store_id}/rollback?limit=10"
-
-# 4. Investigate logs
-docker-compose logs worker | grep "store_id={store_id}"
-```
-
----
-
-## ๐ฎ Future Enhancements
-
-### **Short Term (1-2 weeks each)**
-
-- [ ] Add email notifications on pricing changes
-- [ ] Scheduled pricing cycles (cron-like)
-- [ ] Export pricing history to CSV
-- [ ] Multi-store dashboard view
-- [ ] Advanced filters on pricing history
-
-### **Medium Term (1-2 months each)**
-
-- [ ] Machine learning price optimization
-- [ ] Competitor price monitoring
-- [ ] A/B testing for pricing strategies
-- [ ] Seasonal pricing rules
-- [ ] Custom pricing rules per product tag
-
-### **Long Term (3-6 months each)**
-
-- [ ] Multi-channel support (Amazon, eBay)
-- [ ] Mobile app (React Native)
-- [ ] White-label solution for agencies
-- [ ] Marketplace for pricing strategies
-- [ ] Advanced analytics dashboard
-
----
-
-## ๐ฅ Team Recommendations
-
-### **Ideal Team Structure**
-
-| Role | Hours/Week | Responsibilities |
-|------|------------|------------------|
-| **DevOps Engineer** | 5-10 | Maintain infrastructure, monitor health, handle incidents |
-| **Backend Developer** | 10-20 | Add features, optimize pricing engine, API enhancements |
-| **Frontend Developer** | 5-10 | UI improvements, new dashboards, mobile app (future) |
-| **Customer Success** | 10-20 | Merchant support, feedback collection, documentation updates |
-
-**Total**: 30-60 hours/week for active development + support
-
-### **Skills Needed**
-
-- **Must Have**: Python, Docker, PostgreSQL
-- **Should Have**: React, TypeScript, FastAPI
-- **Nice to Have**: Celery, Redis, Shopify API
-
----
-
-## ๐ Learning Resources
-
-### **For Backend**
-
-- [FastAPI Tutorial](https://fastapi.tiangolo.com/tutorial/)
-- [Celery Documentation](https://docs.celeryq.dev/)
-- [SQLAlchemy ORM](https://docs.sqlalchemy.org/en/20/orm/)
-
-### **For Frontend**
-
-- [React Documentation](https://react.dev/)
-- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
-- [Tailwind CSS](https://tailwindcss.com/docs)
-
-### **For Shopify**
-
-- [Shopify API Reference](https://shopify.dev/api)
-- [OAuth Flow](https://shopify.dev/apps/auth/oauth)
-
----
-
-## โ Handoff Checklist
-
-Before final handoff, ensure:
-
-- [ ] All code is committed and pushed
-- [ ] `.env.example` is up to date
-- [ ] Documentation is current (README, runbooks)
-- [ ] Production environment is configured
-- [ ] Sentry is set up and receiving errors
-- [ ] Database backups are automated
-- [ ] At least one test merchant is onboarded
-- [ ] Support email is set up
-- [ ] Monitoring alerts are configured
-- [ ] New team has access to:
- - [ ] GitHub repository
- - [ ] Shopify Partner account
- - [ ] Sentry account
- - [ ] Production servers
- - [ ] Database credentials
-
----
-
-## ๐ Knowledge Transfer Sessions
-
-### **Recommended Schedule**
-
-**Session 1 (1 hour)**: System Overview
-- Architecture walkthrough
-- Data flow explanation
-- Key files review
-
-**Session 2 (1 hour)**: Backend Deep Dive
-- Pricing engine logic
-- Celery tasks
-- Database models
-- API endpoints
-
-**Session 3 (1 hour)**: Frontend Deep Dive
-- Component structure
-- API integration
-- State management
-- Routing
-
-**Session 4 (30 minutes)**: Operations
-- Health monitoring
-- Common issues
-- Emergency procedures
-- Deployment process
-
-**Session 5 (30 minutes)**: Next Steps
-- Roadmap review
-- Feature prioritization
-- Questions & answers
-
----
-
-## ๐ Point of Contact
-
-**Original Developer**: [Your Name]
-**Handoff Date**: 2025-01-13
-**Contact**: [Your Email]
-
-**Availability for Questions**: 30 days after handoff
-
-**Emergency Contact**: Same as above (for critical production issues only)
-
----
-
-## ๐ Final Words
-
-This system has been built with care to be:
-
-โ **Stable** - Retry logic, timeouts, health checks
-โ **Safe** - Guardrails, preview mode, rollback
-โ **Clear** - Documentation, logging, error messages
-โ **Extensible** - Clean architecture, TypeScript types
-โ **Handoff-Ready** - Everything needed to run independently
-
-**You're inheriting a production-ready system.** The hard work is done. Your job is to:
-1. Keep it running smoothly
-2. Add value through new features
-3. Support merchants
-
-**Good luck! ๐**
-
----
-
-
-
-**Questions? Start with the README.md**
-
-[README](./README.md) โข [Merchant Guide](./MERCHANT_QUICKSTART.md) โข [Operator Manual](./OPERATOR_RUNBOOK.md)
-
-
diff --git a/ecom-dynamic-pricing/MERCHANT_QUICKSTART.md b/ecom-dynamic-pricing/MERCHANT_QUICKSTART.md
deleted file mode 100644
index 193b54b..0000000
--- a/ecom-dynamic-pricing/MERCHANT_QUICKSTART.md
+++ /dev/null
@@ -1,212 +0,0 @@
-# Merchant Quickstart Guide
-## E-Commerce Dynamic Pricing
-
-### What This Does
-
-Automatically adjusts your product prices based on sales velocity and inventory levels to maximize revenue while maintaining healthy margins.
-
----
-
-## ๐ Quick Setup (5 Minutes)
-
-### Step 1: Install the App
-
-1. Click the installation link provided by your administrator
-2. You'll be redirected to Shopify to authorize the app
-3. Grant the requested permissions:
- - Read products
- - Write products
- - Read orders
-
-### Step 2: Initial Sync
-
-After installation, the system will automatically:
-- Sync all your products (takes 2-5 minutes for most stores)
-- Analyze your current pricing
-- Generate initial pricing recommendations
-
-**You won't see any price changes yet** - the system starts in preview mode.
-
-### Step 3: Configure Safety Guardrails
-
-**Before enabling automation**, set your safety limits:
-
-```
-POST /api/operator/stores/{store_id}/guardrails
-{
- "min_price": 5.00, // No product will ever be priced below this
- "max_price": 500.00, // No product will ever be priced above this
- "new_product_protection_days": 7 // New products won't be auto-priced for 7 days
-}
-```
-
-**Recommended Settings:**
-- **Min Price**: Your lowest acceptable price (typically cost ร 1.2)
-- **Max Price**: 2-3ร your highest current price
-- **New Product Protection**: 7-14 days
-
----
-
-## โ๏ธ How It Works
-
-### Pricing Logic
-
-The system makes small price adjustments based on:
-
-| Condition | Action | Example |
-|-----------|--------|---------|
-| **Fast seller** (velocity > 5/day) + High inventory (> 20 units) | Increase price by 5% | $20.00 โ $21.00 |
-| **Slow seller** (velocity < 1/day) + High inventory (> 30 units) | Decrease price by 5% | $20.00 โ $19.00 |
-| Otherwise | No change | $20.00 โ $20.00 |
-
-### Safety Features
-
-โ **Never below cost** - Always maintains 10% margin above product cost
-โ **Respects your min/max** - Won't exceed your configured limits
-โ **Protects new products** - Won't touch products for N days after first sync
-โ **Full audit trail** - Every change is logged with reason
-
----
-
-## ๐๏ธ Control Panel
-
-### Preview Mode (Test Before Applying)
-
-See what will change **before** it happens:
-
-```bash
-curl -X POST http://localhost:8000/api/operator/stores/{store_id}/pricing/preview
-```
-
-Returns:
-```json
-{
- "status": "preview",
- "suggestions": [
- {
- "variant_id": "123456",
- "old_price": 20.00,
- "new_price": 21.00,
- "reason": "fast_seller_increase"
- }
- ]
-}
-```
-
-### Emergency Stop (Suspend Automation)
-
-**Press this if something feels wrong:**
-
-```bash
-curl -X POST http://localhost:8000/api/operator/stores/{store_id}/suspend
-```
-
-This immediately stops all automated pricing. Your prices won't change until you resume.
-
-### Resume Automation
-
-```bash
-curl -X POST http://localhost:8000/api/operator/stores/{store_id}/resume
-```
-
-### Rollback Last Changes
-
-Made a mistake? Roll back the last 10 price changes:
-
-```bash
-curl -X POST http://localhost:8000/api/operator/stores/{store_id}/rollback?limit=10
-```
-
-This reverts prices to what they were before the last pricing cycle.
-
----
-
-## ๐ Monitoring Your Store
-
-### Check Current Status
-
-```bash
-curl http://localhost:8000/api/operator/stores/{store_id}/status
-```
-
-Shows:
-- โ Is automation running?
-- ๐ฆ How many products?
-- ๐ก๏ธ What are my guardrails?
-- ๐ Recent pricing activity
-
-### View Pricing History
-
-```bash
-curl http://localhost:8000/api/operator/stores/{store_id}/pricing-history
-```
-
-See exactly what changed, when, and why.
-
----
-
-## โ ๏ธ Common Questions
-
-### "Will this change all my prices overnight?"
-
-**No.** The system:
-- Makes small adjustments (5% max per cycle)
-- Only changes products meeting specific criteria
-- Respects all your guardrails
-- Logs every change
-
-### "What if I don't like a price change?"
-
-You have 3 options:
-1. **Rollback** - Undo the last N changes
-2. **Suspend** - Stop automation temporarily
-3. **Adjust Guardrails** - Tighten your min/max limits
-
-### "How do I know it's working?"
-
-Check these endpoints:
-- `/api/operator/stores/{store_id}/status` - Overall health
-- `/api/operator/stores/{store_id}/pricing-history` - What changed recently
-
-### "Can I exclude specific products?"
-
-Not yet, but coming soon. Current workaround:
-- Set cost to a high value to prevent price drops
-- Use min/max guardrails per store
-
----
-
-## ๐ When Things Go Wrong
-
-| Problem | Solution |
-|---------|----------|
-| Prices changed too much | Hit `/suspend` endpoint, then `/rollback` |
-| System not making changes | Check `/status` - automation might be suspended |
-| Can't see my products | Wait 5 minutes for initial sync, check `/status` |
-| Getting errors | Check `/api/health/detailed` for system status |
-
----
-
-## ๐ Need Help?
-
-**Operator Hotline**: Contact your system administrator
-**System Health**: `http://localhost:8000/api/health/detailed`
-**Full Docs**: See `OPERATOR_RUNBOOK.md` for technical details
-
----
-
-## โ Daily Checklist
-
-**Morning (2 minutes):**
-1. Check `/status` - Is automation running?
-2. Review `/pricing-history` - What changed last night?
-3. Verify margins look healthy
-
-**Weekly (5 minutes):**
-1. Review overall pricing trends
-2. Adjust guardrails if needed
-3. Test with `/preview` before big changes
-
----
-
-**Remember**: You're always in control. The system makes suggestions, you set the boundaries, and you can always rollback or suspend.
diff --git a/ecom-dynamic-pricing/OPERATOR_RUNBOOK.md b/ecom-dynamic-pricing/OPERATOR_RUNBOOK.md
deleted file mode 100644
index ededc33..0000000
--- a/ecom-dynamic-pricing/OPERATOR_RUNBOOK.md
+++ /dev/null
@@ -1,507 +0,0 @@
-# Operator Runbook
-## E-Commerce Dynamic Pricing - Operations Manual
-
-**Audience**: DevOps, SRE, Technical Support
-**Goal**: Diagnose and resolve 95% of issues without escalation
-
----
-
-## ๐๏ธ System Architecture
-
-```
-โโโโโโโโโโโโโโโ
-โ Merchant โ
-โ Browser โ
-โโโโโโโโฌโโโโโโโ
- โ
- v
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ FastAPI Backend โ
-โ โโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โ Routes โ /api/shopify โ โ
-โ โ โ /api/operator โ โ
-โ โ โ /api/health โ โ
-โ โโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโ โ
-โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโ
- โ โ
- v v
- โโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
- โ PostgreSQL โ โ Redis โ
- โ (Stores, โ โ (Celery โ
- โ Products, โ โ Broker) โ
- โ Events) โ โโโโโโโโโโโโโโโโ
- โโโโโโโโโโโโโโโโโ โ
- v
- โโโโโโโโโโโโโโโโ
- โ Celery โ
- โ Workers โ
- โ (Tasks) โ
- โโโโโโโโโโโโโโโโ
- โ
- v
- โโโโโโโโโโโโโโโโ
- โ Shopify โ
- โ API โ
- โโโโโโโโโโโโโโโโ
-```
-
----
-
-## ๐ Deployment
-
-### Prerequisites
-
-- Docker & Docker Compose installed
-- `.env` file configured (copy from `.env.example`)
-- Network access to Shopify API
-
-### First-Time Setup
-
-```bash
-# Clone repo
-git clone
-cd ecom-dynamic-pricing
-
-# Configure environment
-cp .env.example .env
-# Edit .env with real values
-
-# Start services
-docker-compose up --build -d
-
-# Verify health
-curl http://localhost:8000/api/health/detailed
-```
-
-### Updating / Redeploying
-
-```bash
-# Pull latest changes
-git pull origin main
-
-# Rebuild and restart
-docker-compose down
-docker-compose up --build -d
-
-# Verify
-curl http://localhost:8000/api/health
-```
-
----
-
-## ๐ Health Checks
-
-### Quick Check
-
-```bash
-curl http://localhost:8000/api/health
-# Expected: {"status": "ok", "env": "production"}
-```
-
-### Comprehensive Check
-
-```bash
-curl http://localhost:8000/api/health/detailed
-```
-
-**Expected Response:**
-```json
-{
- "status": "healthy",
- "components": {
- "postgres": {"status": "healthy", "message": "..."},
- "redis": {"status": "healthy", "message": "..."},
- "celery": {"status": "healthy", "message": "3 worker(s) active", "workers": [...]}
- }
-}
-```
-
-### Component-Specific Checks
-
-**Postgres:**
-```bash
-docker-compose exec db psql -U ecom -d ecom_db -c "SELECT COUNT(*) FROM stores;"
-```
-
-**Redis:**
-```bash
-docker-compose exec redis redis-cli PING
-# Expected: PONG
-```
-
-**Celery Workers:**
-```bash
-docker-compose logs worker | tail -50
-# Look for: "celery@ ready"
-```
-
----
-
-## ๐ Common Issues & Solutions
-
-### Issue 1: "No active Celery workers found"
-
-**Symptoms:**
-- `/api/health/detailed` shows celery as unhealthy
-- Pricing jobs not running
-- Product syncs not happening
-
-**Diagnosis:**
-```bash
-docker-compose logs worker | tail -100
-```
-
-**Common Causes:**
-1. **Worker crashed** - Check for Python exceptions in logs
-2. **Redis unreachable** - Verify Redis is running
-3. **Import errors** - Code change broke worker startup
-
-**Solution:**
-```bash
-# Restart worker
-docker-compose restart worker
-
-# If that fails, rebuild
-docker-compose up --build -d worker
-```
-
----
-
-### Issue 2: "Database connection failed"
-
-**Symptoms:**
-- `/api/health` returns 500
-- API endpoints failing
-
-**Diagnosis:**
-```bash
-docker-compose logs db | tail -50
-docker-compose ps # Check if db is running
-```
-
-**Solution:**
-```bash
-# Restart database
-docker-compose restart db
-
-# If data is corrupted
-docker-compose down
-docker volume rm ecom-dynamic-pricing_ecom_pg_data # WARNING: Deletes all data
-docker-compose up -d
-```
-
----
-
-### Issue 3: "Shopify API rate limited"
-
-**Symptoms:**
-- Logs show "Rate limited by Shopify"
-- Sync jobs failing
-- HTTP 429 errors
-
-**Diagnosis:**
-```bash
-grep "Rate limited" docker-compose logs worker
-```
-
-**Solution:**
-This is handled automatically by the client (retries with backoff), but if persistent:
-
-```bash
-# Reduce sync frequency
-# Edit celery beat schedule if using periodic tasks
-
-# Or contact Shopify support to increase rate limits
-```
-
----
-
-### Issue 4: "Pricing changes not applying"
-
-**Symptoms:**
-- Preview works, but prices don't change
-- No errors in logs
-
-**Checklist:**
-1. **Is automation suspended?**
- ```bash
- curl http://localhost:8000/api/operator/stores/{store_id}/status | jq '.automation_suspended'
- ```
-
-2. **Are variants within guardrails?**
- - Check min/max price limits
- - Check new product protection window
-
-3. **Are Shopify credentials valid?**
- ```bash
- grep "Shopify API error" docker-compose logs
- ```
-
----
-
-### Issue 5: "Worker memory leak / high CPU"
-
-**Symptoms:**
-- Worker container using > 2GB RAM
-- Slow task execution
-
-**Diagnosis:**
-```bash
-docker stats ecom_worker
-```
-
-**Solution:**
-```bash
-# Restart worker (releases memory)
-docker-compose restart worker
-
-# If recurring, investigate task code for memory leaks
-```
-
----
-
-## ๐ Monitoring Dashboards
-
-### Key Metrics to Track
-
-| Metric | Command | Healthy Range |
-|--------|---------|---------------|
-| **API Response Time** | Check `X-Process-Time` header | < 500ms |
-| **Celery Queue Size** | `docker-compose exec redis redis-cli LLEN celery` | < 100 |
-| **Database Connections** | `docker-compose exec db psql -U ecom -c "SELECT count(*) FROM pg_stat_activity;"` | < 50 |
-| **Worker Task Success Rate** | Check Celery logs | > 95% |
-| **Shopify API Errors** | `grep "Shopify API error" logs` | < 5/hour |
-
-### Setting Up Sentry (Error Monitoring)
-
-1. Create Sentry project at sentry.io
-2. Add DSN to `.env`:
- ```
- SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
- ```
-3. Restart backend:
- ```bash
- docker-compose restart backend
- ```
-
-All errors will now be forwarded to Sentry automatically.
-
----
-
-## ๐ Security Considerations
-
-### Secrets Management
-
-**Never commit:**
-- `.env` file
-- Shopify access tokens
-- Database passwords
-
-**Rotation Schedule:**
-- Shopify tokens: Never expire (unless revoked by merchant)
-- Database passwords: Rotate every 90 days
-- JWT secrets: Rotate every 180 days
-
-### Rate Limiting
-
-Shopify enforces:
-- **REST API**: 2 requests/second burst, 40 requests/second average
-- **Client handles this automatically** with retry logic
-
----
-
-## ๐จ Incident Response
-
-### Level 1: Service Degraded (Non-Critical)
-
-**Examples:**
-- Celery worker down but backup workers running
-- Single store sync failing
-- Slow response times
-
-**Response:**
-1. Document issue
-2. Fix within 4 business hours
-3. Monitor for recurrence
-
----
-
-### Level 2: Service Outage (Critical)
-
-**Examples:**
-- All workers down
-- Database unreachable
-- API returning 500s
-
-**Response:**
-1. **Immediate**: Page on-call engineer
-2. **Within 5 min**: Execute health checks
-3. **Within 15 min**: Restore service or rollback
-4. **Within 1 hour**: Root cause analysis
-5. **Within 24 hours**: Post-mortem
-
-**Quick Rollback:**
-```bash
-git checkout
-docker-compose up --build -d
-```
-
----
-
-## ๐ Escalation Matrix
-
-| Issue | First Contact | Escalate To |
-|-------|--------------|-------------|
-| Infrastructure down | DevOps on-call | Engineering lead |
-| Merchant reports incorrect pricing | Support team | Product manager |
-| Data corruption | Database admin | CTO |
-| Security incident | Security team | CTO + Legal |
-
----
-
-## ๐ง Maintenance Tasks
-
-### Daily (Automated via Cron)
-
-- Health check monitoring
-- Log rotation
-- Error rate alerts
-
-### Weekly (Manual - 15 minutes)
-
-```bash
-# 1. Check disk usage
-docker system df
-
-# 2. Review error logs
-docker-compose logs --since 24h | grep ERROR
-
-# 3. Verify backups exist
-ls -lh /backups/postgres/
-
-# 4. Check for stuck tasks
-docker-compose exec redis redis-cli LLEN celery
-```
-
-### Monthly (Manual - 30 minutes)
-
-- Review Sentry error trends
-- Update dependencies (security patches)
-- Database vacuum (Postgres maintenance)
- ```bash
- docker-compose exec db psql -U ecom -d ecom_db -c "VACUUM ANALYZE;"
- ```
-
----
-
-## ๐๏ธ Database Operations
-
-### Backup
-
-```bash
-# Manual backup
-docker-compose exec db pg_dump -U ecom ecom_db > backup_$(date +%Y%m%d).sql
-
-# Restore
-cat backup_20250113.sql | docker-compose exec -T db psql -U ecom -d ecom_db
-```
-
-### Schema Migrations (Alembic)
-
-```bash
-# Generate migration
-docker-compose exec backend alembic revision --autogenerate -m "description"
-
-# Apply migration
-docker-compose exec backend alembic upgrade head
-```
-
----
-
-## ๐ Performance Tuning
-
-### Slow API Responses
-
-1. Check database query performance:
- ```sql
- SELECT query, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;
- ```
-
-2. Add database indexes if needed
-
-3. Enable Redis caching for frequent queries
-
-### Celery Task Backlog
-
-```bash
-# Check queue depth
-docker-compose exec redis redis-cli LLEN celery
-
-# If > 1000:
-# 1. Scale workers
-docker-compose up -d --scale worker=3
-
-# 2. Investigate slow tasks
-docker-compose logs worker | grep "Task.*succeeded in"
-```
-
----
-
-## ๐งช Testing in Production
-
-### Safe Testing Workflow
-
-1. **Use a test store** - Create dummy Shopify store
-2. **Enable preview mode** - Never apply prices directly
-3. **Test rollback** - Verify you can undo changes
-4. **Monitor logs** - Watch for errors in real-time
-
-### Example Test Sequence
-
-```bash
-# 1. Sync test store
-curl -X POST http://localhost:8000/api/shopify/stores/1/sync
-
-# 2. Preview pricing
-curl -X POST http://localhost:8000/api/operator/stores/1/pricing/preview
-
-# 3. Apply (if safe)
-curl -X POST http://localhost:8000/api/shopify/stores/1/pricing/run
-
-# 4. Verify
-curl http://localhost:8000/api/operator/stores/1/pricing-history
-
-# 5. Rollback if needed
-curl -X POST http://localhost:8000/api/operator/stores/1/rollback?limit=10
-```
-
----
-
-## ๐ Additional Resources
-
-- **API Documentation**: http://localhost:8000/docs (Swagger UI)
-- **Celery Dashboard**: Install Flower for web UI
-- **Database Admin**: Use pgAdmin or DBeaver
-- **Logs**: `docker-compose logs -f `
-
----
-
-## โ Pre-Launch Checklist
-
-Before going live with a new merchant:
-
-- [ ] `.env` configured with real Shopify credentials
-- [ ] Health check passes: `/api/health/detailed`
-- [ ] Database backup scheduled
-- [ ] Sentry configured and receiving test errors
-- [ ] Guardrails set for store (min/max prices)
-- [ ] Preview mode tested successfully
-- [ ] Rollback tested and working
-- [ ] Monitoring alerts configured
-- [ ] Merchant trained on suspend/resume controls
-
----
-
-**Version**: 1.0
-**Last Updated**: 2025-01-13
-**Maintained By**: Engineering Team
diff --git a/ecom-dynamic-pricing/README.md b/ecom-dynamic-pricing/README.md
deleted file mode 100644
index e717b91..0000000
--- a/ecom-dynamic-pricing/README.md
+++ /dev/null
@@ -1,963 +0,0 @@
-# E-Commerce Dynamic Pricing System
-
-**Production-ready SaaS platform for automated Shopify product pricing using AI-driven demand signals.**
-
-[](https://fastapi.tiangolo.com)
-[](https://reactjs.org)
-[](https://www.typescriptlang.org)
-[](https://www.docker.com)
-[](LICENSE)
-
----
-
-## ๐ Table of Contents
-
-- [What Is This?](#-what-is-this)
-- [โ ๏ธ Known Limitations](#๏ธ-known-limitations)
-- [Quick Start](#-quick-start-5-minutes)
-- [Architecture](#-architecture)
-- [Features](#-features)
-- [Installation](#-installation)
-- [Configuration](#-configuration)
-- [API Documentation](#-api-documentation)
-- [Deployment](#-deployment)
-- [Monitoring](#-monitoring--maintenance)
-- [Troubleshooting](#-troubleshooting)
-- [Documentation](#-documentation)
-- [Development](#-development)
-- [Contributing](#-contributing)
-- [License](#-license)
-
----
-
-## โ ๏ธ Known Limitations
-
-**This is a v1.0 MVP built for speed.** It's production-ready for early customers but has known gaps:
-
-| Issue | Severity | Impact |
-|-------|----------|--------|
-| No testing suite | ๐ด Critical | High regression risk |
-| No formal migrations | ๐ด Critical | Risky schema changes |
-| No authentication | ๐ด Critical | Security risk |
-| No billing system | ๐ด Critical | Can't monetize |
-| Simplistic pricing logic | ๐ก Important | Suboptimal prices |
-| No APM/monitoring | ๐ก Important | Can't identify bottlenecks |
-
-**Total technical debt**: ~7 months of work to address all gaps.
-
-**For complete details, workarounds, and remediation plan**: See **[TECHNICAL_DEBT.md](./TECHNICAL_DEBT.md)**
-
-**Bottom line**: This system works and is ready for early adopters. Budget 2-4 months to harden it for scale.
-
----
-
-## ๐ฏ What Is This?
-
-A **complete, production-ready SaaS platform** that automatically adjusts Shopify product prices based on:
-- Sales velocity (how fast products sell)
-- Inventory levels
-- Configurable business rules
-- Cost floors and price ceilings
-
-### **Key Value Propositions:**
-
-| For Merchants | For Operators | For Developers |
-|---------------|---------------|----------------|
-| โ Maximize revenue automatically | โ Monitor 100+ stores from one dashboard | โ Clean, documented codebase |
-| โ Prevent stockouts and overstock | โ 95% of issues self-service | โ Type-safe TypeScript + Python |
-| โ Full control with guardrails | โ Clear health checks | โ Docker-first architecture |
-| โ Rollback any change instantly | โ Detailed runbook | โ Extensible pricing engine |
-
-### **30-Second Demo:**
-
-```bash
-# Merchant sets guardrails:
-Min price: $5.00, Max price: $500.00
-
-# System analyzes sales:
-Product A: Fast seller (10/day) + High inventory (50 units)
-โ Increase price by 5%: $20.00 โ $21.00
-
-Product B: Slow seller (0.5/day) + High inventory (80 units)
-โ Decrease price by 5%: $30.00 โ $28.50
-
-# Merchant reviews in preview mode:
-"Looks good!" โ Apply changes
-
-# Or if nervous:
-"Wait, rollback!" โ Prices reverted in 2 seconds
-```
-
----
-
-## โก Quick Start (5 Minutes)
-
-### **Prerequisites:**
-- Docker & Docker Compose installed
-- Shopify Partner account (free at https://partners.shopify.com)
-- 10 minutes
-
-### **Step 1: Clone & Configure**
-
-```bash
-# Clone repository
-git clone https://github.com/MacFall7/E-Commerce.git
-cd E-Commerce/ecom-dynamic-pricing
-
-# Copy environment template
-cp .env.example .env
-
-# Edit .env with your Shopify credentials
-nano .env # or use your favorite editor
-```
-
-**Required in `.env`:**
-```bash
-SHOPIFY_APP_API_KEY=your_shopify_api_key_here
-SHOPIFY_APP_API_SECRET=your_shopify_api_secret_here
-SHOPIFY_APP_REDIRECT_URI=https://your-ngrok-url.com/api/shopify/oauth/callback
-```
-
-### **Step 2: Start Services**
-
-```bash
-# Build and start all services (Postgres, Redis, Backend, Celery, Frontend)
-docker-compose up --build
-```
-
-**Expected output:**
-```
-โ ecom_db - PostgreSQL ready
-โ ecom_redis - Redis ready
-โ ecom_backend - FastAPI running on :8000
-โ ecom_worker - Celery worker ready
-```
-
-### **Step 3: Verify Health**
-
-```bash
-# Check API health
-curl http://localhost:8000/api/health/detailed
-
-# Expected response:
-{
- "status": "healthy",
- "components": {
- "postgres": {"status": "healthy"},
- "redis": {"status": "healthy"},
- "celery": {"status": "healthy", "workers": ["celery@ecom_worker"]}
- }
-}
-```
-
-### **Step 4: Access Dashboards**
-
-Open your browser:
-
-- **Frontend**: http://localhost:3000
-- **Merchant Dashboard**: http://localhost:3000/merchant
-- **Operator Panel**: http://localhost:3000/operator
-- **API Docs (Swagger)**: http://localhost:8000/docs
-
-### **Step 5: Connect Shopify Store**
-
-```bash
-# Get installation URL (replace {shop_domain})
-curl "http://localhost:8000/api/shopify/oauth/install?shop=your-store.myshopify.com"
-
-# Returns:
-{
- "install_url": "https://your-store.myshopify.com/admin/oauth/authorize?..."
-}
-```
-
-Visit the `install_url` in your browser to authorize the app.
-
-**๐ Done!** Your store is now connected and products will sync automatically.
-
----
-
-## ๐๏ธ Architecture
-
-### **High-Level Overview**
-
-```
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ Shopify Store โ
-โ (Products, Orders, Inventory) โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- โ OAuth + REST API
- โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ FastAPI Backend (Port 8000) โ
-โ โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
-โ โ Shopify โ Operator โ Health โ โ
-โ โ Routes โ Routes โ Checks โ โ
-โ โโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
-โ โ โ โ โ
-โ โ โ โ โ
-โ โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
-โ โ Pricing โ Shopify โ Rate โ โ
-โ โ Engine โ Client โ Limiter โ โ
-โ โโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
-โโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโ
- โ โ
- โ โ
-โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ PostgreSQL DB โ โ Redis Cache โ
-โ โโโโโโโโโโโโโโโโโโ โ โ โโโโโโโโโโโโโโโโโโโโ โ
-โ โ Stores โ โ โ โ Celery Broker โ โ
-โ โ Products โ โ โ โ Task Results โ โ
-โ โ PricingEvents โ โ โ โโโโโโโโโโโโโโโโโโโโ โ
-โ โโโโโโโโโโโโโโโโโโ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โโโโโโโโโโโโโโโโโโโโโโโโ โ
- โ
- โโโโโโโโโโโโโโโโโโโโโโโโโโโ
- โ Celery Worker(s) โ
- โ โโโโโโโโโโโโโโโโโโโโ โ
- โ โ sync_products โ โ
- โ โ run_pricing_cycleโ โ
- โ โโโโโโโโโโโโโโโโโโโโ โ
- โโโโโโโโโโโโโโโโโโโโโโโโโโโ
- โ
- โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ React Frontend (Port 3000) โ
-โ โโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โ Merchant Dashboard โ Operator Panel โ โ
-โ โ - Control Panel โ - System Health โ โ
-โ โ - Guardrails โ - Worker Monitor โ โ
-โ โ - Pricing History โ - Recent Activity โ โ
-โ โโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-```
-
-### **Technology Stack**
-
-| Layer | Technologies |
-|-------|-------------|
-| **Frontend** | React 18, TypeScript, Tailwind CSS, Vite, React Router, Axios |
-| **Backend** | FastAPI, Python 3.11, Pydantic, SQLAlchemy, Celery |
-| **Database** | PostgreSQL 16 |
-| **Cache/Queue** | Redis 7 |
-| **Infrastructure** | Docker, Docker Compose |
-| **Monitoring** | Sentry (optional), Structured Logging |
-
-### **Data Flow**
-
-1. **OAuth Installation**: Merchant installs app โ Shopify redirects to `/oauth/callback` โ Store record created
-2. **Product Sync**: Celery task `sync_store_products` runs โ Fetches products from Shopify API โ Stores in PostgreSQL
-3. **Pricing Analysis**: Celery task `run_pricing_cycle` runs โ Pricing engine analyzes variants โ Generates suggestions
-4. **Preview Mode**: Suggestions returned without applying โ Merchant reviews in UI
-5. **Apply Changes**: Suggestions approved โ Shopify API updates prices โ Events logged in database
-6. **Rollback**: Merchant clicks rollback โ Last N events retrieved โ Prices reverted in Shopify
-
----
-
-## โจ Features
-
-### **A. Infrastructure Stability**
-
-| Feature | Description | Benefit |
-|---------|-------------|---------|
-| **Retry Logic** | 3 attempts, exponential backoff, jitter | No transient failures |
-| **Timeout Guardrails** | 10min sync, 15min pricing (soft+hard limits) | No infinite loops |
-| **Rate Limiting** | Shopify 429 auto-retry with `Retry-After` | Never hit rate limits |
-| **Health Checks** | Postgres, Redis, Celery worker monitoring | Know instantly if something breaks |
-| **Structured Logging** | Timestamp, level, source, message, duration | Debug issues in seconds |
-| **Sentry Integration** | Auto-forward errors to Sentry.io | Get notified before users complain |
-
-### **B. Merchant Safety**
-
-| Feature | Description | Benefit |
-|---------|-------------|---------|
-| **Preview Mode** | See changes before applying | Zero surprises |
-| **Rollback** | Undo last 1-50 price changes | Instant recovery |
-| **Suspend/Resume** | Emergency stop button | Merchant stays in control |
-| **Min/Max Limits** | Global price floor and ceiling | Never go too low/high |
-| **Cost Floor** | Never drop below cost + 10% margin | Protect profit margins |
-| **New Product Protection** | Don't auto-price for N days | Let new products stabilize |
-| **Full Audit Trail** | Every change logged with reason | Complete transparency |
-
-### **C. Operator Tools**
-
-| Feature | Description | Benefit |
-|---------|-------------|---------|
-| **System Health Dashboard** | Real-time Postgres, Redis, Celery status | Diagnose in 30 seconds |
-| **Worker Monitor** | See active workers and task counts | Know if workers are stuck |
-| **Pricing History** | Cross-store event timeline | Spot patterns and anomalies |
-| **Manual Triggers** | Run pricing cycle on-demand | Test changes safely |
-| **Guardrail Editor** | Update limits without code changes | Iterate quickly |
-
-### **D. Developer Experience**
-
-| Feature | Description | Benefit |
-|---------|-------------|---------|
-| **Type Safety** | TypeScript frontend, Pydantic backend | Catch errors at compile time |
-| **API Documentation** | Auto-generated Swagger UI at `/docs` | No manual API docs needed |
-| **Docker First** | All services containerized | Consistent dev/prod environments |
-| **Hot Reload** | Vite (frontend), uvicorn `--reload` (backend) | Fast iteration |
-| **Clean Architecture** | Separated routes, models, services | Easy to extend |
-
----
-
-## ๐ฆ Installation
-
-### **System Requirements**
-
-- **OS**: Linux, macOS, or Windows (with WSL2)
-- **Docker**: 24.0 or later
-- **Docker Compose**: 2.0 or later
-- **RAM**: 4GB minimum, 8GB recommended
-- **Disk**: 10GB free space
-
-### **Full Installation Steps**
-
-#### **1. Clone Repository**
-
-```bash
-git clone https://github.com/MacFall7/E-Commerce.git
-cd E-Commerce/ecom-dynamic-pricing
-```
-
-#### **2. Configure Environment**
-
-```bash
-# Copy template
-cp .env.example .env
-
-# Edit with your credentials
-nano .env
-```
-
-**Required Variables:**
-```bash
-# Shopify API Credentials (from Shopify Partner Dashboard)
-SHOPIFY_APP_API_KEY=
-SHOPIFY_APP_API_SECRET=
-SHOPIFY_APP_REDIRECT_URI=/api/shopify/oauth/callback
-
-# Optional: Sentry for Error Monitoring
-SENTRY_DSN=
-```
-
-**Optional Variables** (defaults work for local dev):
-```bash
-# Database
-POSTGRES_USER=ecom
-POSTGRES_PASSWORD=ecom_password
-POSTGRES_DB=ecom_db
-
-# Redis
-REDIS_URL=redis://redis:6379/0
-
-# App
-APP_ENV=local
-APP_DEBUG=true
-```
-
-#### **3. Start Services**
-
-```bash
-# Build and start all containers
-docker-compose up --build
-
-# Or run in background
-docker-compose up -d --build
-```
-
-**Services Started:**
-- `ecom_db` - PostgreSQL on port 5432
-- `ecom_redis` - Redis on port 6379
-- `ecom_backend` - FastAPI on port 8000
-- `ecom_worker` - Celery worker (no exposed port)
-
-#### **4. Verify Installation**
-
-```bash
-# Check all containers are running
-docker-compose ps
-
-# Check API health
-curl http://localhost:8000/api/health/detailed
-
-# Check database
-docker-compose exec db psql -U ecom -d ecom_db -c "\dt"
-```
-
-#### **5. Install Frontend (Optional)**
-
-```bash
-cd frontend
-npm install
-npm run dev
-```
-
-Frontend runs on http://localhost:3000
-
----
-
-## โ๏ธ Configuration
-
-### **Environment Variables Reference**
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `SHOPIFY_APP_API_KEY` | โ | - | Your Shopify app's public API key |
-| `SHOPIFY_APP_API_SECRET` | โ | - | Your Shopify app's secret key |
-| `SHOPIFY_APP_REDIRECT_URI` | โ | - | OAuth callback URL (must be publicly accessible) |
-| `POSTGRES_USER` | โ | `ecom` | PostgreSQL username |
-| `POSTGRES_PASSWORD` | โ | `ecom_password` | PostgreSQL password |
-| `POSTGRES_DB` | โ | `ecom_db` | PostgreSQL database name |
-| `REDIS_URL` | โ | `redis://redis:6379/0` | Redis connection string |
-| `APP_ENV` | โ | `local` | Environment (local, staging, production) |
-| `APP_DEBUG` | โ | `true` | Enable debug mode |
-| `SENTRY_DSN` | โ | - | Sentry error tracking DSN |
-
-### **Shopify App Setup**
-
-1. Go to https://partners.shopify.com
-2. Create new app โ Public app
-3. Set **App URL**: `https://your-ngrok-url.com`
-4. Set **Allowed redirection URL(s)**: `https://your-ngrok-url.com/api/shopify/oauth/callback`
-5. Set **API scopes**: `read_products,write_products,read_orders`
-6. Copy API key and secret to `.env`
-
-### **Guardrails Configuration**
-
-Set via API or UI:
-
-```bash
-curl -X PUT http://localhost:8000/api/operator/stores/1/guardrails \
- -H "Content-Type: application/json" \
- -d '{
- "min_price_limit": 5.00,
- "max_price_limit": 500.00,
- "new_product_protection_days": 7
- }'
-```
-
----
-
-## ๐ API Documentation
-
-### **Interactive Docs**
-
-- **Swagger UI**: http://localhost:8000/docs
-- **ReDoc**: http://localhost:8000/redoc
-
-### **Core Endpoints**
-
-#### **Health Checks**
-
-```http
-GET /health
-GET /api/health/detailed
-GET /api/health/readiness # Kubernetes probe
-GET /api/health/liveness # Kubernetes probe
-```
-
-#### **Shopify Integration**
-
-```http
-GET /api/shopify/oauth/install?shop={shop_domain}
-GET /api/shopify/oauth/callback
-POST /api/shopify/stores/{store_id}/pricing/run
-```
-
-#### **Operator Controls**
-
-```http
-GET /api/operator/stores/{store_id}/status
-POST /api/operator/stores/{store_id}/suspend
-POST /api/operator/stores/{store_id}/resume
-POST /api/operator/stores/{store_id}/pricing/preview
-POST /api/operator/stores/{store_id}/rollback?limit={N}
-PUT /api/operator/stores/{store_id}/guardrails
-GET /api/operator/stores/{store_id}/pricing-history?limit={N}
-```
-
-### **Example API Calls**
-
-**Get Store Status:**
-```bash
-curl http://localhost:8000/api/operator/stores/1/status
-```
-
-**Response:**
-```json
-{
- "store_id": 1,
- "shop_domain": "my-store.myshopify.com",
- "is_active": true,
- "automation_suspended": false,
- "product_count": 150,
- "guardrails": {
- "min_price_limit": 5.00,
- "max_price_limit": 500.00,
- "new_product_protection_days": 7
- },
- "recent_events_count": 23
-}
-```
-
-**Preview Pricing:**
-```bash
-curl -X POST http://localhost:8000/api/operator/stores/1/pricing/preview
-```
-
-**Response:**
-```json
-{
- "status": "preview",
- "store_id": 1,
- "suggestions": [
- {
- "variant_id": "12345",
- "old_price": 20.00,
- "new_price": 21.00,
- "reason": "fast_seller_increase"
- }
- ],
- "total_suggestions": 150
-}
-```
-
----
-
-## ๐ Deployment
-
-### **Docker Compose (Production)**
-
-```bash
-# Pull latest code
-git pull origin main
-
-# Update .env for production
-cp .env.example .env
-nano .env # Set production values
-
-# Start services
-docker-compose up -d --build
-
-# Verify
-docker-compose ps
-curl https://your-domain.com/api/health/detailed
-```
-
-### **Environment-Specific Overrides**
-
-Create `docker-compose.prod.yml`:
-
-```yaml
-version: "3.9"
-
-services:
- backend:
- environment:
- APP_ENV: production
- APP_DEBUG: false
- restart: always
-
- worker:
- restart: always
-```
-
-Run with:
-```bash
-docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
-```
-
-### **Kubernetes (Advanced)**
-
-See `k8s/` directory for Kubernetes manifests (to be created).
-
-Key considerations:
-- Use Kubernetes Secrets for sensitive env vars
-- Use `readiness` and `liveness` probes
-- Set resource limits (CPU, memory)
-- Use Persistent Volumes for PostgreSQL
-- Scale workers with HPA based on queue depth
-
-### **Database Migrations**
-
-```bash
-# Generate migration
-docker-compose exec backend alembic revision --autogenerate -m "description"
-
-# Apply migration
-docker-compose exec backend alembic upgrade head
-
-# Rollback migration
-docker-compose exec backend alembic downgrade -1
-```
-
-### **Backup Strategy**
-
-**PostgreSQL:**
-```bash
-# Backup
-docker-compose exec db pg_dump -U ecom ecom_db > backup_$(date +%Y%m%d).sql
-
-# Restore
-cat backup_20250113.sql | docker-compose exec -T db psql -U ecom -d ecom_db
-```
-
-**Redis:**
-```bash
-# Redis persists to disk automatically (RDB snapshots)
-# Backup: Copy /data/dump.rdb from container
-docker cp ecom_redis:/data/dump.rdb ./redis_backup.rdb
-```
-
----
-
-## ๐ Monitoring & Maintenance
-
-### **Health Monitoring**
-
-**Automated Checks:**
-```bash
-# Add to cron (every 5 minutes)
-*/5 * * * * curl -f http://localhost:8000/api/health/detailed || echo "Health check failed" | mail -s "Alert" ops@example.com
-```
-
-**Key Metrics to Track:**
-- API response time (< 500ms)
-- Celery queue depth (< 100)
-- Database connections (< 50)
-- Worker task success rate (> 95%)
-- Shopify API error rate (< 1%)
-
-### **Sentry Integration**
-
-1. Sign up at https://sentry.io (free tier available)
-2. Create new project
-3. Copy DSN to `.env`:
- ```
- SENTRY_DSN=https://...@sentry.io/...
- ```
-4. Restart backend: `docker-compose restart backend`
-
-All errors now auto-forward to Sentry with:
-- Stack traces
-- Request context
-- User information
-- Environment tags
-
-### **Log Management**
-
-**View logs:**
-```bash
-# All services
-docker-compose logs -f
-
-# Specific service
-docker-compose logs -f backend
-docker-compose logs -f worker
-
-# Last 100 lines
-docker-compose logs --tail=100 backend
-```
-
-**Log rotation:**
-```yaml
-# Add to docker-compose.yml under each service
-logging:
- driver: "json-file"
- options:
- max-size: "10m"
- max-file: "3"
-```
-
-### **Performance Tuning**
-
-**Database:**
-```sql
--- Check slow queries
-SELECT query, mean_exec_time
-FROM pg_stat_statements
-ORDER BY mean_exec_time DESC
-LIMIT 10;
-
--- Vacuum and analyze
-VACUUM ANALYZE;
-```
-
-**Celery:**
-```bash
-# Scale workers
-docker-compose up -d --scale worker=3
-
-# Monitor queue
-docker-compose exec redis redis-cli LLEN celery
-```
-
----
-
-## ๐ง Troubleshooting
-
-### **Common Issues**
-
-| Problem | Solution |
-|---------|----------|
-| **"No active Celery workers"** | `docker-compose restart worker` |
-| **"Database connection failed"** | Check `docker-compose logs db`, ensure container is running |
-| **"Shopify API rate limited"** | Automatic retry with backoff - wait 60s |
-| **"Frontend can't connect to API"** | Ensure backend is running on port 8000, check CORS settings |
-| **"Pricing not applying"** | Check if automation is suspended: `/api/operator/stores/1/status` |
-| **"Docker build fails"** | Clear cache: `docker-compose build --no-cache` |
-
-### **Debug Mode**
-
-Enable detailed logging:
-
-```bash
-# In .env
-APP_DEBUG=true
-
-# Restart
-docker-compose restart backend
-```
-
-Now logs include:
-- Full stack traces
-- SQL queries
-- API request/response bodies
-
-### **Reset Everything**
-
-```bash
-# Stop all containers
-docker-compose down
-
-# Remove volumes (WARNING: deletes all data)
-docker volume rm ecom-dynamic-pricing_ecom_pg_data
-
-# Rebuild from scratch
-docker-compose up --build
-```
-
-### **Check System Resources**
-
-```bash
-# Container stats
-docker stats
-
-# Disk usage
-docker system df
-
-# Clean up unused images
-docker system prune -a
-```
-
----
-
-## ๐ Documentation
-
-### **For Different Audiences**
-
-| Audience | Document | Location |
-|----------|----------|----------|
-| **Merchants** | Quick Start Guide | [`MERCHANT_QUICKSTART.md`](./MERCHANT_QUICKSTART.md) |
-| **Operators** | Operations Runbook | [`OPERATOR_RUNBOOK.md`](./OPERATOR_RUNBOOK.md) |
-| **Developers** | Frontend README | [`frontend/README.md`](./frontend/README.md) |
-| **New Team Lead** | Handoff Document | [`HANDOFF.md`](./HANDOFF.md) |
-| **Technical Leads** | Known Limitations & Debt | [`TECHNICAL_DEBT.md`](./TECHNICAL_DEBT.md) |
-| **Everyone** | This README | [`README.md`](./README.md) |
-
-### **Additional Resources**
-
-- **API Reference**: http://localhost:8000/docs (Swagger UI)
-- **Architecture Decisions**: See inline code comments
-- **Pricing Engine Logic**: [`backend/app/pricing_engine.py`](./backend/app/pricing_engine.py)
-- **Database Schema**: [`backend/app/models.py`](./backend/app/models.py)
-- **Technical Debt**: See [`TECHNICAL_DEBT.md`](./TECHNICAL_DEBT.md) for known gaps and remediation plan
-
----
-
-## ๐จโ๐ป Development
-
-### **Local Development Setup**
-
-```bash
-# Backend (with hot reload)
-docker-compose up backend worker
-
-# Frontend (with hot reload)
-cd frontend
-npm install
-npm run dev
-```
-
-Changes to Python code auto-reload. Changes to React code hot-reload in browser.
-
-### **Code Structure**
-
-```
-ecom-dynamic-pricing/
-โโโ backend/
-โ โโโ app/
-โ โ โโโ main.py # FastAPI app entrypoint
-โ โ โโโ config.py # Settings management
-โ โ โโโ database.py # SQLAlchemy setup
-โ โ โโโ models.py # Database models
-โ โ โโโ schemas.py # Pydantic schemas
-โ โ โโโ pricing_engine.py # Pricing logic
-โ โ โโโ shopify_client.py # Shopify API wrapper
-โ โ โโโ celery_app.py # Celery configuration
-โ โ โโโ tasks.py # Background tasks
-โ โ โโโ routes/
-โ โ โโโ shopify.py # Shopify endpoints
-โ โ โโโ operator.py # Operator endpoints
-โ โ โโโ health.py # Health checks
-โ โโโ requirements.txt
-โ โโโ Dockerfile
-โโโ frontend/
-โ โโโ src/
-โ โ โโโ components/ # React components
-โ โ โโโ pages/ # Page components
-โ โ โโโ lib/ # API client, types
-โ โ โโโ App.tsx # Main app
-โ โโโ package.json
-โโโ docker-compose.yml
-โโโ .env.example
-โโโ MERCHANT_QUICKSTART.md
-โโโ OPERATOR_RUNBOOK.md
-โโโ README.md
-```
-
-### **Adding a New Feature**
-
-1. **Define Models** (`models.py`)
-2. **Create Schemas** (`schemas.py`)
-3. **Add Route** (`routes/*.py`)
-4. **Write Task** (`tasks.py`) if async
-5. **Update Frontend** (`frontend/src/`)
-6. **Write Tests**
-7. **Document** (update this README)
-
-### **Testing**
-
-```bash
-# Backend tests (to be added)
-docker-compose exec backend pytest
-
-# Frontend tests (to be added)
-cd frontend && npm test
-
-# Integration tests (to be added)
-./scripts/integration-tests.sh
-```
-
-### **Code Quality**
-
-```bash
-# Linting
-docker-compose exec backend flake8
-cd frontend && npm run lint
-
-# Type checking
-cd frontend && npm run type-check
-
-# Formatting
-docker-compose exec backend black .
-cd frontend && npm run format
-```
-
----
-
-## ๐ค Contributing
-
-We welcome contributions! Please follow these guidelines:
-
-### **How to Contribute**
-
-1. **Fork the repository**
-2. **Create feature branch**: `git checkout -b feature/amazing-feature`
-3. **Commit changes**: `git commit -m 'Add amazing feature'`
-4. **Push to branch**: `git push origin feature/amazing-feature`
-5. **Open Pull Request**
-
-### **PR Checklist**
-
-- [ ] Code follows existing style
-- [ ] All tests pass
-- [ ] Documentation updated
-- [ ] CHANGELOG.md updated
-- [ ] No breaking changes (or clearly documented)
-
-### **Code Style**
-
-- **Python**: Follow PEP 8, use Black formatter
-- **TypeScript**: Follow Airbnb style guide, use Prettier
-- **Commits**: Use conventional commits (`feat:`, `fix:`, `docs:`, etc.)
-
----
-
-## ๐ License
-
-This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
-
-### **MIT License Summary**
-
-โ Commercial use
-โ Modification
-โ Distribution
-โ Private use
-
-โ Liability
-โ Warranty
-
----
-
-## ๐ Acknowledgments
-
-- **FastAPI** - Modern, fast web framework
-- **React** - UI library
-- **Shopify** - E-commerce platform
-- **Celery** - Distributed task queue
-- **PostgreSQL** - Reliable database
-- **Redis** - In-memory data store
-
----
-
-## ๐ Support
-
-- **Issues**: https://github.com/MacFall7/E-Commerce/issues
-- **Discussions**: https://github.com/MacFall7/E-Commerce/discussions
-- **Email**: support@example.com
-
----
-
-## ๐บ๏ธ Roadmap
-
-- [x] Core pricing engine
-- [x] Shopify integration
-- [x] Merchant dashboard
-- [x] Operator panel
-- [x] Production stability features
-- [ ] Multi-variant pricing strategies
-- [ ] Machine learning price optimization
-- [ ] Competitor price monitoring
-- [ ] A/B testing for pricing
-- [ ] Mobile app (React Native)
-- [ ] Multi-channel support (Amazon, eBay)
-
----
-
-## ๐ Status
-
-**Current Version**: 1.0.0
-**Status**: Production Ready โ
-**Last Updated**: 2025-01-13
-
----
-
-
-
-**Built with โค๏ธ for merchants who want to maximize revenue without the complexity**
-
-[Get Started](#-quick-start-5-minutes) โข [View Demo](#) โข [Report Bug](https://github.com/MacFall7/E-Commerce/issues)
-
-
-
-**This roadmap is a living document. Update as priorities shift.**
-
-[Back to README](./README.md) โข [View Technical Debt](./TECHNICAL_DEBT.md) โข [Handoff Guide](./HANDOFF.md)
-
-
diff --git a/ecom-dynamic-pricing/TECHNICAL_DEBT.md b/ecom-dynamic-pricing/TECHNICAL_DEBT.md
deleted file mode 100644
index a8535f3..0000000
--- a/ecom-dynamic-pricing/TECHNICAL_DEBT.md
+++ /dev/null
@@ -1,744 +0,0 @@
-# Technical Debt & Known Weaknesses
-
-**Last Updated**: 2025-01-13
-**Status**: Production-ready but with known gaps
-
----
-
-## ๐ฏ Philosophy
-
-This system was built with the **"get it running first, perfect it later"** approach. It's production-ready for early customers, but there are known weaknesses you should address as you scale.
-
-**Honest Assessment**: This is a **v1.0 MVP**, not a **v5.0 enterprise system**.
-
----
-
-## ๐ Severity Categories
-
-| Level | Description | Timeline |
-|-------|-------------|----------|
-| ๐ด **Critical** | Must fix before scaling to 50+ stores | 1-2 months |
-| ๐ก **Important** | Should fix before major features | 3-6 months |
-| ๐ข **Nice-to-Have** | Quality of life improvements | 6-12 months |
-
----
-
-## ๐ด Critical Gaps
-
-### **1. No Testing Suite**
-
-**Problem:**
-- Zero unit tests
-- Zero integration tests
-- Zero E2E tests
-- Changes require manual verification
-
-**Impact:**
-- High risk of regression bugs
-- Slow development velocity
-- Difficult to refactor with confidence
-
-**Current Workaround:**
-```bash
-# Manual testing checklist (see OPERATOR_RUNBOOK.md)
-1. Check health endpoint
-2. Connect test store
-3. Run preview mode
-4. Apply pricing
-5. Test rollback
-```
-
-**Proper Fix:**
-```bash
-# Backend testing (pytest)
-backend/tests/
-โโโ unit/
-โ โโโ test_pricing_engine.py
-โ โโโ test_shopify_client.py
-โ โโโ test_models.py
-โโโ integration/
-โ โโโ test_api.py
-โ โโโ test_tasks.py
-โโโ conftest.py
-
-# Frontend testing (Jest + React Testing Library)
-frontend/src/
-โโโ components/
-โ โโโ __tests__/
-โโโ pages/
- โโโ __tests__/
-
-# Example test
-def test_pricing_engine_increases_fast_seller():
- engine = PricingEngine()
- result = engine.suggest_prices([{
- "variant_id": "123",
- "current_price": 20.0,
- "sales_velocity": 10.0, # Fast
- "inventory_quantity": 50
- }])
- assert result[0]["new_price"] > 20.0
- assert result[0]["reason"] == "fast_seller_increase"
-```
-
-**Effort**: 2-3 weeks for 80% coverage
-
-**Priority**: Fix this **first** before adding major features
-
----
-
-### **2. No Formal Database Migrations**
-
-**Problem:**
-- Schema changes done via `Base.metadata.create_all()`
-- No migration history
-- Can't rollback schema changes
-- Manual production updates risky
-
-**Impact:**
-- Database changes are destructive
-- Can't easily add columns to production
-- No audit trail of schema changes
-
-**Current Workaround:**
-```bash
-# Schema changes require manual SQL
-docker-compose exec db psql -U ecom -d ecom_db -c "ALTER TABLE stores ADD COLUMN new_field VARCHAR(255);"
-```
-
-**Proper Fix:**
-```bash
-# Setup Alembic
-cd backend
-pip install alembic
-alembic init migrations
-
-# Create migration
-alembic revision --autogenerate -m "Add new_field to stores"
-
-# Apply migration
-alembic upgrade head
-
-# Rollback
-alembic downgrade -1
-```
-
-**Implementation:**
-```python
-# alembic/env.py
-from app.database import Base
-from app.models import Store, Product, PricingEvent
-
-target_metadata = Base.metadata
-
-# Then migrations are automatic
-alembic revision --autogenerate -m "description"
-```
-
-**Effort**: 1 week to set up + retrofit existing schema
-
-**Priority**: Fix before first production schema change
-
----
-
-### **3. No Authentication/Authorization**
-
-**Problem:**
-- No user accounts
-- No login system
-- API endpoints are public (anyone with URL can call)
-- No role-based access control (RBAC)
-
-**Impact:**
-- Can't have multiple users per store
-- No audit of who did what
-- Operator panel is accessible to anyone
-- Can't restrict pricing changes to admins
-
-**Current Workaround:**
-- Deploy behind VPN
-- Use IP whitelisting
-- Assume single user per store
-
-**Proper Fix:**
-```python
-# Add User model
-class User(Base):
- __tablename__ = "users"
- id = Column(Integer, primary_key=True)
- email = Column(String, unique=True)
- password_hash = Column(String) # bcrypt
- role = Column(String) # "merchant", "operator", "admin"
- store_id = Column(Integer, ForeignKey("stores.id"))
-
-# Add JWT authentication
-from fastapi import Depends, HTTPException
-from fastapi.security import OAuth2PasswordBearer
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
-
-async def get_current_user(token: str = Depends(oauth2_scheme)):
- # Verify JWT token
- # Return user
- pass
-
-# Protect routes
-@router.post("/pricing/run")
-async def run_pricing(
- store_id: int,
- current_user: User = Depends(get_current_user)
-):
- if current_user.role != "merchant":
- raise HTTPException(403, "Not authorized")
- # ...
-```
-
-**Effort**: 2-3 weeks for basic auth, 1 month for full RBAC
-
-**Priority**: Fix before handling sensitive merchant data
-
----
-
-### **4. No Billing/Subscription System**
-
-**Problem:**
-- No way to charge merchants
-- No subscription tiers
-- No usage tracking
-- No payment integration
-
-**Impact:**
-- Can't monetize
-- No revenue
-- Can't limit features by plan
-
-**Current Workaround:**
-- Manual invoicing
-- Honor system
-- Or make it free during beta
-
-**Proper Fix:**
-```python
-# Add Subscription model
-class Subscription(Base):
- __tablename__ = "subscriptions"
- id = Column(Integer, primary_key=True)
- store_id = Column(Integer, ForeignKey("stores.id"))
- plan = Column(String) # "free", "pro", "enterprise"
- stripe_subscription_id = Column(String)
- status = Column(String) # "active", "canceled", "past_due"
- current_period_end = Column(DateTime)
-
-# Integrate Stripe
-import stripe
-
-@router.post("/subscribe")
-async def create_subscription(plan: str, store_id: int):
- subscription = stripe.Subscription.create(
- customer=store.stripe_customer_id,
- items=[{"price": PLAN_PRICES[plan]}]
- )
- # Save to DB
-```
-
-**Effort**: 2 weeks for Stripe integration, 1 week for plan limits
-
-**Priority**: Fix before public launch
-
----
-
-## ๐ก Important Gaps
-
-### **5. Simplistic Pricing Engine**
-
-**Problem:**
-- Uses simple thresholds (velocity > 5, inventory > 20)
-- No machine learning
-- No seasonality
-- No competitor monitoring
-- No demand forecasting
-
-**Impact:**
-- Suboptimal prices (leaves money on table)
-- Can't handle complex scenarios
-- Not differentiated from competitors
-
-**Current Workaround:**
-- The simple logic actually works for 80% of cases
-- Merchants can adjust guardrails to compensate
-
-**Better Approach:**
-```python
-# ML-based pricing
-class MLPricingEngine:
- def __init__(self):
- self.model = self.load_model() # XGBoost, LightGBM
-
- def suggest_prices(self, variants):
- features = self.extract_features(variants)
- # Features: sales_velocity, inventory, day_of_week,
- # season, historical_demand, cost, margin
- predictions = self.model.predict(features)
- return predictions
-
- def extract_features(self, variants):
- # Engineer features from:
- # - Order history (sales trends)
- # - Inventory trends
- # - Time features (seasonality)
- # - Product attributes
- pass
-```
-
-**Effort**: 2-3 months for ML pipeline, data collection, training
-
-**Priority**: Fix after 50+ stores (need training data first)
-
----
-
-### **6. No APM/Monitoring**
-
-**Problem:**
-- No performance monitoring
-- No request tracing
-- No database query profiling
-- Only basic health checks
-
-**Impact:**
-- Can't identify slow endpoints
-- Can't trace errors across services
-- Can't optimize bottlenecks
-
-**Current Workaround:**
-- Manual log analysis
-- Sentry for errors only
-- Response time in headers (`X-Process-Time`)
-
-**Proper Fix:**
-```python
-# Add DataDog, New Relic, or Elastic APM
-import ddtrace
-from ddtrace import tracer
-
-ddtrace.patch_all() # Auto-instrument FastAPI, SQLAlchemy, Redis
-
-@tracer.wrap()
-def expensive_function():
- # Traced automatically
- pass
-
-# Or Prometheus + Grafana
-from prometheus_fastapi_instrumentator import Instrumentator
-
-Instrumentator().instrument(app).expose(app)
-```
-
-**Effort**: 1 week for APM setup, 1 week for dashboard creation
-
-**Priority**: Fix after first 10 paying customers
-
----
-
-### **7. No Worker Autoscaling**
-
-**Problem:**
-- Worker count is fixed (default 1)
-- Can't handle traffic spikes
-- Manual scaling only
-
-**Impact:**
-- Queue backs up during high load
-- Slow processing during peak times
-- Wasted resources during low load
-
-**Current Workaround:**
-```bash
-# Manual scaling
-docker-compose up -d --scale worker=3
-```
-
-**Proper Fix:**
-```yaml
-# Kubernetes HPA
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
- name: celery-worker
-spec:
- scaleTargetRef:
- apiVersion: apps/v1
- kind: Deployment
- name: celery-worker
- minReplicas: 1
- maxReplicas: 10
- metrics:
- - type: External
- external:
- metric:
- name: celery_queue_length
- target:
- type: AverageValue
- averageValue: "100" # Scale if queue > 100
-```
-
-**Effort**: 2 weeks for K8s + HPA setup
-
-**Priority**: Fix when handling 100+ stores
-
----
-
-### **8. No Rate Limiting (User-Facing)**
-
-**Problem:**
-- Merchants can spam API endpoints
-- No protection against abuse
-- No per-store rate limits
-
-**Impact:**
-- API can be overloaded
-- No defense against malicious actors
-
-**Current Workaround:**
-- Trust merchants not to abuse
-- Backend rate limits Shopify API only
-
-**Proper Fix:**
-```python
-from slowapi import Limiter, _rate_limit_exceeded_handler
-from slowapi.util import get_remote_address
-
-limiter = Limiter(key_func=get_remote_address)
-app.state.limiter = limiter
-
-@router.post("/pricing/run")
-@limiter.limit("10/minute") # Max 10 pricing runs per minute
-async def run_pricing(request: Request, store_id: int):
- # ...
-```
-
-**Effort**: 1-2 days
-
-**Priority**: Fix before public launch
-
----
-
-## ๐ข Nice-to-Have Improvements
-
-### **9. Frontend State Management**
-
-**Problem:**
-- Prop drilling in places
-- No global state manager (Redux, Zustand)
-- Duplicate API calls
-- No caching
-
-**Impact:**
-- Code is verbose
-- Performance could be better
-- Refactoring is harder
-
-**Current Workaround:**
-- It works fine for current scale
-- React Context could be added easily
-
-**Better Approach:**
-```typescript
-// Add Zustand for global state
-import create from 'zustand'
-
-interface StoreState {
- storeId: number | null
- status: StoreStatus | null
- loadStatus: () => Promise
-}
-
-const useStore = create((set) => ({
- storeId: null,
- status: null,
- loadStatus: async () => {
- const status = await operatorApi.getStoreStatus(get().storeId)
- set({ status })
- }
-}))
-
-// Use in components
-function MyComponent() {
- const { status, loadStatus } = useStore()
- // No prop drilling!
-}
-```
-
-**Effort**: 1 week
-
-**Priority**: Fix when frontend becomes unwieldy
-
----
-
-### **10. No Real-Time Updates**
-
-**Problem:**
-- UI requires manual refresh
-- No WebSocket connection
-- No push notifications
-
-**Impact:**
-- Operators don't see changes immediately
-- Have to refresh page to see new events
-
-**Current Workaround:**
-- Auto-refresh every 30 seconds (health check)
-- Manual refresh button
-
-**Better Approach:**
-```python
-# Add WebSocket support
-from fastapi import WebSocket
-
-@app.websocket("/ws")
-async def websocket_endpoint(websocket: WebSocket):
- await websocket.accept()
- while True:
- # Push updates when pricing events occur
- await websocket.send_json({"type": "pricing_event", "data": {...}})
-```
-
-**Effort**: 1 week
-
-**Priority**: Fix when real-time is required
-
----
-
-### **11. No Email Notifications**
-
-**Problem:**
-- No email alerts for critical events
-- Merchants don't know when prices change
-- Operators aren't notified of failures
-
-**Impact:**
-- Merchants are surprised by changes
-- Operators miss critical alerts
-
-**Current Workaround:**
-- Check dashboard manually
-- Review Sentry for errors
-
-**Better Approach:**
-```python
-# Add SendGrid integration
-import sendgrid
-from sendgrid.helpers.mail import Mail
-
-def send_pricing_summary(store_id: int, changes: List[PricingEvent]):
- message = Mail(
- from_email='noreply@example.com',
- to_emails=store.owner_email,
- subject='Daily Pricing Summary',
- html_content=render_template('pricing_summary.html', changes=changes)
- )
- sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
- sg.send(message)
-
-# Call after pricing cycle
-send_pricing_summary(store_id, applied_changes)
-```
-
-**Effort**: 3-4 days
-
-**Priority**: Fix when merchants request it
-
----
-
-### **12. No Competitor Price Monitoring**
-
-**Problem:**
-- Pricing decisions ignore competitor prices
-- Can't react to market changes
-- No price intelligence
-
-**Impact:**
-- May price too high/low vs market
-- Miss opportunities
-
-**Current Workaround:**
-- Merchants set guardrails based on market knowledge
-
-**Better Approach:**
-```python
-# Web scraping or API integration
-class CompetitorMonitor:
- def get_competitor_prices(self, product_sku: str) -> List[float]:
- # Scrape competitor sites
- # Or use price intelligence API (Prisync, etc.)
- return [19.99, 21.50, 18.75]
-
- def suggest_price_with_competition(self, product):
- competitor_prices = self.get_competitor_prices(product.sku)
- avg_competitor = sum(competitor_prices) / len(competitor_prices)
- # Adjust based on competition
- return avg_competitor * 0.95 # Undercut by 5%
-```
-
-**Effort**: 2-3 weeks
-
-**Priority**: Competitive differentiator for later
-
----
-
-### **13. No Internationalization (i18n)**
-
-**Problem:**
-- All text is hardcoded in English
-- No multi-currency support
-- No timezone handling
-
-**Impact:**
-- Can only serve English-speaking merchants
-- Prices assume USD
-
-**Current Workaround:**
-- Only target US/UK/Australia markets
-
-**Better Approach:**
-```typescript
-// Frontend i18n (react-i18next)
-import { useTranslation } from 'react-i18next'
-
-function MyComponent() {
- const { t } = useTranslation()
- return
{t('dashboard.title')}
-}
-
-// Backend
-from babel.numbers import format_currency
-
-format_currency(price, 'USD', locale='en_US') # $20.00
-format_currency(price, 'GBP', locale='en_GB') # ยฃ20.00
-```
-
-**Effort**: 1-2 weeks
-
-**Priority**: Fix when expanding internationally
-
----
-
-## ๐ Prioritized Remediation Plan
-
-### **Phase 1: Foundation (Months 1-2)**
-
-Focus: Make it safe to change code
-
-| Task | Effort | Impact |
-|------|--------|--------|
-| Add testing suite | 3 weeks | High |
-| Setup Alembic migrations | 1 week | High |
-| Add user authentication | 2 weeks | High |
-
-### **Phase 2: Monetization (Months 3-4)**
-
-Focus: Make money
-
-| Task | Effort | Impact |
-|------|--------|--------|
-| Integrate Stripe billing | 2 weeks | Critical |
-| Add subscription tiers | 1 week | High |
-| Add rate limiting | 2 days | Medium |
-
-### **Phase 3: Scaling (Months 5-6)**
-
-Focus: Handle growth
-
-| Task | Effort | Impact |
-|------|--------|--------|
-| Add APM (DataDog/New Relic) | 1 week | High |
-| Setup worker autoscaling | 2 weeks | Medium |
-| Add email notifications | 4 days | Medium |
-
-### **Phase 4: Intelligence (Months 7-12)**
-
-Focus: Better pricing
-
-| Task | Effort | Impact |
-|------|--------|--------|
-| ML pricing engine | 3 months | High |
-| Competitor monitoring | 3 weeks | Medium |
-| Advanced analytics | 2 weeks | Low |
-
----
-
-## ๐ฏ What To Fix First?
-
-**If you're handling < 10 stores:**
-- Testing suite (avoid breaking things)
-- Database migrations (safe schema changes)
-
-**If you're handling 10-50 stores:**
-- User authentication (security)
-- Billing integration (make money)
-- APM (find bottlenecks)
-
-**If you're handling 50+ stores:**
-- Worker autoscaling (handle load)
-- ML pricing engine (competitive advantage)
-
----
-
-## ๐ฌ Honest Q&A
-
-**Q: Is this system production-ready?**
-A: Yes, for early customers (< 50 stores). But expect to invest 3-6 months of dev time to harden it for scale.
-
-**Q: What's the biggest risk?**
-A: No testing means regressions are easy. Add tests first.
-
-**Q: Can I launch with this?**
-A: Absolutely. But add auth and billing within 2 months.
-
-**Q: Will I need to rewrite anything?**
-A: No. The architecture is solid. You're adding features, not rebuilding.
-
-**Q: How much technical debt is this?**
-A: ~3-4 months of work to address critical + important gaps. That's normal for an MVP.
-
-**Q: Should I be worried?**
-A: No. Every successful SaaS starts like this. The key is that **we documented all the gaps** instead of hiding them.
-
----
-
-## ๐ Technical Debt Metrics
-
-| Category | Count | Estimated Fix Time |
-|----------|-------|-------------------|
-| Critical Issues | 4 | 2 months |
-| Important Issues | 4 | 3 months |
-| Nice-to-Have | 5 | 2 months |
-| **Total** | **13** | **7 months** |
-
-**Realistic Timeline**: Fix critical issues in 2 months, important issues over 6 months, nice-to-haves as needed.
-
----
-
-## โ What's Actually Good
-
-Don't forget what's **already solid**:
-
-- โ Clean architecture (easy to extend)
-- โ Type safety (TypeScript + Pydantic)
-- โ Error handling (retry logic, timeouts)
-- โ Logging (structured, readable)
-- โ Documentation (comprehensive)
-- โ Docker setup (reproducible)
-- โ Health checks (observable)
-- โ Safety features (preview, rollback, guardrails)
-
-**This is a solid foundation.** The gaps are normal for an MVP. You're not inheriting a messโyou're inheriting a v1.0 that works, with a clear roadmap to v2.0.
-
----
-
-
-
-**Gaps are opportunities, not failures.**
-
-[Back to README](./README.md) โข [View Roadmap](./README.md#-roadmap)
-
-