# Wizamart Multi-Tenant URL Routing - Documentation Index

**Generated:** November 7, 2025  
**Project:** Wizamart Multi-Tenant E-Commerce Platform  
**Topic:** Understanding how customers access vendor shops via URLs

---

## 📚 Documentation Files

### 1. **COMPLETE_SUMMARY.txt** ⭐ START HERE
   **Best for:** Getting the complete picture in one file
   
   Contains:
   - TL;DR answer to the main question
   - All three deployment modes explained
   - Request processing flow
   - Vendor isolation layers
   - All shop routes
   - Complete request lifecycle example
   - Debugging tips & troubleshooting
   - Security best practices
   
   **Read this when:** You need everything in one place

---

### 2. **WIZAMART_MULTITENANT_URL_GUIDE.md**
   **Best for:** Deep dive into multi-tenant architecture
   
   Contains:
   - Detailed explanation of all three deployment modes
   - Subdomain mode with real-world example
   - Custom domain mode with setup steps
   - Path-based mode for development
   - Complete route examples
   - How vendor isolation works
   - Request routing decision tree
   - Theme integration
   - Database perspective
   - Potential issues and solutions
   
   **Read this when:** You want comprehensive documentation

---

### 3. **QUICK_REFERENCE.md**
   **Best for:** Quick lookups while coding
   
   Contains:
   - URL breakdown diagrams
   - Request flow (in order)
   - Detection priority (highest to lowest)
   - All shop routes table
   - API endpoints pattern
   - Request state contents
   - Vendor isolation multi-layer view
   - Common scenarios
   - Middleware files location
   - Environment configuration
   - Debugging tips
   - Quick links to code files
   
   **Read this when:** You need a specific answer quickly

---

### 4. **ARCHITECTURE_DIAGRAMS.txt**
   **Best for:** Visual understanding of the system
   
   Contains:
   - Production deployment diagram
   - Development deployment diagram
   - Vendor detection decision tree
   - Database schema (multi-tenant)
   - Request context detection table
   - Authorization layers

   **Read this when:** You prefer visual representations

---

## 🎯 Quick Navigation by Use Case

### "I need to understand the basic URLs"
→ Read: **COMPLETE_SUMMARY.txt** (Top section)
→ Time: 5 minutes

### "I need to set up production deployment"
→ Read: **QUICK_REFERENCE.md** (Deployment Checklist section)
→ Then: **WIZAMART_MULTITENANT_URL_GUIDE.md** (Mode 1 & 2 sections)
→ Time: 15 minutes

### "I'm debugging a routing issue"
→ Read: **QUICK_REFERENCE.md** (Debugging Tips section)
→ Then: **COMPLETE_SUMMARY.txt** (Potential Issues section)
→ Time: 10 minutes

### "I need to understand vendor isolation"
→ Read: **COMPLETE_SUMMARY.txt** (Vendor Isolation section)
→ Then: **WIZAMART_MULTITENANT_URL_GUIDE.md** (How Vendor Isolation Works)
→ Time: 15 minutes

### "I want a complete technical overview"
→ Read: **WIZAMART_MULTITENANT_URL_GUIDE.md** (entire file)
→ Then: **ARCHITECTURE_DIAGRAMS.txt** (visual reference)
→ Time: 30 minutes

### "I need to learn the middleware flow"
→ Read: **ARCHITECTURE_DIAGRAMS.txt** (Production Deployment diagram)
→ Then: **COMPLETE_SUMMARY.txt** (Request Processing Flow)
→ Time: 10 minutes

---

## 📖 The Three Deployment Modes

### Mode 1: Subdomain (Production Standard)
```
URL: https://acme.wizamart.com/shop/products
Best for: Most vendors
SSL: Single wildcard certificate
DNS: Add subdomains as needed
```
📖 Details: WIZAMART_MULTITENANT_URL_GUIDE.md → "1. SUBDOMAIN MODE"

### Mode 2: Custom Domain (Production Premium)
```
URL: https://store.acme-corp.com/shop/products
Best for: Premium vendors
SSL: Vendor's own certificate
DNS: Vendor configures domain
```
📖 Details: WIZAMART_MULTITENANT_URL_GUIDE.md → "2. CUSTOM DOMAIN MODE"

### Mode 3: Path-Based (Development)
```
URL: http://localhost:8000/vendor/acme/shop/products
Best for: Development & testing
SSL: None needed
DNS: None needed
```
📖 Details: WIZAMART_MULTITENANT_URL_GUIDE.md → "3. PATH-BASED MODE"

---

## 🔄 Request Flow Overview

```
Customer Request
    ↓
vendor_context_middleware    ← Detects which vendor
    ↓
context_middleware           ← Determines context type (SHOP)
    ↓
theme_context_middleware     ← Loads vendor's theme
    ↓
Route Matching               ← /shop/products
    ↓
Handler Execution            ← Renders template
    ↓
Template with Theme          ← Uses vendor's colors, logo, fonts
    ↓
HTML Response                ← Fully branded shop
    ↓
JavaScript API Call          ← Fetches products
    ↓
Customer sees Shop           ← With vendor's theme
```

📖 Full details: COMPLETE_SUMMARY.txt → "REQUEST PROCESSING FLOW"

---

## 🛡️ Vendor Isolation (4 Layers)

```
Layer 1: URL Detection     ← Identifies vendor from host/domain/path
   ↓
Layer 2: Middleware        ← Sets request.state.vendor
   ↓
Layer 3: Database Queries  ← WHERE vendor_id = ?
   ↓
Layer 4: API Authorization ← Validates vendor_id
   ↓
Result: No cross-vendor access possible
```

📖 Full details: COMPLETE_SUMMARY.txt → "VENDOR ISOLATION: 4 LAYERS"

---

## 🗂️ All Shop Routes

| Category | Routes |
|----------|--------|
| **Public** | `/shop/`, `/shop/products`, `/shop/categories/{slug}`, `/shop/search`, etc. |
| **Auth** | `/shop/account/register`, `/shop/account/login`, `/shop/account/forgot-password` |
| **Protected** | `/shop/account/dashboard`, `/shop/account/orders`, `/shop/account/profile`, etc. |

📖 Full table: QUICK_REFERENCE.md → "ALL SHOP ROUTES"

---

## 🔑 Key Files to Know

### Middleware Files
- `middleware/vendor_context.py` - Detects vendor from host/domain/path
- `middleware/context_middleware.py` - Determines request context type
- `middleware/theme_context.py` - Loads vendor-specific theme
- `middleware/logging_middleware.py` - Logs all requests

### Route Files
- `app/routes/shop_pages.py` - Customer shop pages
- `app/routes/vendor_pages.py` - Vendor dashboard pages
- `app/routes/admin_pages.py` - Admin pages

### Main Files
- `main.py` - FastAPI app setup & middleware chain
- `app/core/config.py` - Configuration including platform_domain
- `app/api/main.py` - API router configuration

---

## ⚡ Most Common Questions

### Q: What URL do I give to a customer?

**A:** Depends on deployment mode:
- Subdomain: `https://vendor-name.wizamart.com/shop/products`
- Custom Domain: `https://vendor-domain.com/shop/products`
- Development: `http://localhost:8000/vendor/vendor-code/shop/products`

📖 Reference: COMPLETE_SUMMARY.txt → "TL;DR"

---

### Q: How does the system know which vendor to show?

**A:** The `vendor_context_middleware` detects the vendor from:
1. Custom domain lookup (highest priority)
2. Subdomain extraction
3. URL path extraction (development)

📖 Reference: ARCHITECTURE_DIAGRAMS.txt → "VENDOR DETECTION DECISION TREE"

---

### Q: How is vendor data isolated?

**A:** Multi-layer isolation:
- Middleware sets request.state.vendor
- Database queries filtered by vendor_id
- API endpoints validate vendor ownership
- Cookies scoped to /shop path

📖 Reference: COMPLETE_SUMMARY.txt → "VENDOR ISOLATION: 4 LAYERS"

---

### Q: How are themes applied per vendor?

**A:** The `theme_context_middleware`:
1. Gets the vendor from middleware chain
2. Queries VendorTheme table by vendor_id
3. Sets request.state.theme with colors, fonts, logo
4. Template uses {{ request.state.theme.* }} to render

📖 Reference: WIZAMART_MULTITENANT_URL_GUIDE.md → "Theme Integration"

---

### Q: What happens if I visit vendor1.wizamart.com but the vendor doesn't exist?

**A:** The `vendor_context_middleware` returns None, and the request continues. The error handling depends on the route - shop routes will likely return a 404.

📖 Reference: QUICK_REFERENCE.md → "Debugging Tips"

---

### Q: Can customers access multiple vendors' shops?

**A:** Yes! They just visit different subdomains or custom domains:
- `https://acme.wizamart.com/shop/products` → ACME's store
- `https://techpro.wizamart.com/shop/products` → TechPro's store

Each is a completely separate session with different theme, products, auth token.

📖 Reference: COMPLETE_SUMMARY.txt → "KEY DIFFERENCES BETWEEN MODES"

---

## 🐛 Debugging Checklist

- [ ] Check `request.state.vendor.name` to see detected vendor
- [ ] Check `request.state.context_type` to see detected context
- [ ] Check server logs for "[OK] Vendor found via..." messages
- [ ] Test with curl: `curl -H "Host: acme.wizamart.com" http://localhost:8000/shop`
- [ ] Verify vendor exists in database
- [ ] Verify VendorTheme exists for vendor
- [ ] Check all database queries have `WHERE vendor_id = ?`

📖 Full debugging guide: QUICK_REFERENCE.md → "Debugging Tips"

---

## 🚀 Getting Started

### For Developers
1. Read: **COMPLETE_SUMMARY.txt** (5 min)
2. Read: **QUICK_REFERENCE.md** (5 min)
3. Look at: **ARCHITECTURE_DIAGRAMS.txt** (5 min)
4. Start coding!

### For DevOps/Deployment
1. Read: **WIZARD_MULTITENANT_URL_GUIDE.md** → Deployment sections
2. Read: **QUICK_REFERENCE.md** → Deployment Checklist
3. Follow checklist for your mode (Subdomain/Custom Domain)

### For Architects/Decision Makers
1. Read: **COMPLETE_SUMMARY.txt** → The Complete Picture
2. Read: **ARCHITECTURE_DIAGRAMS.txt** → All diagrams
3. Consider: Subdomain vs Custom Domain vs Path-Based

---

## 📝 Document Maintenance

This documentation covers:
- **FastAPI** - Backend framework
- **SQLAlchemy** - Database ORM
- **Jinja2** - Template engine
- **Alpine.js** - Frontend reactivity
- **Tailwind CSS** - Styling

Last Updated: November 7, 2025  
Version: Current Development  
Status: Complete & Tested

---

## 🔗 Related Code References

### Vendor Detection Logic
```python
# middleware/vendor_context.py:VendorContextManager.detect_vendor_context()
```

### Theme Loading Logic
```python
# middleware/theme_context.py:ThemeContextManager.get_vendor_theme()
```

### Context Detection Logic
```python
# middleware/context_middleware.py:ContextManager.detect_context()
```

### Shop Routes
```python
# app/routes/shop_pages.py
```

### Main App Setup
```python
# main.py - See middleware registration order
```

---

## 💡 Tips

- **Always test with multiple vendors** to ensure proper isolation
- **Check request.state.vendor** in templates to debug vendor detection
- **Monitor cross-vendor access attempts** for security
- **Use path-based routing** for local development
- **Use subdomain routing** for most production scenarios
- **Use custom domain** only when vendor pays for premium branding

---

## 📞 Quick Reference Card

```
DEPLOYMENT MODES:
  Subdomain:      https://vendor.platform.com/shop/products
  Custom Domain:  https://vendor-domain.com/shop/products
  Path-Based:     http://localhost:8000/vendor/vendor-code/shop/products

MIDDLEWARE CHAIN:
  1. vendor_context_middleware    → request.state.vendor
  2. context_middleware           → request.state.context_type
  3. theme_context_middleware     → request.state.theme

VENDOR ISOLATION:
  URL Detection → Middleware → Database Queries → API Authorization

AUTHENTICATION:
  JWT in header + customer_token cookie (path=/shop)

SHOP ROUTES:
  Public:     /shop/*, /shop/products, /shop/categories/{slug}
  Auth:       /shop/account/register, /shop/account/login
  Protected:  /shop/account/dashboard, /shop/account/orders

DATABASE:
  Every table has vendor_id for multi-tenant isolation
```

---

**Need help?** Check the relevant documentation file above, or search for your specific question using the "Most Common Questions" section.
