# Error Handling System - Flow Diagram ## Request Processing Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Incoming HTTP Request │ └─────────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Store Context Middleware (FIRST) │ │ - Detects store from domain/subdomain/path │ │ - Sets request.state.store │ │ - Sets request.state.store_context │ └─────────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Context Detection Middleware (NEW) │ │ - Detects request context type │ │ - Sets request.state.context_type │ │ • API, ADMIN, STORE_DASHBOARD, SHOP, FALLBACK │ └─────────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Route Handler Execution │ │ - Process business logic │ │ - May throw exceptions │ └─────────────────────────────────┬───────────────────────────────┘ │ ┌─────────────┴─────────────┐ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ Success │ │ Exception │ │ Response │ │ Raised │ └──────────────┘ └──────┬───────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ Exception Handler │ │ - OrionException │ │ - HTTPException │ │ - RequestValidationError │ │ - Generic Exception │ │ - 404 Not Found │ └────────────────────┬───────────────────────────────────┘ │ ┌─────────────┴────────────┐ │ │ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ │ Special Case: │ │ General Error │ │ 401 on HTML │ │ Handling │ │ → Redirect to │ │ │ │ Login │ │ │ └──────────────────┘ └─────────┬────────┘ │ ┌─────────────┴─────────────┐ │ │ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ │ API Request? │ │ HTML Request? │ │ /api/* path │ │ GET + text/html │ └────────┬─────────┘ └─────────┬────────┘ │ │ ▼ ▼ ┌──────────────────┐ ┌──────────────────────────┐ │ Return JSON │ │ Error Page Renderer │ │ Response │ │ │ │ { │ │ - Detect context type │ │ error_code, │ │ - Select template │ │ message, │ │ - Prepare data │ │ status_code │ │ - Render HTML │ │ } │ └──────────┬───────────────┘ └──────────────────┘ │ ▼ ┌──────────────────────────────┐ │ Template Selection │ │ │ │ Priority: │ │ 1. {context}/errors/{code} │ │ 2. {context}/errors/generic│ │ 3. shared/{code}-fallback │ │ 4. shared/generic-fallback │ └──────────┬───────────────────┘ │ ┌──────────────┼──────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Admin │ │ Store │ │ Storefront │ │ Error │ │ Error │ │ Error │ │ Page │ │ Page │ │ Page │ │ │ │ │ │ (Themed) │ └─────────────┘ └─────────────┘ └─────────────┘ ``` --- ## Context Detection Logic ``` ┌──────────────────────────────────────────────────────────────────┐ │ Request Arrives │ │ (host + path) │ └────────────────────────────┬─────────────────────────────────────┘ │ ▼ ┌──────────────────┐ │ Path starts │───YES───→ API Context │ with /api/ ? │ (Always JSON) └────────┬─────────┘ │ NO ▼ ┌──────────────────┐ │ Host starts │───YES───→ ADMIN Context │ with admin. │ (Admin Portal) │ OR path starts │ │ with /admin ? │ └────────┬─────────┘ │ NO ▼ ┌──────────────────┐ │ Path starts │───YES───→ STORE_DASHBOARD Context │ with /store/ ? │ (Store Management) └────────┬─────────┘ │ NO ▼ ┌──────────────────┐ │ Store object │───YES───→ SHOP Context │ in request │ (Customer Storefront) │ state? │ └────────┬─────────┘ │ NO ▼ ┌──────────────────┐ │ FALLBACK │ │ Context │ │ (Unknown) │ └──────────────────┘ ``` --- ## Template Selection Example For a 404 error in ADMIN context: ``` 1. Check: app/templates/admin/errors/404.html ✓ EXISTS → USE THIS 2. Check: app/templates/admin/errors/generic.html (skipped) 3. Check: app/templates/shared/404-fallback.html (skipped) 4. Check: app/templates/shared/generic-fallback.html (skipped) ``` For a 429 error in SHOP context (not created yet): ``` 1. Check: app/templates/storefront/errors/429.html ✗ Missing 2. Check: app/templates/storefront/errors/generic.html ✗ Missing 3. Check: app/templates/shared/429-fallback.html ✗ Missing 4. Check: app/templates/shared/generic-fallback.html ✓ EXISTS → USE THIS ``` --- ## Error Response Types ``` ┌──────────────────────────────────────────────────────────────────┐ │ Request Type │ └───────────┬─────────────┬───────────────────┬─────────────────────┘ │ │ │ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ API │ │ HTML Page │ │ 401 on HTML │ │ Request │ │ Request │ │ Page │ └──────┬─────┘ └──────┬─────┘ └──────┬───────┘ │ │ │ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ JSON │ │ Rendered │ │ Redirect │ │ Response │ │ HTML │ │ to Login │ │ │ │ Error │ │ │ │ { │ │ Page │ │ 302 Found │ │ error_code│ │ │ │ Location: │ │ message │ │ Context- │ │ /admin/login│ │ status │ │ aware │ │ /store/login│ │ details │ │ template │ │ /storefront/login │ │ } │ │ │ │ │ └────────────┘ └────────────┘ └──────────────┘ ``` --- ## Example Scenarios ### Scenario 1: API 404 Error ``` Request: GET /api/v1/admin/stores/999 Context: API Result: JSON { "error_code": "STORE_NOT_FOUND", ... } ``` ### Scenario 2: Admin Page 404 Error ``` Request: GET /admin/nonexistent Accept: text/html Context: ADMIN Result: HTML admin/errors/404.html ``` ### Scenario 3: Storefront Page 500 Error ``` Request: GET /products/123 (on store1.platform.com) Accept: text/html Context: SHOP (store detected) Result: HTML storefront/errors/500.html (with store theme) ``` ### Scenario 4: Unauthorized Access to Admin ``` Request: GET /admin/settings Accept: text/html No valid session Context: ADMIN Result: 302 Redirect to /admin/login ``` --- ## Debug Information Display ``` ┌──────────────────────────────────────────────────────────────┐ │ Error Page Display │ └──────────────────────┬───────────────────────────────────────┘ │ ┌───────────┴───────────┐ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ Admin User │ │ Other Users │ │ (Context: │ │ (Store, │ │ ADMIN) │ │ Storefront)│ └──────┬───────┘ └──────┬───────┘ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ Debug Info │ │ No Debug │ │ SHOWN: │ │ Info: │ │ • Path │ │ │ │ • Error code │ │ Only user- │ │ • Details │ │ friendly │ │ • Stack │ │ message │ └──────────────┘ └──────────────┘ ``` --- ## File Organization ``` app/ ├── exceptions/ │ ├── handler.py # Exception handlers (refactored) │ ├── error_renderer.py # NEW: Renders error pages │ └── base.py # Base exceptions │ ├── templates/ │ ├── admin/ │ │ └── errors/ # NEW: Admin error pages │ │ ├── base.html # Base template │ │ ├── 404.html # Specific errors │ │ └── generic.html # Catch-all │ │ │ ├── store/ │ │ └── errors/ # TODO: Store error pages │ │ │ ├── storefront/ │ │ └── errors/ # TODO: Storefront error pages (themed) │ │ │ └── shared/ │ └── *-fallback.html # Shared fallback error pages middleware/ ├── store_context.py # Store detection (existing) ├── context_middleware.py # NEW: Context detection └── theme_context.py # Theme loading (existing) ``` --- ## Benefits Summary ✅ **Separation of Concerns**: HTML templates separate from handler logic ✅ **Context-Aware**: Different error pages for different areas ✅ **Maintainable**: Easy to update individual error pages ✅ **Scalable**: Easy to add new contexts or error types ✅ **Professional**: Polished error pages matching area design ✅ **Flexible**: Fallback mechanism ensures errors always render ✅ **Secure**: Debug info only shown to admins ✅ **Themed**: Storefront errors can use store branding (Phase 3) --- This flow ensures that: 1. API calls ALWAYS get JSON responses 2. HTML page requests get appropriate error pages 3. Each context (admin/store/storefront) has its own error design 4. Fallback mechanism prevents broken error pages 5. 401 errors redirect to appropriate login pages