╔══════════════════════════════════════════════════════════════════╗
║        🐳 DOCKER MICROSERVICES — COMPLETE RUN GUIDE             ║
║        E-Commerce: Users + Products + Orders                    ║
╚══════════════════════════════════════════════════════════════════╝

NO DOCKER NEEDED — runs entirely with Python 3 (built-in libraries only!)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PROJECT STRUCTURE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  docker-microservices/
  ├── dashboard.html          ← Open this in  browser (architecture viz)
  ├── start_all.py            ← ONE COMMAND to start everything
  ├── docker-compose.yml      ← Reference: what real Docker would look like
  ├── RUN_GUIDE.txt           ← This file
  └── services/
      ├── gateway.py          ← API Gateway     :8000
      ├── user_service.py     ← User Service    :8001
      ├── product_service.py  ← Product Service :8002
      └── order_service.py    ← Order Service   :8003

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✅  Python 3.7+  (No pip installs needed — uses stdlib only!)

  Check your Python version:
    python --version
    python3 --version

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  OPTION A — EASIEST: Start everything at once
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. Open a terminal in the project root folder (docker-microservices/)
  2. Run:

       python start_all.py

  3. Open dashboard.html in  browser
  4. Click TEST buttons to fire real API requests

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  OPTION B — DOCKER-STYLE: Each service in its own terminal
  (This is closer to how Docker actually works sir)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Open 4 separate VS Code terminals (Terminal → New Terminal):

  Terminal 1 — User Service:
    cd services
    python user_service.py

  Terminal 2 — Product Service:
    cd services
    python product_service.py

  Terminal 3 — Order Service:
    cd services
    python order_service.py

  Terminal 4 — API Gateway (start this LAST):
    cd services
    python gateway.py

  Then open dashboard.html in your browser.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  TESTING WITH CURL (copy-paste these)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ── Health Checks ──
  curl http://localhost:8000/health
  curl http://localhost:8001/health
  curl http://localhost:8002/health
  curl http://localhost:8003/health

  ── Users ──
  curl http://localhost:8000/users

  curl -X POST http://localhost:8000/users/register \
    -H "Content-Type: application/json" \
    -d '{"name":"Charlie","email":"charlie@test.com","password":"pass123"}'

  curl http://localhost:8000/users/1

  ── Products ──
  curl http://localhost:8000/products

  curl -X POST http://localhost:8000/products \
    -H "Content-Type: application/json" \
    -d '{"name":"Wireless Mouse","price":49.99,"stock":75,"category":"Electronics"}'

  curl http://localhost:8000/products/1

  ── Orders (demonstrates inter-service calls!) ──
  curl http://localhost:8000/orders

  curl -X POST http://localhost:8000/orders \
    -H "Content-Type: application/json" \
    -d '{"user_id":1,"product_id":1,"quantity":2}'

  Watch the terminals — you'll see:
    [GATEWAY :8000]  POST /orders → Order Service
    [ORDER SVC :8003] → Calling User Service: GET /users/1
    [USER SVC :8001]  GET /users/1
    [ORDER SVC :8003] → Calling Product Service: GET /products/1
    [PRODUCT SVC :8002] GET /products/1
    [EVENT BUS ⚡] Published: order.created
    [PRODUCT SVC :8002] Stock updated: product #1 → 23 remaining

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  WHAT THIS DEMONSTRATES (Architecture Concepts)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  🔀 API GATEWAY PATTERN
     All traffic goes through :8000. Services are "hidden" from clients.
     Gateway handles routing, (would handle auth, rate-limiting, etc.)

  📦 SERVICE ISOLATION
     Each service has its own database (users.db, products.db, orders.db).
     Services NEVER share a database — only communicate via APIs.

  🌐 INTER-SERVICE COMMUNICATION
     Order Service calls User Service + Product Service to place an order.
     This is "synchronous" communication (REST API calls).

  ⚡ EVENT-DRIVEN ARCHITECTURE
     After creating an order, an "order.created" event is published.
     Product Service consumes this event asynchronously → updates stock.
     This is "asynchronous" communication (message queue pattern).

  🐳 HOW DOCKER MAPS TO THIS
     Each python file = one Docker container
     SQLite file = Docker volume (persistent storage)
     localhost:port = docker-compose service name + port
     "All services running" = docker-compose up

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  TROUBLESHOOTING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ❌ "Address already in use"
     A port is taken. Kill it:
       Mac/Linux: lsof -ti:8000 | xargs kill -9
       Windows:   netstat -ano | findstr :8000  → taskkill /PID <id> /F

  ❌ "Connection refused" in dashboard
     Services aren't running. Start them first with python start_all.py

  ❌ "ModuleNotFoundError"
     Make sure you're in the right directory:
       cd services/  (for individual services)
       cd docker-microservices/  (for start_all.py)

  ❌ Dashboard TEST buttons show error but services are running
     Your browser may block localhost requests. Try opening dashboard.html
     from a local server:
       python -m http.server 3000
     Then visit: http://localhost:3000/dashboard.html

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  RESET / CLEAN DATABASES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Delete the .db files to start fresh:
    Windows:   del services\*.db

  Then restart the services — they'll re-seed automatically.

╚══════════════════════════════════════════════════════════════════╝
