sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revamping documentation

Browse Source
This commit is contained in:
Samir Boulahtit
2025-11-17 22:59:42 +01:00
parent bbd64a6f21
commit 807033be16
107 changed files with 11973 additions and 28413 deletions
Download Patch File Download Diff File Expand all files Collapse all files

808
docs/frontend/shop/architecture.md Normal file
View File

@@ -0,0 +1,808 @@
╔══════════════════════════════════════════════════════════════════╗
║ SHOP FRONTEND ARCHITECTURE OVERVIEW ║
║ Alpine.js + Jinja2 + Tailwind CSS + Multi-Theme ║
╚══════════════════════════════════════════════════════════════════╝
📦 WHAT IS THIS?
═════════════════════════════════════════════════════════════════
Customer-facing shop frontend provides visitors with a branded
e-commerce experience unique to each vendor. Built with:
✅ Jinja2 Templates (server-side rendering)
✅ Alpine.js (client-side reactivity)
✅ Tailwind CSS (utility-first styling)
✅ Multi-Theme System (vendor branding)
✅ FastAPI (backend routes)
🎯 KEY PRINCIPLES
═════════════════════════════════════════════════════════════════
1. Theme-First Design
• Each vendor has unique colors, fonts, logos
• CSS variables for dynamic theming
• Custom CSS support per vendor
• Dark mode with vendor colors
2. Progressive Enhancement
• Works without JavaScript (basic HTML)
• JavaScript adds cart, search, filters
• Graceful degradation for older browsers
3. API-First Data Loading
• All products from REST APIs
• Client-side cart management
• Real-time stock updates
• Search and filtering
4. Responsive & Mobile-First
• Mobile-first Tailwind approach
• Touch-friendly interactions
• Optimized images
• Fast page loads
📁 FILE STRUCTURE
═════════════════════════════════════════════════════════════════
app/
├── templates/shop/
│ ├── base.html ← Base template (layout)
│ ├── home.html ← Homepage / product grid
│ ├── product-detail.html ← Single product page
│ ├── cart.html ← Shopping cart
│ ├── checkout.html ← Checkout flow
│ ├── search.html ← Search results
│ ├── category.html ← Category browse
│ ├── about.html ← About the shop
│ ├── contact.html ← Contact form
│ └── partials/ ← Reusable components
│ ├── product-card.html ← Product display card
│ ├── cart-item.html ← Cart item row
│ ├── search-modal.html ← Search overlay
│ └── filters.html ← Product filters
│
├── static/shop/
│ ├── css/
│ │ ├── shop.css ← Shop-specific styles
│ │ └── themes/ ← Optional theme stylesheets
│ │ ├── modern.css
│ │ ├── minimal.css
│ │ └── elegant.css
│ ├── js/
│ │ ├── shop-layout.js ← Base shop functionality
│ │ ├── home.js ← Homepage logic
│ │ ├── product-detail.js ← Product page logic
│ │ ├── cart.js ← Cart management
│ │ ├── checkout.js ← Checkout flow
│ │ ├── search.js ← Search functionality
│ │ └── filters.js ← Product filtering
│ └── img/
│ ├── placeholder-product.png
│ └── empty-cart.svg
│
├── 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
│
└── api/v1/shop/
└── pages.py ← Route handlers
🏗️ ARCHITECTURE LAYERS
═════════════════════════════════════════════════════════════════
Layer 1: Routes (FastAPI)
↓
Layer 2: Middleware (Vendor + Theme Detection)
↓
Layer 3: Templates (Jinja2)
↓
Layer 4: JavaScript (Alpine.js)
↓
Layer 5: API (REST endpoints)
↓
Layer 6: Database
Layer 1: ROUTES (FastAPI)
──────────────────────────────────────────────────────────────────
Purpose: Vendor Detection + Template Rendering
Location: app/api/v1/shop/pages.py
Example:
@router.get("/")
async def shop_home(
request: Request,
db: Session = Depends(get_db)
):
vendor = request.state.vendor # From middleware
theme = request.state.theme # From middleware
return templates.TemplateResponse(
"shop/home.html",
{
"request": request,
"vendor": vendor,
"theme": theme,
}
)
Responsibilities:
✅ Access vendor from middleware
✅ Access theme from middleware
✅ Render template
❌ NO database queries (data loaded client-side)
❌ NO business logic
Layer 2: MIDDLEWARE
──────────────────────────────────────────────────────────────────
Purpose: Vendor & Theme Identification
Two middleware components work together:
1. Vendor Context Middleware
• Detects vendor from domain/subdomain
• Sets request.state.vendor
• Returns 404 if vendor not found
2. Theme Context Middleware
• Loads theme for detected vendor
• Sets request.state.theme
• Falls back to default theme
Order matters:
vendor_context_middleware → theme_context_middleware
Layer 3: TEMPLATES (Jinja2)
──────────────────────────────────────────────────────────────────
Purpose: HTML Structure + Vendor Branding
Location: app/templates/shop/
Template Hierarchy:
base.html (layout + theme injection)
↓
home.html (product grid)
↓
partials/product-card.html (components)
Example:
{% extends "shop/base.html" %}
{% block title %}{{ vendor.name }}{% endblock %}
{% block alpine_data %}shopHome(){% endblock %}
{% block content %}
<div x-show="loading">Loading products...</div>
<div x-show="!loading" class="grid grid-cols-1 md:grid-cols-4 gap-6">
<template x-for="product in products" :key="product.id">
<!-- Product card -->
</template>
</div>
{% endblock %}
Key Features:
✅ Theme CSS variables injection
✅ Vendor logo (light/dark mode)
✅ Custom CSS from theme
✅ Social links from theme
✅ Dynamic favicon
Layer 4: JAVASCRIPT (Alpine.js)
──────────────────────────────────────────────────────────────────
Purpose: Client-Side Interactivity + Cart + Search
Location: app/static/shop/js/
Example (shop-layout.js):
function shopLayoutData() {
return {
dark: false,
cartCount: 0,
cart: [],
init() {
this.loadCart();
this.loadThemePreference();
},
addToCart(product, quantity) {
// Add to cart logic
this.cart.push({ ...product, quantity });
this.saveCart();
},
toggleTheme() {
this.dark = !this.dark;
localStorage.setItem('shop-theme',
this.dark ? 'dark' : 'light');
}
};
}
Responsibilities:
✅ Load products from API
✅ Manage cart in localStorage
✅ Handle search and filters
✅ Update DOM reactively
✅ Theme toggling
Layer 5: API (REST)
──────────────────────────────────────────────────────────────────
Purpose: Product Data + Cart + Orders
Location: app/api/v1/shop/*.py (not pages.py)
Example Endpoints:
GET /api/v1/shop/{vendor_code}/products
GET /api/v1/shop/{vendor_code}/products/{id}
GET /api/v1/shop/{vendor_code}/categories
POST /api/v1/shop/{vendor_code}/search
POST /api/v1/shop/{vendor_code}/cart/checkout
🔄 DATA FLOW
═════════════════════════════════════════════════════════════════
Page Load Flow:
──────────────────────────────────────────────────────────────────
1. Customer → visits acme-shop.com
2. Vendor Middleware → Identifies "ACME" vendor
3. Theme Middleware → Loads ACME's theme config
4. FastAPI → Renders shop/home.html
5. Browser → Receives HTML with theme CSS variables
6. Alpine.js → init() executes
7. JavaScript → GET /api/v1/shop/ACME/products
8. API → Returns product list JSON
9. Alpine.js → Updates products array
10. Browser → DOM updates with product cards
Add to Cart Flow:
──────────────────────────────────────────────────────────────────
1. Customer → Clicks "Add to Cart"
2. Alpine.js → addToCart(product, quantity)
3. Alpine.js → Updates cart array
4. Alpine.js → Saves to localStorage
5. Alpine.js → Updates cartCount badge
6. Alpine.js → Shows toast notification
7. Browser → Cart icon updates automatically
Checkout Flow:
──────────────────────────────────────────────────────────────────
1. Customer → Goes to /cart
2. Page → Loads cart from localStorage
3. Customer → Fills checkout form
4. Alpine.js → POST /api/v1/shop/ACME/cart/checkout
5. API → Creates order + payment intent
6. Alpine.js → Redirects to payment
7. Payment → Completes
8. Redirect → /order/{order_id}/confirmation
🎨 MULTI-THEME SYSTEM
═════════════════════════════════════════════════════════════════
How Themes Work:
1. Database Storage
• Each vendor has a theme record
• Stores colors, fonts, logos, layout prefs
• Custom CSS per vendor
2. CSS Variables Injection
• base.html injects variables in <style> tag
• Variables available throughout page
• Example:
:root {
--color-primary: #6366f1;
--color-secondary: #8b5cf6;
--color-accent: #ec4899;
--color-background: #ffffff;
--color-text: #1f2937;
--font-heading: Inter, sans-serif;
--font-body: Inter, sans-serif;
}
3. Usage in Templates
<button style="background-color: var(--color-primary)">
Buy Now
</button>
4. Dark Mode
• Vendor colors adjust for dark mode
• Saved in localStorage
• Applied via :class="{ 'dark': dark }"
• Uses dark: variants in Tailwind
Theme Configuration Example:
──────────────────────────────────────────────────────────────────
{
"theme_name": "modern",
"colors": {
"primary": "#6366f1",
"secondary": "#8b5cf6",
"accent": "#ec4899",
"background": "#ffffff",
"text": "#1f2937"
},
"fonts": {
"heading": "Inter, sans-serif",
"body": "Inter, sans-serif"
},
"branding": {
"logo": "/media/vendors/acme/logo.png",
"logo_dark": "/media/vendors/acme/logo-dark.png",
"favicon": "/media/vendors/acme/favicon.ico"
},
"layout": {
"header": "fixed",
"style": "grid"
},
"social_links": {
"facebook": "https://facebook.com/acme",
"instagram": "https://instagram.com/acme"
},
"custom_css": ".product-card { border-radius: 12px; }"
}
🛒 CART SYSTEM
═════════════════════════════════════════════════════════════════
Client-Side Cart Management:
Storage: localStorage
Format: JSON array of cart items
Cart Item Structure:
{
"id": "product-123",
"name": "Product Name",
"price": 29.99,
"quantity": 2,
"image": "/media/products/image.jpg",
"vendor_code": "ACME"
}
Key Functions:
• loadCart(): Load from localStorage
• saveCart(): Persist to localStorage
• addToCart(product, quantity): Add item
• updateCartItem(id, quantity): Update quantity
• removeFromCart(id): Remove item
• clearCart(): Empty cart
• cartTotal: Computed total price
Cart Persistence:
• Survives page refresh
• Shared across shop pages
• Cleared on checkout completion
• Synced across tabs (optional)
🔍 SEARCH & FILTERS
═════════════════════════════════════════════════════════════════
Search System:
1. Search Modal
• Overlay with input
• Live search as you type
• Keyboard shortcuts (Cmd+K)
2. Search API
POST /api/v1/shop/{vendor_code}/search
{
"query": "laptop",
"category": "electronics",
"min_price": 100,
"max_price": 1000,
"sort": "price:asc"
}
3. Client-Side Filtering
• Filter products array
• No API call needed for basic filters
• Use for in-memory datasets
Filter Components:
• Category dropdown
• Price range slider
• Sort options
• Availability toggle
• Brand checkboxes
📱 RESPONSIVE DESIGN
═════════════════════════════════════════════════════════════════
Breakpoints (Tailwind):
• sm: 640px (mobile landscape)
• md: 768px (tablet)
• lg: 1024px (desktop)
• xl: 1280px (large desktop)
Product Grid Responsive:
• Mobile: 1 column
• Tablet: 2 columns
• Desktop: 4 columns
Example:
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
<!-- Product cards -->
</div>
Touch Optimization:
• Larger touch targets (min 44x44px)
• Swipeable carousels
• Touch-friendly buttons
• Tap to zoom images
🌙 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 persistence
5. Vendor colors adapt to dark mode
Toggle Button:
<button @click="toggleTheme()">
<svg x-show="!dark"><!-- Sun icon --></svg>
<svg x-show="dark"><!-- Moon icon --></svg>
</button>
Dark Mode Colors:
• Background: dark:bg-gray-900
• Text: dark:text-gray-100
• Borders: dark:border-gray-700
• Cards: dark:bg-gray-800
Vendor Colors:
• Primary color adjusts brightness
• Maintains brand identity
• Readable in both modes
🔐 CUSTOMER AUTHENTICATION
═════════════════════════════════════════════════════════════════
Optional Auth System:
Guest Checkout:
✅ No account required
✅ Email for order updates
✅ Quick checkout
Account Features:
✅ Order history
✅ Saved addresses
✅ Wishlist
✅ Profile management
Auth Flow:
1. Login/Register → POST /api/v1/shop/auth/login
2. API → Return JWT token
3. JavaScript → Store in localStorage
4. API Client → Add to authenticated requests
5. Optional → Use account features
📡 API CLIENT
═════════════════════════════════════════════════════════════════
Location: app/static/shared/js/api-client.js
Usage:
const products = await apiClient.get(
`/api/v1/shop/${vendorCode}/products`
);
const order = await apiClient.post(
`/api/v1/shop/${vendorCode}/checkout`,
orderData
);
Features:
✅ Automatic error handling
✅ JSON parsing
✅ Loading states
✅ Auth token injection (if logged in)
🐛 LOGGING
═════════════════════════════════════════════════════════════════
Location: app/static/shared/js/log-config.js
Shop-Specific Logging:
shopLog.info('Product added to cart', product);
shopLog.error('Checkout failed', error);
shopLog.debug('Search query', { query, results });
Levels:
• INFO: User actions
• ERROR: Failures and exceptions
• DEBUG: Development debugging
• WARN: Warnings
🎭 ICONS
═════════════════════════════════════════════════════════════════
Location: app/static/shared/js/icons.js
Usage:
<span x-html="$icon('shopping-cart', 'w-5 h-5')"></span>
<span x-html="$icon('search', 'w-6 h-6 text-primary')"></span>
Shop Icons:
• shopping-cart, shopping-bag
• heart (wishlist)
• search, filter
• eye (view)
• star (rating)
• truck (shipping)
• check (success)
• x (close)
• chevron-left, chevron-right
• spinner (loading)
🚀 PERFORMANCE
═════════════════════════════════════════════════════════════════
Optimization Techniques:
1. Image Optimization
• WebP format
• Lazy loading
• Responsive images (srcset)
• CDN delivery
2. Code Splitting
• Base layout loads first
• Page-specific JS loads after
• Deferred non-critical CSS
3. Caching
• Browser cache for assets
• LocalStorage for cart
• Service worker (optional)
4. Lazy Loading
• Products load as you scroll
• Images load when visible
• Infinite scroll for large catalogs
5. CDN Assets
• Tailwind from CDN
• Alpine.js from CDN
• Vendor assets from CDN
📊 PAGE-BY-PAGE BREAKDOWN
═════════════════════════════════════════════════════════════════
/ (Homepage)
──────────────────────────────────────────────────────────────────
Purpose: Display featured products, hero section
Components:
• Hero banner with CTA
• Featured products grid
• Category cards
• About vendor section
Data Sources:
• GET /api/v1/shop/{code}/products?featured=true
• GET /api/v1/shop/{code}/categories
/products
──────────────────────────────────────────────────────────────────
Purpose: Browse all products with filters
Components:
• Product grid
• Filter sidebar
• Sort dropdown
• Pagination
Data Sources:
• GET /api/v1/shop/{code}/products
• Filters applied client-side or server-side
/products/{product_id}
──────────────────────────────────────────────────────────────────
Purpose: Single product detail page
Components:
• Image gallery
• Product info
• Add to cart form
• Related products
• Reviews (optional)
Data Sources:
• GET /api/v1/shop/{code}/products/{id}
• GET /api/v1/shop/{code}/products/{id}/related
/cart
──────────────────────────────────────────────────────────────────
Purpose: Review cart contents before checkout
Components:
• Cart items list
• Quantity adjusters
• Remove buttons
• Cart total
• Checkout button
Data Sources:
• LocalStorage cart
• No API call needed
/checkout
──────────────────────────────────────────────────────────────────
Purpose: Complete purchase
Components:
• Shipping form
• Payment form
• Order summary
• Submit button
Data Sources:
• POST /api/v1/shop/{code}/checkout
• Stripe/PayPal integration
/search
──────────────────────────────────────────────────────────────────
Purpose: Search results page
Components:
• Search input
• Results grid
• Filter options
• Sort options
Data Sources:
• POST /api/v1/shop/{code}/search
/category/{category_slug}
──────────────────────────────────────────────────────────────────
Purpose: Browse products by category
Components:
• Breadcrumbs
• Product grid
• Subcategories
• Filters
Data Sources:
• GET /api/v1/shop/{code}/categories/{slug}/products
/about
──────────────────────────────────────────────────────────────────
Purpose: About the vendor
Components:
• Vendor story
• Team photos
• Values/mission
• Contact info
Data Sources:
• Vendor info from middleware
• Static content
/contact
──────────────────────────────────────────────────────────────────
Purpose: Contact form
Components:
• Contact form
• Map (optional)
• Business hours
• Social links
Data Sources:
• POST /api/v1/shop/{code}/contact
🎓 LEARNING PATH
═════════════════════════════════════════════════════════════════
For New Developers:
1. Understand Architecture (1 hour)
→ Read this document
→ Review file structure
→ Examine base template
→ Understand theme system
2. Study Existing Page (2 hours)
→ Open home.html
→ Open shop-layout.js
→ Trace product loading flow
→ Examine cart management
3. Create Simple Page (4 hours)
→ Copy templates
→ Modify for new feature
→ Test with different vendor themes
→ Verify responsive design
4. Add Complex Feature (1 day)
→ Product filters
→ Cart operations
→ API integration
→ Search functionality
5. Master Patterns (1 week)
→ All common patterns
→ Theme customization
→ Performance optimization
→ Mobile responsiveness
🔄 DEPLOYMENT CHECKLIST
═════════════════════════════════════════════════════════════════
Before Deploying:
□ Build Tailwind CSS
□ Minify JavaScript
□ Test all routes
□ Test with multiple vendor themes
□ Verify cart persistence
□ Check mobile responsive
□ Test dark mode
□ Validate product display
□ Test checkout flow
□ Check image optimization
□ Test search functionality
□ Verify social links
□ Test across browsers
□ Check console for errors
□ Test in production mode
🔒 SECURITY
═════════════════════════════════════════════════════════════════
Best Practices:
1. Input Validation
✅ Validate all form inputs
✅ Sanitize user content
✅ XSS prevention
2. Cart Security
✅ Validate cart on server
✅ Check stock availability
✅ Verify prices server-side
✅ Never trust client cart
3. Payment Security
✅ Use trusted payment providers
✅ Never store card details
✅ HTTPS only
✅ PCI compliance
4. Rate Limiting
✅ Search endpoint throttling
✅ Contact form limits
✅ Checkout attempt limits
📚 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_SHOP_ALPINE_PAGE_TEMPLATE.md
• Multi-Theme Guide: MULTI_THEME_SHOP_GUIDE.md
• API Documentation: API_REFERENCE.md
• Database Schema: DATABASE_SCHEMA.md
══════════════════════════════════════════════════════════════════
SHOP FRONTEND ARCHITECTURE
Theme-Driven, Customer-Focused, Brand-Consistent
══════════════════════════════════════════════════════════════════