removing legacy code on path_rewrite_middleware

docs/architecture/url-routing/overview.md

@@ -345,40 +345,38 @@ In Jinja2 template:
 
 ---
 
-## Potential Issue: Path-Based Development Mode
+## Path-Based Routing Implementation
 
-⚠️ **Current Implementation Gap:**
+**Current Solution: Double Router Mounting**
 
-The `vendor_context_middleware` sets `clean_path` for path-based URLs, but this isn't used for FastAPI routing.
-
-**Problem:**
-- Incoming: `GET http://localhost:8000/vendors/acme/shop/products`
-- Routes registered: `@router.get("/shop/products")`
-- FastAPI tries to match `/vendors/acme/shop/products` against `/shop/products`
-- Result: ❌ 404 Not Found
-
-**Solution (Recommended):**
-
-Add a path rewriting middleware in `main.py`:
+The application handles path-based routing by registering shop routes **twice** with different prefixes:
 
 ```python
-async def path_rewrite_middleware(request: Request, call_next):
-    """Rewrite path for path-based vendor routing in development mode."""
-    if hasattr(request.state, 'clean_path'):
-        # Replace request path for FastAPI routing
-        request._url = request._url.replace(path=request.state.clean_path)
-    return await call_next(request)
-
-# In main.py, add after vendor_context_middleware:
-app.middleware("http")(path_rewrite_middleware)
-```
-
-Or alternatively, mount the router twice:
-```python
+# In main.py
 app.include_router(shop_pages.router, prefix="/shop")
-app.include_router(shop_pages.router, prefix="/vendors/{vendor_code}/shop")  # Path-based development mode
+app.include_router(shop_pages.router, prefix="/vendors/{vendor_code}/shop")
 ```
 
+**How This Works:**
+
+1. **For Subdomain/Custom Domain Mode:**
+   - URL: `https://acme.wizamart.com/shop/products`
+   - Matches: First router with `/shop` prefix
+   - Route: `@router.get("/products")` → Full path: `/shop/products`
+
+2. **For Path-Based Development Mode:**
+   - URL: `http://localhost:8000/vendors/acme/shop/products`
+   - Matches: Second router with `/vendors/{vendor_code}/shop` prefix
+   - Route: `@router.get("/products")` → Full path: `/vendors/{vendor_code}/shop/products`
+   - Bonus: `vendor_code` available as path parameter!
+
+**Benefits:**
+- ✅ No middleware complexity or path manipulation
+- ✅ FastAPI native routing
+- ✅ Explicit and maintainable
+- ✅ Vendor code accessible via path parameter when needed
+- ✅ Both deployment modes supported cleanly
+
 ---
 
 ## Authentication in Multi-Tenant Shop