From d85a68f1753ece9dabcbff5aa61980563bac1528 Mon Sep 17 00:00:00 2001
From: Samir Boulahtit <samir.boulahtit@wizard.lu>
Date: Sat, 22 Nov 2025 23:09:08 +0100
Subject: [PATCH] docs: add error handling and error pages section to shop
 architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added comprehensive documentation for:
- Error page templates (10 templates)
- Error renderer base_url calculation
- Multi-access aware error links
- Template usage examples (bad vs good)
- How error pages work across domain/subdomain/path access

This documents the error page improvements made during shop API migration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/frontend/shop/architecture.md | 72 ++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/docs/frontend/shop/architecture.md b/docs/frontend/shop/architecture.md
index 1964689f..ac204c8f 100644
--- a/docs/frontend/shop/architecture.md
+++ b/docs/frontend/shop/architecture.md
@@ -998,6 +998,78 @@ Before Deploying:
   □ Test in production mode
 
 
+🚨 ERROR HANDLING & ERROR PAGES
+═════════════════════════════════════════════════════════════════
+
+Multi-Access Aware Error Pages:
+
+All shop error pages (404, 500, etc.) are vendor-context aware and display
+correct links based on the access method (domain, subdomain, or path-based).
+
+Error Page Templates:
+  • app/templates/shop/errors/404.html - Not Found
+  • app/templates/shop/errors/400.html - Bad Request
+  • app/templates/shop/errors/401.html - Unauthorized
+  • app/templates/shop/errors/403.html - Forbidden
+  • app/templates/shop/errors/422.html - Validation Error
+  • app/templates/shop/errors/429.html - Rate Limited
+  • app/templates/shop/errors/500.html - Server Error
+  • app/templates/shop/errors/502.html - Bad Gateway
+  • app/templates/shop/errors/base.html - Base error template
+  • app/templates/shop/errors/generic.html - Generic error
+
+Error Renderer (app/exceptions/error_renderer.py):
+
+Calculates base_url dynamically based on vendor access method:
+
+  def _get_context_data(self, request: Request, ...):
+      vendor = getattr(request.state, 'vendor', None)
+      access_method = getattr(request.state, "access_method", None)
+      vendor_context = getattr(request.state, "vendor_context", None)
+
+      # Calculate base_url for shop links
+      base_url = "/"
+      if access_method == "path" and vendor:
+          full_prefix = vendor_context.get('full_prefix', '/vendor/')
+          base_url = f"{full_prefix}{vendor.subdomain}/"
+
+      return {
+          "request": request,
+          "vendor": vendor,
+          "base_url": base_url,  # ⭐ Used in error templates
+          ...
+      }
+
+Error Template Usage:
+
+All error page links use {{ base_url }} prefix for correct routing:
+
+  {# ❌ BAD - Hardcoded links #}
+  <a href="/">Continue Shopping</a>
+  <a href="/products">View Products</a>
+
+  {# ✅ GOOD - Context-aware links #}
+  <a href="{{ base_url or '/' }}">Continue Shopping</a>
+  <a href="{{ base_url or '/' }}products">View Products</a>
+
+How It Works:
+
+1. Error occurs (404, 500, etc.)
+2. Exception handler detects shop context
+3. error_renderer.py calculates base_url from vendor_context
+4. Error template renders with correct base_url
+5. Links work for all access methods:
+   - Domain: customshop.com → base_url = "/"
+   - Subdomain: wizamart.platform.com → base_url = "/"
+   - Path: localhost/vendors/wizamart/ → base_url = "/vendors/wizamart/"
+
+Benefits:
+  ✅ Error pages work correctly regardless of access method
+  ✅ No broken links in error states
+  ✅ Consistent user experience
+  ✅ Vendor branding maintained in errors
+
+
 🔒 SECURITY
 ═════════════════════════════════════════════════════════════════