revamping documentation
This commit is contained in:
828
docs/frontend/admin/architecture.md
Normal file
828
docs/frontend/admin/architecture.md
Normal file
@@ -0,0 +1,828 @@
|
||||
╔══════════════════════════════════════════════════════════════════╗
|
||||
║ ADMIN FRONTEND ARCHITECTURE OVERVIEW ║
|
||||
║ Alpine.js + Jinja2 + Tailwind CSS ║
|
||||
╚══════════════════════════════════════════════════════════════════╝
|
||||
|
||||
📦 WHAT IS THIS?
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Admin frontend provides platform administrators with complete control
|
||||
over the marketplace. Built with:
|
||||
✅ Jinja2 Templates (server-side rendering)
|
||||
✅ Alpine.js (client-side reactivity)
|
||||
✅ Tailwind CSS (utility-first styling)
|
||||
✅ Windmill Dashboard UI (dark mode ready)
|
||||
✅ 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
|
||||
|
||||
5. Centralized State & Logging
|
||||
• Base layout provides shared state
|
||||
• Centralized logging system
|
||||
• Consistent error handling
|
||||
|
||||
|
||||
📁 FILE STRUCTURE
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
app/
|
||||
├── templates/admin/
|
||||
│ ├── base.html ← Base template (layout)
|
||||
│ ├── login.html ← Admin login page
|
||||
│ ├── dashboard.html ← Dashboard overview
|
||||
│ ├── vendors.html ← Vendor management
|
||||
│ ├── vendor-edit.html ← Single vendor edit
|
||||
│ ├── users.html ← User management
|
||||
│ ├── products.html ← Product management
|
||||
│ ├── orders.html ← Order management
|
||||
│ ├── import-jobs.html ← Import job tracking
|
||||
│ ├── audit-logs.html ← Audit log viewer
|
||||
│ ├── settings.html ← System settings
|
||||
│ └── partials/ ← Reusable components
|
||||
│ ├── header.html ← Top navigation
|
||||
│ ├── sidebar.html ← Main navigation
|
||||
│ ├── notifications.html ← Toast notifications
|
||||
│ ├── modal.html ← Modal template
|
||||
│ └── table.html ← Data table template
|
||||
│
|
||||
├── static/admin/
|
||||
│ ├── css/
|
||||
│ │ ├── tailwind.output.css ← Generated Tailwind
|
||||
│ │ └── admin.css ← Custom admin styles
|
||||
│ ├── js/
|
||||
│ │ ├── init-alpine.js ← Base Alpine.js data
|
||||
│ │ ├── dashboard.js ← Dashboard logic
|
||||
│ │ ├── vendors.js ← Vendor management logic
|
||||
│ │ ├── vendor-edit.js ← Vendor edit logic
|
||||
│ │ ├── vendor-theme.js ← Theme customization
|
||||
│ │ ├── users.js ← User management logic
|
||||
│ │ ├── products.js ← Product management logic
|
||||
│ │ ├── orders.js ← Order management logic
|
||||
│ │ ├── import-jobs.js ← Import tracking logic
|
||||
│ │ ├── audit-logs.js ← Audit log logic
|
||||
│ │ └── settings.js ← Settings logic
|
||||
│ └── img/
|
||||
│ ├── login-office.jpeg
|
||||
│ └── login-office-dark.jpeg
|
||||
│
|
||||
├── static/shared/ ← Shared across all areas
|
||||
│ ├── js/
|
||||
│ │ ├── log-config.js ← Centralized logging
|
||||
│ │ ├── icons.js ← Icon registry
|
||||
│ │ ├── utils.js ← Utility functions
|
||||
│ │ └── api-client.js ← API wrapper
|
||||
│ └── css/
|
||||
│ └── base.css ← Global styles
|
||||
│
|
||||
└── api/v1/admin/
|
||||
├── pages.py ← Route handlers (templates)
|
||||
├── vendors.py ← Vendor API endpoints
|
||||
├── users.py ← User API endpoints
|
||||
├── products.py ← Product API endpoints
|
||||
├── orders.py ← Order API endpoints
|
||||
└── settings.py ← Settings API endpoints
|
||||
|
||||
|
||||
🏗️ 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/api/v1/admin/pages.py
|
||||
|
||||
Example:
|
||||
@router.get("/admin/dashboard")
|
||||
async def admin_dashboard_page(
|
||||
request: Request,
|
||||
current_user: User = Depends(get_current_admin_user)
|
||||
):
|
||||
return templates.TemplateResponse(
|
||||
"admin/dashboard.html",
|
||||
{
|
||||
"request": request,
|
||||
"user": current_user,
|
||||
}
|
||||
)
|
||||
|
||||
Responsibilities:
|
||||
✅ Verify authentication (admin role required)
|
||||
✅ Extract route parameters
|
||||
✅ Render template with minimal context
|
||||
❌ NO database queries
|
||||
❌ NO business logic
|
||||
|
||||
|
||||
Layer 2: TEMPLATES (Jinja2)
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: HTML Structure + Server-Side Data
|
||||
Location: app/templates/admin/
|
||||
|
||||
Template Hierarchy:
|
||||
base.html (layout + shared components)
|
||||
↓
|
||||
dashboard.html (page content)
|
||||
↓
|
||||
partials/sidebar.html (navigation)
|
||||
|
||||
Example:
|
||||
{% extends "admin/base.html" %}
|
||||
{% block title %}Dashboard{% endblock %}
|
||||
{% block alpine_data %}adminDashboard(){% endblock %}
|
||||
{% block content %}
|
||||
<div x-show="loading">Loading...</div>
|
||||
<div x-show="!loading">
|
||||
<div class="grid grid-cols-1 md:grid-cols-4 gap-6">
|
||||
<template x-for="stat in stats" :key="stat.label">
|
||||
<!-- Stats card -->
|
||||
</template>
|
||||
</div>
|
||||
</div>
|
||||
{% endblock %}
|
||||
|
||||
Key Features:
|
||||
✅ Template inheritance
|
||||
✅ Server-side variables (user info)
|
||||
✅ Include partials
|
||||
✅ Block overrides
|
||||
✅ Alpine.js integration
|
||||
|
||||
|
||||
Layer 3: JAVASCRIPT (Alpine.js)
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Client-Side Interactivity + Data Loading
|
||||
Location: app/static/admin/js/
|
||||
|
||||
Component Structure:
|
||||
function adminDashboard() {
|
||||
return {
|
||||
// ✅ CRITICAL: Inherit base layout state
|
||||
...data(),
|
||||
|
||||
// ✅ CRITICAL: Set page identifier
|
||||
currentPage: 'dashboard',
|
||||
|
||||
// Page-specific state
|
||||
loading: false,
|
||||
error: null,
|
||||
stats: [],
|
||||
|
||||
// Initialization
|
||||
async init() {
|
||||
// Guard against multiple initialization
|
||||
if (window._dashboardInitialized) {
|
||||
dashLog.warn('Already initialized');
|
||||
return;
|
||||
}
|
||||
window._dashboardInitialized = true;
|
||||
|
||||
await this.loadStats();
|
||||
},
|
||||
|
||||
// Data loading
|
||||
async loadStats() {
|
||||
this.loading = true;
|
||||
try {
|
||||
this.stats = await apiClient.get(
|
||||
'/api/v1/admin/stats'
|
||||
);
|
||||
} catch (error) {
|
||||
this.error = error.message;
|
||||
} finally {
|
||||
this.loading = false;
|
||||
}
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
Responsibilities:
|
||||
✅ Load data from API
|
||||
✅ Manage UI state
|
||||
✅ Handle user interactions
|
||||
✅ Update DOM reactively
|
||||
✅ Inherit base layout functionality
|
||||
|
||||
|
||||
Layer 4: API (REST)
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Business Logic + Data Access
|
||||
Location: app/api/v1/admin/*.py (not pages.py)
|
||||
|
||||
Example Endpoints:
|
||||
GET /api/v1/admin/stats
|
||||
GET /api/v1/admin/vendors
|
||||
POST /api/v1/admin/vendors
|
||||
PUT /api/v1/admin/vendors/{id}
|
||||
DELETE /api/v1/admin/vendors/{id}
|
||||
GET /api/v1/admin/users
|
||||
GET /api/v1/admin/audit-logs
|
||||
|
||||
|
||||
🔄 DATA FLOW
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Page Load Flow:
|
||||
──────────────────────────────────────────────────────────────────
|
||||
1. Admin → GET /admin/dashboard
|
||||
2. FastAPI → Check authentication (admin role)
|
||||
3. FastAPI → Render template with minimal context
|
||||
4. Browser → Load HTML + CSS + JS
|
||||
5. Alpine.js → init() executes
|
||||
6. JavaScript → Check initialization guard
|
||||
7. JavaScript → API call for dashboard stats
|
||||
8. API → Return JSON data
|
||||
9. Alpine.js → Update reactive state
|
||||
10. Browser → DOM updates automatically
|
||||
|
||||
User Interaction Flow:
|
||||
──────────────────────────────────────────────────────────────────
|
||||
1. Admin → Click "Delete Vendor"
|
||||
2. Alpine.js → Show confirmation dialog
|
||||
3. Admin → Confirms deletion
|
||||
4. Alpine.js → DELETE to API
|
||||
5. API → Delete vendor + return success
|
||||
6. Alpine.js → Update local state (remove from list)
|
||||
7. Browser → DOM updates automatically
|
||||
8. Alpine.js → Show success toast notification
|
||||
|
||||
|
||||
💡 BASE LAYOUT INHERITANCE
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
The ...data() Spread:
|
||||
──────────────────────────────────────────────────────────────────
|
||||
|
||||
Every page component MUST start with ...data() to inherit
|
||||
base layout functionality:
|
||||
|
||||
init-alpine.js provides:
|
||||
function data() {
|
||||
return {
|
||||
// Theme state
|
||||
dark: localStorage.getItem('theme') === 'dark',
|
||||
toggleTheme() { /* ... */ },
|
||||
|
||||
// Side menu state
|
||||
isSideMenuOpen: false,
|
||||
toggleSideMenu() { /* ... */ },
|
||||
closeSideMenu() { /* ... */ },
|
||||
|
||||
// Profile menu state
|
||||
isProfileMenuOpen: false,
|
||||
toggleProfileMenu() { /* ... */ },
|
||||
closeProfileMenu() { /* ... */ },
|
||||
|
||||
// Notifications menu state
|
||||
isNotificationsMenuOpen: false,
|
||||
toggleNotificationsMenu() { /* ... */ },
|
||||
closeNotificationsMenu() { /* ... */ },
|
||||
|
||||
// Page identifier (override in each page)
|
||||
currentPage: ''
|
||||
};
|
||||
}
|
||||
|
||||
Your page inherits ALL of this:
|
||||
function adminVendors() {
|
||||
return {
|
||||
...data(), // ← Spreads all base functionality
|
||||
currentPage: 'vendors', // ← Override page identifier
|
||||
|
||||
// Your page-specific state
|
||||
vendors: [],
|
||||
loading: false
|
||||
};
|
||||
}
|
||||
|
||||
Benefits:
|
||||
✅ Automatic dark mode support
|
||||
✅ Menu states work automatically
|
||||
✅ No duplicate code
|
||||
✅ Consistent behavior across pages
|
||||
|
||||
|
||||
🎨 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 (admin/css/admin.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)
|
||||
|
||||
Windmill Dashboard Theme:
|
||||
• Professional admin UI
|
||||
• Dark mode ready
|
||||
• Consistent components
|
||||
• Accessible by default
|
||||
|
||||
|
||||
🔐 AUTHENTICATION
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Auth Flow:
|
||||
1. Login → POST /api/v1/admin/auth/login
|
||||
2. API → Verify credentials + check admin role
|
||||
3. API → Return JWT token
|
||||
4. JavaScript → Store in localStorage
|
||||
5. API Client → Add to all requests
|
||||
6. Routes → Verify with get_current_admin_user
|
||||
|
||||
Protected Routes:
|
||||
• All /admin/* routes
|
||||
• Require valid JWT token
|
||||
• Require admin role (is_admin=True)
|
||||
• Redirect to login if unauthorized
|
||||
|
||||
Public Routes:
|
||||
• /admin/login
|
||||
• No authentication required
|
||||
|
||||
Role-Based Access:
|
||||
• Admin: Full platform access
|
||||
• Vendor: Limited to own shop (vendor portal)
|
||||
• Customer: No admin access
|
||||
|
||||
|
||||
📱 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
|
||||
• Collapsible sidebar on mobile
|
||||
• Stack cards vertically on mobile
|
||||
|
||||
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 Flow:
|
||||
1. User clicks dark mode button
|
||||
2. toggleTheme() called (from base data)
|
||||
3. dark state toggled
|
||||
4. Saved to localStorage
|
||||
5. HTML class updates
|
||||
6. Tailwind dark: variants activate
|
||||
|
||||
Example Usage:
|
||||
<div class="bg-white dark:bg-gray-800">
|
||||
<p class="text-gray-900 dark:text-white">Content</p>
|
||||
</div>
|
||||
|
||||
|
||||
🔒 INITIALIZATION GUARDS
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Purpose: Prevent Multiple Initialization
|
||||
|
||||
Alpine.js can sometimes initialize components multiple times.
|
||||
Use a guard to prevent duplicate API calls and setup:
|
||||
|
||||
Pattern:
|
||||
async init() {
|
||||
// Check if already initialized
|
||||
if (window._dashboardInitialized) {
|
||||
dashLog.warn('Already initialized, skipping...');
|
||||
return; // Exit early
|
||||
}
|
||||
|
||||
// Set flag BEFORE async operations
|
||||
window._dashboardInitialized = true;
|
||||
|
||||
// Safe to proceed
|
||||
await this.loadData();
|
||||
}
|
||||
|
||||
Naming Convention:
|
||||
• Dashboard: window._dashboardInitialized
|
||||
• Vendors: window._vendorsInitialized
|
||||
• Products: window._productsInitialized
|
||||
• etc.
|
||||
|
||||
Benefits:
|
||||
✅ Prevents duplicate API calls
|
||||
✅ Prevents duplicate event listeners
|
||||
✅ Improves performance
|
||||
✅ Avoids state conflicts
|
||||
|
||||
|
||||
🪵 CENTRALIZED LOGGING
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Location: app/static/shared/js/log-config.js
|
||||
|
||||
Pre-configured Loggers:
|
||||
window.LogConfig.loggers.dashboard
|
||||
window.LogConfig.loggers.vendors
|
||||
window.LogConfig.loggers.vendorTheme
|
||||
window.LogConfig.loggers.users
|
||||
window.LogConfig.loggers.products
|
||||
window.LogConfig.loggers.orders
|
||||
window.LogConfig.loggers.imports
|
||||
window.LogConfig.loggers.audit
|
||||
|
||||
Usage:
|
||||
// Use pre-configured logger
|
||||
const dashLog = window.LogConfig.loggers.dashboard;
|
||||
|
||||
dashLog.info('Dashboard loading...');
|
||||
dashLog.error('Failed to load stats', error);
|
||||
dashLog.debug('Stats data:', statsData);
|
||||
dashLog.warn('API response slow');
|
||||
|
||||
Advanced Features:
|
||||
// Grouped logs
|
||||
dashLog.group('Loading Dashboard Data');
|
||||
dashLog.info('Fetching stats...');
|
||||
dashLog.info('Fetching activity...');
|
||||
dashLog.groupEnd();
|
||||
|
||||
// API call logging
|
||||
window.LogConfig.logApiCall('GET', url, data, 'response');
|
||||
|
||||
// Performance logging
|
||||
window.LogConfig.logPerformance('Load Stats', duration);
|
||||
|
||||
// Error logging
|
||||
window.LogConfig.logError(error, 'Load Stats');
|
||||
|
||||
Benefits:
|
||||
✅ One line instead of 15+ lines per file
|
||||
✅ Consistent logging format
|
||||
✅ Environment-aware (dev/prod)
|
||||
✅ Frontend-aware (admin/vendor/shop)
|
||||
✅ Advanced features (groups, perf, API)
|
||||
|
||||
|
||||
📡 API CLIENT
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Location: app/static/shared/js/api-client.js
|
||||
|
||||
CRITICAL: Always use lowercase 'apiClient'
|
||||
✅ apiClient.get()
|
||||
❌ ApiClient.get()
|
||||
❌ API_CLIENT.get()
|
||||
|
||||
Usage:
|
||||
const data = await apiClient.get('/api/v1/admin/vendors');
|
||||
|
||||
await apiClient.post('/api/v1/admin/vendors', {
|
||||
name: 'New Vendor',
|
||||
code: 'NEWVENDOR'
|
||||
});
|
||||
|
||||
await apiClient.put('/api/v1/admin/vendors/123', {
|
||||
name: 'Updated Name'
|
||||
});
|
||||
|
||||
await apiClient.delete('/api/v1/admin/vendors/123');
|
||||
|
||||
Features:
|
||||
✅ Automatic auth headers
|
||||
✅ Error handling
|
||||
✅ JSON parsing
|
||||
✅ Request/response logging
|
||||
|
||||
|
||||
🎭 ICONS
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Location: app/static/shared/js/icons.js
|
||||
|
||||
Usage:
|
||||
<span x-html="$icon('home', 'w-5 h-5')"></span>
|
||||
<span x-html="$icon('users', '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
|
||||
• Tailwind CSS from CDN
|
||||
• Alpine.js from CDN
|
||||
|
||||
6. Initialization Guards
|
||||
• Prevent duplicate setups
|
||||
• Reduce unnecessary operations
|
||||
|
||||
|
||||
📊 PAGE-BY-PAGE BREAKDOWN
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
/admin/dashboard
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Overview of platform operations
|
||||
Components:
|
||||
• Stats cards (vendors, users, orders, revenue)
|
||||
• Recent activity feed
|
||||
• Quick actions panel
|
||||
• System health indicators
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/stats
|
||||
• GET /api/v1/admin/recent-activity
|
||||
|
||||
/admin/vendors
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Manage marketplace vendors
|
||||
Components:
|
||||
• Vendor list table
|
||||
• Search and filters
|
||||
• Create/Edit modal
|
||||
• Status management
|
||||
• Verification controls
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/vendors
|
||||
• POST /api/v1/admin/vendors
|
||||
• PUT /api/v1/admin/vendors/{id}
|
||||
• DELETE /api/v1/admin/vendors/{id}
|
||||
|
||||
/admin/vendors/{code}/edit
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Edit single vendor details
|
||||
Components:
|
||||
• Vendor information form
|
||||
• Status controls
|
||||
• Contact information
|
||||
• Business details
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/vendors/{code}
|
||||
• PUT /api/v1/admin/vendors/{code}
|
||||
|
||||
/admin/vendors/{code}/theme
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Customize vendor's shop theme
|
||||
Components:
|
||||
• Color picker
|
||||
• Font selector
|
||||
• Logo uploader
|
||||
• Layout options
|
||||
• Custom CSS editor
|
||||
• Theme presets
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/vendor-themes/{code}
|
||||
• PUT /api/v1/admin/vendor-themes/{code}
|
||||
|
||||
/admin/users
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Manage platform users
|
||||
Components:
|
||||
• User list table
|
||||
• Search and filters
|
||||
• Role management
|
||||
• Status controls
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/users
|
||||
• PUT /api/v1/admin/users/{id}
|
||||
• DELETE /api/v1/admin/users/{id}
|
||||
|
||||
/admin/products
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: View all marketplace products
|
||||
Components:
|
||||
• Product list table
|
||||
• Search and filters
|
||||
• Vendor filter
|
||||
• Bulk actions
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/products
|
||||
|
||||
/admin/orders
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: View all marketplace orders
|
||||
Components:
|
||||
• Order list table
|
||||
• Status filters
|
||||
• Vendor filter
|
||||
• Order detail modal
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/orders
|
||||
• GET /api/v1/admin/orders/{id}
|
||||
|
||||
/admin/import-jobs
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Monitor marketplace import operations
|
||||
Components:
|
||||
• Import job list
|
||||
• Status indicators
|
||||
• Progress tracking
|
||||
• Error logs
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/import-jobs
|
||||
• GET /api/v1/admin/import-jobs/{id}
|
||||
|
||||
/admin/audit-logs
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Track all system actions
|
||||
Components:
|
||||
• Audit log table
|
||||
• Filters (user, action, date)
|
||||
• Export functionality
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/audit-logs
|
||||
|
||||
/admin/settings
|
||||
──────────────────────────────────────────────────────────────────
|
||||
Purpose: Configure platform settings
|
||||
Components:
|
||||
• Settings tabs
|
||||
• Configuration forms
|
||||
• Feature toggles
|
||||
Data Sources:
|
||||
• GET /api/v1/admin/settings
|
||||
• PUT /api/v1/admin/settings
|
||||
|
||||
|
||||
🎓 LEARNING PATH
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
For New Developers:
|
||||
|
||||
1. Understand Architecture (1 hour)
|
||||
→ Read this document
|
||||
→ Review file structure
|
||||
→ Examine base template
|
||||
→ Understand ...data() inheritance
|
||||
|
||||
2. Study Existing Page (2 hours)
|
||||
→ Open dashboard.html
|
||||
→ Open dashboard.js
|
||||
→ Trace data flow
|
||||
→ Understand init guard pattern
|
||||
|
||||
3. Create Simple Page (4 hours)
|
||||
→ Copy templates from dashboard
|
||||
→ Modify for new feature
|
||||
→ Test initialization guard
|
||||
→ Verify dark mode works
|
||||
|
||||
4. Add Complex Feature (1 day)
|
||||
→ Forms with validation
|
||||
→ Modal dialogs
|
||||
→ API integration
|
||||
→ Error handling
|
||||
|
||||
5. Master Patterns (1 week)
|
||||
→ All common patterns
|
||||
→ Centralized logging
|
||||
→ Performance optimization
|
||||
→ Best practices
|
||||
|
||||
|
||||
🔄 DEPLOYMENT CHECKLIST
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Before Deploying:
|
||||
□ Build Tailwind CSS
|
||||
□ Minify JavaScript
|
||||
□ Test all routes
|
||||
□ Verify authentication
|
||||
□ Check role-based access
|
||||
□ Verify initialization guards work
|
||||
□ Check mobile responsive
|
||||
□ Test dark mode
|
||||
□ Validate API endpoints
|
||||
□ Review error handling
|
||||
□ Test logging in production mode
|
||||
□ Check console for errors
|
||||
□ Verify no duplicate initializations
|
||||
|
||||
|
||||
🔒 SECURITY
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Best Practices:
|
||||
|
||||
1. Authentication
|
||||
✅ JWT tokens
|
||||
✅ Token expiration
|
||||
✅ Secure storage (httpOnly cookies option)
|
||||
|
||||
2. Authorization
|
||||
✅ Route-level checks (admin role required)
|
||||
✅ API-level validation
|
||||
✅ Role-based permissions
|
||||
|
||||
3. Input Validation
|
||||
✅ Client-side validation
|
||||
✅ Server-side validation
|
||||
✅ XSS prevention
|
||||
|
||||
4. CSRF Protection
|
||||
✅ Token-based
|
||||
✅ SameSite cookies
|
||||
|
||||
5. Admin-Specific
|
||||
✅ Audit logging for all actions
|
||||
✅ Strong password requirements
|
||||
✅ Two-factor authentication (optional)
|
||||
|
||||
|
||||
📚 REFERENCE LINKS
|
||||
═════════════════════════════════════════════════════════════════
|
||||
|
||||
Documentation:
|
||||
• Alpine.js: https://alpinejs.dev/
|
||||
• Tailwind CSS: https://tailwindcss.com/
|
||||
• Jinja2: https://jinja.palletsprojects.com/
|
||||
• FastAPI: https://fastapi.tiangolo.com/
|
||||
• Windmill Dashboard: https://windmill-dashboard.vercel.app/
|
||||
|
||||
Internal Docs:
|
||||
• Page Template Guide: FRONTEND_ADMIN_ALPINE_PAGE_TEMPLATE.md
|
||||
• API Documentation: API_REFERENCE.md
|
||||
• Database Schema: DATABASE_SCHEMA.md
|
||||
|
||||
|
||||
══════════════════════════════════════════════════════════════════
|
||||
ADMIN FRONTEND ARCHITECTURE
|
||||
Powerful, Secure, and Maintainable Platform Control
|
||||
══════════════════════════════════════════════════════════════════
|
||||
1310
docs/frontend/admin/page-templates.md
Normal file
1310
docs/frontend/admin/page-templates.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user