revamping documentation

2025-11-17 22:59:42 +01:00
parent bbd64a6f21
commit 807033be16
107 changed files with 11973 additions and 28413 deletions
--- a/docs/frontend/overview.md
+++ b/docs/frontend/overview.md
@@ -0,0 +1,501 @@
+# 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 |
+| 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 |
+
+### 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
+
+---
+
+## 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](shared/ui-components.md)** - Reusable UI components
+- **[Pagination System](shared/pagination.md)** - Pagination implementation
+- **[Sidebar Navigation](shared/sidebar.md)** - Sidebar setup guide
+- **[Logging System](shared/logging.md)** - Frontend logging configuration
+- **[Icons Guide](../development/icons_guide.md)** - 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](shared/ui-components.md) documentation
+5. Review the [Icons Guide](../development/icons_guide.md)
+6. Copy templates and start building!
+
+Questions? Check the detailed architecture docs or review existing implementations in the codebase.