╔══════════════════════════════════════════════════════════════════╗
║         VENDOR ADMIN FRONTEND ARCHITECTURE OVERVIEW              ║
║         Alpine.js + Jinja2 + Tailwind CSS                        ║
╚══════════════════════════════════════════════════════════════════╝

📦 WHAT IS THIS?
═════════════════════════════════════════════════════════════════

Vendor admin frontend provides vendors with a complete management
interface for their store. Built with:
  ✅ Jinja2 Templates (server-side rendering)
  ✅ Alpine.js (client-side reactivity)
  ✅ Tailwind CSS (utility-first styling)
  ✅ FastAPI (backend routes)


🎯 KEY PRINCIPLES
═════════════════════════════════════════════════════════════════

1. Minimal Server-Side Rendering
   • Routes handle authentication + template rendering
   • NO database queries in route handlers
   • ALL data loaded client-side via JavaScript

2. Component-Based Architecture
   • Base template with shared layout
   • Reusable partials (header, sidebar, etc.)
   • Page-specific templates extend base

3. Progressive Enhancement
   • Works without JavaScript (basic HTML)
   • JavaScript adds interactivity
   • Graceful degradation

4. API-First Data Loading
   • All data from REST APIs
   • Client-side state management
   • Real-time updates possible


📁 FILE STRUCTURE
═════════════════════════════════════════════════════════════════

app/
├── templates/vendor/
│   ├── base.html                    ← Base template (layout)
│   ├── login.html                   ← Public login page
│   ├── dashboard.html               ← Authenticated pages
│   ├── products.html
│   ├── orders.html
│   ├── customers.html
│   ├── inventory.html
│   ├── marketplace.html
│   ├── team.html
│   ├── settings.html
│   ├── profile.html
│   ├── partials/                    ← Reusable components
│   │   ├── header.html              ← Top navigation
│   │   ├── sidebar.html             ← Main navigation
│   │   ├── vendor_info.html         ← Vendor details card
│   │   └── notifications.html       ← Toast notifications
│   └── errors/                      ← Error pages
│
├── static/vendor/
│   ├── css/
│   │   ├── tailwind.output.css      ← Generated Tailwind
│   │   └── vendor.css               ← Custom styles
│   ├── js/
│   │   ├── init-alpine.js           ← Alpine.js base data
│   │   ├── dashboard.js             ← Dashboard logic
│   │   ├── products.js              ← Products page logic
│   │   ├── orders.js                ← Orders page logic
│   │   ├── customers.js             ← Customers page logic
│   │   ├── inventory.js             ← Inventory page logic
│   │   ├── marketplace.js           ← Marketplace page logic
│   │   ├── team.js                  ← Team page logic
│   │   └── settings.js              ← Settings page logic
│   └── img/
│       ├── login-office.jpeg
│       └── login-office-dark.jpeg
│
├── static/shared/                   ← Shared across all areas
│   ├── js/
│   │   ├── log-config.js            ← Logging setup
│   │   ├── icons.js                 ← Icon registry
│   │   ├── utils.js                 ← Utility functions
│   │   └── api-client.js            ← API wrapper
│   └── css/
│       └── base.css                 ← Global styles
│
└── routes/
    └── vendor_pages.py              ← Route handlers


🏗️  ARCHITECTURE LAYERS
═════════════════════════════════════════════════════════════════

Layer 1: Routes (FastAPI)
  ↓
Layer 2: Templates (Jinja2)
  ↓
Layer 3: JavaScript (Alpine.js)
  ↓
Layer 4: API (REST endpoints)
  ↓
Layer 5: Database


Layer 1: ROUTES (FastAPI)
──────────────────────────────────────────────────────────────────
Purpose: Authentication + Template Rendering
Location: app/routes/vendor_pages.py

Example:
  @router.get("/{vendor_code}/dashboard")
  async def vendor_dashboard_page(
      request: Request,
      vendor_code: str = Path(..., description="Vendor code"),
      current_user: User = Depends(get_current_vendor_from_cookie_or_header)
  ):
      return templates.TemplateResponse(
          "vendor/dashboard.html",
          {
              "request": request,
              "user": current_user,
              "vendor_code": vendor_code
          }
      )

Responsibilities:
  ✅ Verify authentication
  ✅ Extract route parameters
  ✅ Render template
  ❌ NO database queries
  ❌ NO business logic


Layer 2: TEMPLATES (Jinja2)
──────────────────────────────────────────────────────────────────
Purpose: HTML Structure + Server-Side Data
Location: app/templates/vendor/

Template Hierarchy:
  base.html (layout)
    ↓
  dashboard.html (page)
    ↓
  partials/sidebar.html (components)

Example:
  {% extends "vendor/base.html" %}
  {% block title %}Dashboard{% endblock %}
  {% block alpine_data %}vendorDashboard(){% endblock %}
  {% block content %}
    <div x-show="loading">Loading...</div>
    <div x-show="!loading" x-text="stats.products_count"></div>
  {% endblock %}

Key Features:
  ✅ Template inheritance
  ✅ Server-side variables (user, vendor_code)
  ✅ Include partials
  ✅ Block overrides


Layer 3: JAVASCRIPT (Alpine.js)
──────────────────────────────────────────────────────────────────
Purpose: Client-Side Interactivity + Data Loading
Location: app/static/vendor/js/

Example:
  function vendorDashboard() {
      return {
          loading: false,
          stats: {},
          
          async init() {
              await this.loadStats();
          },
          
          async loadStats() {
              this.loading = true;
              try {
                  this.stats = await apiClient.get(
                      `/api/v1/vendor/dashboard/stats`
                  );
              } finally {
                  this.loading = false;
              }
          }
      };
  }

Responsibilities:
  ✅ Load data from API
  ✅ Manage UI state
  ✅ Handle user interactions
  ✅ Update DOM reactively


Layer 4: API (REST)
──────────────────────────────────────────────────────────────────
Purpose: Business Logic + Data Access
Location: app/api/v1/vendor/*.py

Example Endpoints:
  GET    /api/v1/vendor/dashboard/stats
  GET    /api/v1/vendor/products
  POST   /api/v1/vendor/products
  PUT    /api/v1/vendor/products/{id}
  DELETE /api/v1/vendor/products/{id}


🔄 DATA FLOW
═════════════════════════════════════════════════════════════════

Page Load Flow:
──────────────────────────────────────────────────────────────────
  1. User → GET /vendor/ACME/dashboard
  2. FastAPI → Check authentication
  3. FastAPI → Render template with minimal context
  4. Browser → Load HTML + CSS + JS
  5. Alpine.js → init() executes
  6. JavaScript → API call for data
  7. API → Return JSON data
  8. Alpine.js → Update reactive state
  9. Browser → DOM updates automatically

User Interaction Flow:
──────────────────────────────────────────────────────────────────
  1. User → Click "Add Product"
  2. Alpine.js → openCreateModal()
  3. Alpine.js → Show modal
  4. User → Fill form + submit
  5. Alpine.js → POST to API
  6. API → Create product + return
  7. Alpine.js → Update local state
  8. Browser → DOM updates automatically
  9. Alpine.js → Close modal


🎨 STYLING SYSTEM
═════════════════════════════════════════════════════════════════

Tailwind CSS Utility Classes:
  • Responsive: sm:, md:, lg:, xl:
  • Dark mode: dark:bg-gray-800
  • Hover: hover:bg-purple-700
  • Focus: focus:outline-none
  • Transitions: transition-colors duration-150

Custom CSS Variables (vendor/css/vendor.css):
  --color-primary: #7c3aed (purple-600)
  --color-accent: #ec4899 (pink-500)
  --color-success: #10b981 (green-500)
  --color-warning: #f59e0b (yellow-500)
  --color-danger: #ef4444 (red-500)


🔐 AUTHENTICATION
═════════════════════════════════════════════════════════════════

Auth Flow:
  1. Login → POST /api/v1/vendor/auth/login
  2. API → Return JWT token + set vendor_token cookie
  3. JavaScript → Token stored in localStorage (optional)
  4. Cookie → Automatically sent with page requests
  5. API Client → Add Authorization header for API calls
  6. Routes → Verify with get_current_vendor_from_cookie_or_header

Token Storage:
  • HttpOnly Cookie: vendor_token (path=/vendor) - For page navigation
  • LocalStorage: Optional, for JavaScript API calls
  • Dual authentication: Supports both cookie and header-based auth

Protected Routes:
  • All /vendor/{code}/* routes (except /login)
  • Require valid JWT token (cookie or header)
  • Redirect to login if unauthorized

Public Routes:
  • /vendor/{code}/login
  • No authentication required
  • Uses get_current_vendor_optional to redirect if already logged in


📱 RESPONSIVE DESIGN
═════════════════════════════════════════════════════════════════

Breakpoints (Tailwind):
  • sm: 640px  (mobile landscape)
  • md: 768px  (tablet)
  • lg: 1024px (desktop)
  • xl: 1280px (large desktop)

Mobile-First Approach:
  • Base styles for mobile
  • Add complexity for larger screens
  • Hide sidebar on mobile
  • Stack cards vertically

Example:
  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4">
    <!-- 1 column mobile, 2 tablet, 4 desktop -->
  </div>


🌙 DARK MODE
═════════════════════════════════════════════════════════════════

Implementation:
  1. Alpine.js state: dark: boolean
  2. HTML class binding: :class="{ 'dark': dark }"
  3. Tailwind variants: dark:bg-gray-800
  4. LocalStorage: persist preference

Toggle:
  toggleTheme() {
      this.dark = !this.dark;
      localStorage.setItem('theme', this.dark ? 'dark' : 'light');
  }


🔧 COMPONENT PATTERNS
═════════════════════════════════════════════════════════════════

Pattern 1: DATA TABLE
──────────────────────────────────────────────────────────────────
Use For: Lists (products, orders, customers)

Structure:
  • Loading state
  • Error state
  • Empty state
  • Data rows
  • Actions column
  • Pagination

Key Features:
  ✅ Server-side pagination
  ✅ Filtering
  ✅ Sorting
  ✅ Responsive


Pattern 2: DASHBOARD
──────────────────────────────────────────────────────────────────
Use For: Overview pages with stats

Structure:
  • Stats cards grid
  • Recent activity list
  • Quick actions

Key Features:
  ✅ Real-time stats
  ✅ Charts (optional)
  ✅ Refresh button


Pattern 3: FORM MODAL
──────────────────────────────────────────────────────────────────
Use For: Create/Edit operations

Structure:
  • Modal overlay
  • Form fields
  • Validation
  • Save/Cancel buttons

Key Features:
  ✅ Client-side validation
  ✅ Error messages
  ✅ Loading state
  ✅ Escape to close


Pattern 4: DETAIL PAGE
──────────────────────────────────────────────────────────────────
Use For: Single item view (product detail, order detail)

Structure:
  • Header with actions
  • Info cards
  • Related data tabs

Key Features:
  ✅ Edit inline
  ✅ Related items
  ✅ Status badges


🔄 STATE MANAGEMENT
═════════════════════════════════════════════════════════════════

Alpine.js Reactive State:

Global State (init-alpine.js):
  • dark mode
  • current user
  • vendor info
  • menu state

Page State (e.g., products.js):
  • items array
  • loading boolean
  • error string
  • filters object
  • pagination object

State Updates:
  • Direct assignment: this.items = []
  • Alpine auto-updates DOM
  • No manual DOM manipulation


📡 API CLIENT
═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/api-client.js

Usage:
  const data = await apiClient.get('/endpoint');
  await apiClient.post('/endpoint', { data });
  await apiClient.put('/endpoint/{id}', { data });
  await apiClient.delete('/endpoint/{id}');

Features:
  ✅ Automatic auth headers
  ✅ Error handling
  ✅ JSON parsing
  ✅ Retry logic


🐛 LOGGING
═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/log-config.js

Usage:
  logInfo('Operation completed', data);
  logError('Operation failed', error);
  logDebug('Debug info', context);
  logWarn('Warning message');

Levels:
  • INFO: General information
  • ERROR: Errors and failures
  • DEBUG: Detailed debugging
  • WARN: Warnings


🎭 ICONS
═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/icons.js

Usage:
  <span x-html="$icon('home', 'w-5 h-5')"></span>
  <span x-html="$icon('user', 'w-4 h-4 text-blue-500')"></span>

Available Icons:
  • home, dashboard, settings
  • user, users, user-group
  • shopping-bag, shopping-cart
  • cube, download, upload
  • plus, minus, x
  • pencil, trash, eye
  • check, exclamation
  • chevron-left, chevron-right
  • spinner (for loading)


🚀 PERFORMANCE
═════════════════════════════════════════════════════════════════

Optimization Techniques:

1. Template Caching
   • Base template cached by FastAPI
   • Reduces rendering time

2. Lazy Loading
   • Data loaded after page render
   • Progressive content display

3. Debouncing
   • Search inputs debounced
   • Reduces API calls

4. Pagination
   • Server-side pagination
   • Load only needed data

5. CDN Assets with Fallback
   • Tailwind CSS from CDN (fallback to local)
   • Alpine.js from CDN (fallback to local)
   • Works offline and in restricted networks
   • See: [CDN Fallback Strategy](../cdn-fallback-strategy.md)


🧪 TESTING APPROACH
═════════════════════════════════════════════════════════════════

Unit Tests:
  • Route handlers (Python)
  • API endpoints (Python)
  • Utility functions (JavaScript)

Integration Tests:
  • Full page load
  • Data fetching
  • Form submission
  • Authentication flow

Manual Testing:
  • Visual regression
  • Cross-browser
  • Mobile devices
  • Dark mode


🔒 SECURITY
═════════════════════════════════════════════════════════════════

Best Practices:

1. Authentication
   ✅ JWT tokens
   ✅ HttpOnly cookies option
   ✅ Token expiration

2. Authorization
   ✅ Route-level checks
   ✅ API-level validation
   ✅ Vendor-scoped data

3. Input Validation
   ✅ Client-side validation
   ✅ Server-side validation
   ✅ XSS prevention

4. CSRF Protection
   ✅ Token-based
   ✅ SameSite cookies


📊 PAGE-BY-PAGE BREAKDOWN
═════════════════════════════════════════════════════════════════

/vendor/{code}/dashboard
──────────────────────────────────────────────────────────────────
Purpose: Overview of vendor operations
Components:
  • Stats cards (products, orders, revenue)
  • Recent orders table
  • Quick actions
Data Sources:
  • GET /api/v1/vendor/dashboard/stats
  • GET /api/v1/vendor/orders?limit=5

/vendor/{code}/products
──────────────────────────────────────────────────────────────────
Purpose: Manage product catalog
Components:
  • Product list table
  • Search and filters
  • Create/Edit modal
Data Sources:
  • GET /api/v1/vendor/products
  • POST /api/v1/vendor/products
  • PUT /api/v1/vendor/products/{id}

/vendor/{code}/orders
──────────────────────────────────────────────────────────────────
Purpose: View and manage orders
Components:
  • Orders table
  • Status filters
  • Order detail modal
Data Sources:
  • GET /api/v1/vendor/orders
  • PUT /api/v1/vendor/orders/{id}

/vendor/{code}/customers
──────────────────────────────────────────────────────────────────
Purpose: Customer management
Components:
  • Customer list
  • Search functionality
  • Customer detail view
Data Sources:
  • GET /api/v1/vendor/customers

/vendor/{code}/inventory
──────────────────────────────────────────────────────────────────
Purpose: Track stock levels
Components:
  • Inventory table
  • Stock adjustment modal
  • Low stock alerts
Data Sources:
  • GET /api/v1/vendor/inventory
  • PUT /api/v1/vendor/inventory/{id}

/vendor/{code}/marketplace
──────────────────────────────────────────────────────────────────
Purpose: Import products from marketplace
Components:
  • Import job list
  • Product browser
  • Import wizard
Data Sources:
  • GET /api/v1/vendor/marketplace/jobs
  • POST /api/v1/vendor/marketplace/import

/vendor/{code}/team
──────────────────────────────────────────────────────────────────
Purpose: Manage team members
Components:
  • Team member list
  • Role management
  • Invitation form
Data Sources:
  • GET /api/v1/vendor/team
  • POST /api/v1/vendor/team/invite

/vendor/{code}/profile
──────────────────────────────────────────────────────────────────
Purpose: Manage vendor profile and branding
Components:
  • Profile information form
  • Branding settings
  • Business details
Data Sources:
  • GET /api/v1/vendor/profile
  • PUT /api/v1/vendor/profile

/vendor/{code}/settings
──────────────────────────────────────────────────────────────────
Purpose: Configure vendor settings
Components:
  • Settings tabs
  • Form sections
  • Save buttons
Data Sources:
  • GET /api/v1/vendor/settings
  • PUT /api/v1/vendor/settings


🎓 LEARNING PATH
═════════════════════════════════════════════════════════════════

For New Developers:

1. Understand Architecture (1 hour)
   → Read this document
   → Review file structure
   → Examine base template

2. Study Existing Page (2 hours)
   → Open dashboard.html
   → Open dashboard.js
   → Trace data flow

3. Create Simple Page (4 hours)
   → Copy templates
   → Modify for new feature
   → Test thoroughly

4. Add Complex Feature (1 day)
   → Forms with validation
   → Modal dialogs
   → API integration

5. Master Patterns (1 week)
   → All common patterns
   → Error handling
   → Performance optimization


🔄 DEPLOYMENT CHECKLIST
═════════════════════════════════════════════════════════════════

Before Deploying:
  □ Build Tailwind CSS
  □ Minify JavaScript
  □ Test all routes
  □ Verify authentication
  □ Check mobile responsive
  □ Test dark mode
  □ Validate API endpoints
  □ Review error handling
  □ Check console for errors
  □ Test in production mode


📚 REFERENCE LINKS
═════════════════════════════════════════════════════════════════

Documentation:
  • Alpine.js: https://alpinejs.dev/
  • Tailwind CSS: https://tailwindcss.com/
  • Jinja2: https://jinja.palletsprojects.com/
  • FastAPI: https://fastapi.tiangolo.com/

Internal Docs:
  • Page Template Guide: FRONTEND_VENDOR_ALPINE_PAGE_TEMPLATE.md
  • API Documentation: API_REFERENCE.md
  • Database Schema: DATABASE_SCHEMA.md


══════════════════════════════════════════════════════════════════
                    VENDOR ADMIN ARCHITECTURE
           Modern, Maintainable, and Developer-Friendly
══════════════════════════════════════════════════════════════════