orion/docs/frontend/overview.md

Frontend Architecture Overview

Version: 1.0 Last Updated: November 2025 Audience: Frontend Developers

---

What is This Document?

This document provides a comprehensive overview of the Wizamart frontend architecture, covering all three distinct frontend applications and the shared design patterns that ensure consistency, maintainability, and developer productivity across the entire platform.

This serves as the introduction to three detailed architecture documents:

1. Admin Frontend Architecture
2. Vendor Frontend Architecture
3. Shop Frontend Architecture

---

Platform Overview

Wizamart is a multi-tenant e-commerce marketplace platform with three distinct frontend applications, each serving different user groups:

┌─────────────────────────────────────────────────────────────────┐
│                                                                  │
│  ┌──────────────┐        ┌──────────────┐      ┌────────────┐  │
│  │    ADMIN     │        │    VENDOR    │      │    SHOP    │  │
│  │   FRONTEND   │        │   FRONTEND   │      │  FRONTEND  │  │
│  └──────────────┘        └──────────────┘      └────────────┘  │
│         │                        │                     │         │
│         ├────────────────────────┴─────────────────────┤         │
│         │                                              │         │
│         │           SHARED ARCHITECTURE                │         │
│         │           • Alpine.js                        │         │
│         │           • Jinja2 Templates                 │         │
│         │           • Tailwind CSS                     │         │
│         │           • FastAPI Backend                  │         │
│         │           • Design Patterns                  │         │
│         │                                              │         │
│         └──────────────────────────────────────────────┘         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Three Frontends Explained

1. Admin Frontend

Purpose: Platform administration and control Users: Platform administrators Access: /admin/* Auth: Admin role required (is_admin=True)

Key Features:

• Vendor management (create, verify, suspend)
• User management (roles, permissions)
• Platform-wide analytics and monitoring
• Theme customization for vendors
• Import job monitoring
• Audit log viewing
• System settings and configuration

UI Theme: Windmill Dashboard (professional admin UI) Colors: Purple (#7c3aed) primary

Pages:

• /admin/dashboard
• /admin/vendors
• /admin/vendors/{code}/edit
• /admin/vendors/{code}/theme
• /admin/users
• /admin/products
• /admin/orders
• /admin/import-jobs
• /admin/audit-logs
• /admin/settings

---

2. Vendor Frontend

Purpose: Vendor shop management and operations Users: Vendor owners and their team members Access: /vendor/{vendor_code}/* Auth: Vendor role required + vendor ownership

Key Features:

• Product catalog management
• Inventory tracking
• Order management
• Customer management
• Marketplace imports (Amazon, eBay, etc.)
• Shop analytics and reports
• Team member management
• Shop settings

UI Theme: Windmill Dashboard (professional admin UI) Colors: Purple (#7c3aed) primary

Pages:

• /vendor/{code}/dashboard
• /vendor/{code}/products
• /vendor/{code}/inventory
• /vendor/{code}/orders
• /vendor/{code}/customers
• /vendor/{code}/marketplace
• /vendor/{code}/analytics
• /vendor/{code}/team
• /vendor/{code}/settings

---

3. Shop Frontend

Purpose: Customer-facing e-commerce storefront Users: Customers and visitors Access: Vendor-specific domains or subdomains Auth: Optional (guest checkout supported)

Key Features:

• Product browsing and search
• Shopping cart management
• Checkout and payment
• Order tracking
• Customer account (optional)
• Wishlist (optional)
• Product reviews (optional)
• Multi-theme system (vendor branding)

UI Theme: Custom per vendor (multi-theme system) Colors: Vendor-specific via CSS variables

Special Features:

• Vendor Context Middleware (domain → vendor detection)
• Theme Context Middleware (loads vendor theme)
• CSS Variables for dynamic theming
• Client-side cart (localStorage)

Pages:

• / (homepage)
• /products (catalog)
• /products/{id} (product detail)
• /category/{slug} (category browse)
• /search (search results)
• /cart (shopping cart)
• /checkout (checkout flow)
• /account (customer account)
• /orders (order history)
• /about (about vendor)
• /contact (contact form)

---

Shared Technology Stack

All three frontends share the same core technologies:

Layer	Technology	Purpose
Backend	FastAPI	REST API + routing
Templates	Jinja2	Server-side rendering
Interactivity	Alpine.js 3.x	Client-side reactivity
Styling	Tailwind CSS 2.x	Utility-first CSS (CDN + fallback)
Icons	Heroicons	SVG icon system
HTTP Client	Fetch API	API requests
State Management	Alpine.js reactive	No external state lib
Logging	Custom LogConfig	Centralized logging
Error Handling	Custom exceptions	Structured errors
Asset Loading	CDN with fallback	Offline support - Details

Why This Stack?

• ✅ Minimal JavaScript complexity (no React/Vue build process)
• ✅ Server-side rendering for SEO
• ✅ Progressive enhancement (works without JS)
• ✅ Fast development iteration
• ✅ Small bundle sizes
• ✅ Easy to learn and maintain
• ✅ Python developers can contribute to frontend
• ✅ Works offline with CDN fallback (see CDN Fallback Strategy)

---

Architecture Philosophy

1. API-First Design

• Routes only render templates (no business logic)
• ALL data loaded client-side via REST APIs
• Clear separation: pages.py (templates) vs other API files
• Enables future mobile apps or SPA migrations

2. Progressive Enhancement

• HTML works without JavaScript (basic functionality)
• JavaScript enhances experience (filters, live updates)
• Graceful degradation for older browsers
• Accessible by default

3. Component-Based Templates

• Base templates provide layout
• Pages extend base templates
• Partials for reusable components
• Block overrides for customization

4. Centralized Design Patterns

• Shared utilities (logging, API client, utils)
• Consistent error handling across frontends
• Standardized state management patterns
• Common UI components and patterns

5. Developer Experience

• Copy-paste templates for new pages
• Consistent patterns reduce cognitive load
• Comprehensive documentation
• Clear file organization

---

File Organization

The project follows a clear, frontend-specific organization:

app/
├── templates/
│   ├── admin/              ← Admin frontend templates
│   │   ├── base.html
│   │   ├── dashboard.html
│   │   └── partials/
│   ├── vendor/             ← Vendor frontend templates
│   │   ├── base.html
│   │   ├── dashboard.html
│   │   └── partials/
│   └── shop/               ← Shop frontend templates
│       ├── base.html
│       ├── home.html
│       └── partials/
│
├── static/
│   ├── admin/              ← Admin-specific assets
│   │   ├── css/
│   │   ├── js/
│   │   └── img/
│   ├── vendor/             ← Vendor-specific assets
│   │   ├── css/
│   │   ├── js/
│   │   └── img/
│   ├── shop/               ← Shop-specific assets
│   │   ├── css/
│   │   ├── js/
│   │   └── img/
│   └── shared/             ← Shared across all frontends
│       ├── js/
│       │   ├── log-config.js       ← Centralized logging
│       │   ├── api-client.js       ← HTTP client wrapper
│       │   ├── icons.js            ← Icon registry
│       │   └── utils.js            ← Utility functions
│       └── css/
│
├── api/v1/
│   ├── admin/              ← Admin API endpoints
│   │   ├── pages.py        ← Routes (templates only)
│   │   ├── vendors.py      ← Business logic
│   │   ├── users.py
│   │   └── ...
│   ├── vendor/             ← Vendor API endpoints
│   │   ├── pages.py
│   │   ├── products.py
│   │   └── ...
│   └── shop/               ← Shop API endpoints
│       ├── pages.py
│       ├── products.py
│       └── ...
│
└── exceptions/             ← Custom exception classes
    ├── base.py             ← Base exception classes
    ├── admin.py            ← Admin-specific exceptions
    ├── shop.py             ← Shop-specific exceptions
    ├── product.py          ← Product exceptions
    └── handler.py          ← Exception handler setup

---

Request Flow

Page Load Flow

1. Browser Request
2. FastAPI Route Handler (pages.py)
   • Verify authentication
   • Extract route parameters
   • Render Jinja2 template
3. Template Rendering
   • Extend base template
   • Include partials
   • Inject server-side data (user, vendor, theme)
4. Browser Receives HTML
   • Load CSS (Tailwind)
   • Load JavaScript (Alpine.js, page scripts)
5. Alpine.js Initialization
   • x-data component initialized
   • ...data() spreads base state
   • init() method runs
   • Initialization guard checked
6. Client-Side Data Loading
   • JavaScript calls REST API
   • apiClient handles request
   • JSON response received
7. Reactive Updates
   • Alpine.js updates reactive state
   • DOM automatically updates
   • Page fully interactive

User Interaction Flow

1. User Action (click, input, etc.)
2. Alpine.js Event Handler
   • @click, @input, @change, etc.
   • Calls component method
3. Business Logic
   • Validate input
   • Update local state
   • Call API if needed
4. API Request (if needed)
   • apiClient.post/put/delete
   • Automatic error handling
   • Logging
5. Update State
   • Modify reactive data
   • Alpine.js watches changes
6. DOM Updates
   • Automatic reactive updates
   • No manual DOM manipulation
7. User Feedback
   • Toast notification
   • Loading indicator removed
   • Success/error message

---

Core Design Patterns

For detailed information about the design patterns used across all frontends, see:

• Shared UI Components - Reusable UI components
• Pagination System - Pagination implementation
• Sidebar Navigation - Sidebar setup guide
• Logging System - Frontend logging configuration
• Icons Guide - Icon system usage

---

Security Patterns

Authentication & Authorization

1. JWT Tokens

   • Stored in localStorage
   • Automatically sent with API requests
   • Expiration handling

2. Role-Based Access

   • Admin: Full platform access
   • Vendor: Limited to own shop
   • Customer: Public + account access

3. Route Protection

   • FastAPI dependencies verify auth
   • Middleware for vendor context
   • Automatic redirects to login

Input Validation

1. Client-Side (Alpine.js)

   • Immediate feedback
   • Better UX
   • Reduces server load

2. Server-Side (Pydantic)

   • Security boundary
   • Type validation
   • Cannot be bypassed

3. Both Required

   • Client-side for UX
   • Server-side for security

XSS Prevention

• Jinja2 auto-escapes by default
• Use | safe only when necessary
• Sanitize user content

CSRF Protection

• Token-based (if using forms)
• SameSite cookies
• API uses Bearer tokens (CSRF-safe)

---

Learning Path

For New Developers

Week 1: Foundation

• Day 1-2: Read this overview document
• Day 3-4: Study one detailed architecture doc (start with admin)
• Day 5: Review shared design patterns

Week 2: Hands-On

• Day 1-2: Examine existing dashboard.js (best example)
• Day 3-4: Copy template and create simple page
• Day 5: Test and understand data flow

Week 3: Patterns

• Day 1: Practice base layout inheritance
• Day 2: Implement initialization guards
• Day 3: Use centralized logging
• Day 4: Work with API client
• Day 5: Handle errors properly

Week 4: Advanced

• Day 1-2: Create complex page with filters/pagination
• Day 3: Implement modal forms
• Day 4: Add dark mode support
• Day 5: Review and refactor

After 1 Month:

• ✅ Understand all three frontends
• ✅ Can create new pages independently
• ✅ Follow all design patterns
• ✅ Debug issues effectively
• ✅ Contribute to architecture improvements

---

Development Checklist

Before Creating New Page

• □ Read relevant architecture document
• □ Review page template guide
• □ Study similar existing page
• □ Identify which patterns to use

While Developing

• □ Use ...data() for base inheritance
• □ Add initialization guard
• □ Set currentPage identifier
• □ Use lowercase apiClient
• □ Use centralized logger
• □ Handle errors gracefully
• □ Add loading states
• □ Support dark mode

Before Committing

• □ No console errors
• □ Initialization guard works
• □ Dark mode works
• □ Mobile responsive
• □ API errors handled
• □ No duplicate API calls
• □ Logging consistent
• □ Code matches patterns

---

Benefits of This Architecture

For Developers

• ✅ Copy-paste templates reduce development time
• ✅ Consistent patterns reduce cognitive load
• ✅ Centralized utilities eliminate duplication
• ✅ Clear documentation speeds onboarding
• ✅ Shared patterns enable code reuse

For The Platform

• ✅ Maintainable codebase
• ✅ Consistent user experience
• ✅ Easier debugging
• ✅ Faster feature development
• ✅ Scalable architecture

For Users

• ✅ Consistent UI/UX
• ✅ Fast page loads
• ✅ Reliable functionality
• ✅ Professional appearance
• ✅ Works on all devices

---

Next Steps

1. Read the detailed architecture document for the frontend you're working on (Admin, Vendor, or Shop)
2. Study the page template guide for that frontend
3. Review existing code examples (dashboard.js is the best)
4. Check the Shared Components documentation
5. Review the Icons Guide
6. Copy templates and start building!

Questions? Check the detailed architecture docs or review existing implementations in the codebase.