feat: add logging, marketplace, and admin enhancements
Database & Migrations: - Add application_logs table migration for hybrid cloud logging - Add companies table migration and restructure vendor relationships Logging System: - Implement hybrid logging system (database + file) - Add log_service for centralized log management - Create admin logs page with filtering and viewing capabilities - Add init_log_settings.py script for log configuration - Enhance core logging with database integration Marketplace Integration: - Add marketplace admin page with product management - Create marketplace vendor page with product listings - Implement marketplace.js for both admin and vendor interfaces - Add marketplace integration documentation Admin Enhancements: - Add imports management page and functionality - Create settings page for admin configuration - Add vendor themes management page - Enhance vendor detail and edit pages - Improve code quality dashboard and violation details - Add logs viewing and management - Update icons guide and shared icon system Architecture & Documentation: - Document frontend structure and component architecture - Document models structure and relationships - Add vendor-in-token architecture documentation - Add vendor RBAC (role-based access control) documentation - Document marketplace integration patterns - Update architecture patterns documentation Infrastructure: - Add platform static files structure (css, img, js) - Move architecture_scan.py to proper models location - Update model imports and registrations - Enhance exception handling - Update dependency injection patterns UI/UX: - Improve vendor edit interface - Update admin user interface - Enhance page templates documentation - Add vendor marketplace interface
This commit is contained in:
545
docs/architecture/frontend-structure.md
Normal file
545
docs/architecture/frontend-structure.md
Normal file
@@ -0,0 +1,545 @@
|
||||
# Frontend Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
This application has **4 distinct frontends**, each with its own templates and static assets:
|
||||
|
||||
1. **Platform** - Public platform pages (homepage, about, contact)
|
||||
2. **Admin** - Administrative control panel
|
||||
3. **Vendor** - Vendor management portal
|
||||
4. **Shop** - Customer-facing e-commerce store
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
app/
|
||||
├── templates/
|
||||
│ ├── platform/ # Platform public pages
|
||||
│ ├── admin/ # Admin portal pages
|
||||
│ ├── vendor/ # Vendor portal pages
|
||||
│ ├── shop/ # Shop customer pages
|
||||
│ └── shared/ # Shared components (emails, errors)
|
||||
│
|
||||
└── static/
|
||||
├── platform/ # Platform static assets
|
||||
│ ├── js/
|
||||
│ ├── css/
|
||||
│ └── img/
|
||||
├── admin/ # Admin static assets
|
||||
│ ├── js/
|
||||
│ ├── css/
|
||||
│ └── img/
|
||||
├── vendor/ # Vendor static assets
|
||||
│ ├── js/
|
||||
│ ├── css/
|
||||
│ └── img/
|
||||
├── shop/ # Shop static assets
|
||||
│ ├── js/
|
||||
│ ├── css/
|
||||
│ └── img/
|
||||
└── shared/ # Shared assets (icons, utilities)
|
||||
├── js/
|
||||
├── css/
|
||||
└── img/
|
||||
```
|
||||
|
||||
## Frontend Details
|
||||
|
||||
### 1. Platform Frontend
|
||||
|
||||
**Purpose:** Public-facing platform pages (marketing, info pages)
|
||||
|
||||
**Location:**
|
||||
- Templates: `app/templates/platform/`
|
||||
- Static: `static/platform/`
|
||||
|
||||
**Pages:**
|
||||
- Homepage (multiple layouts: default, minimal, modern)
|
||||
- Content pages (about, privacy, terms)
|
||||
- Landing pages
|
||||
|
||||
**Features:**
|
||||
- SEO-optimized
|
||||
- Multi-layout homepage support
|
||||
- Content management system integration
|
||||
- Responsive design
|
||||
|
||||
**Routes:** `/`, `/about`, `/contact`, etc.
|
||||
|
||||
**Authentication:** Not required (public access)
|
||||
|
||||
---
|
||||
|
||||
### 2. Admin Frontend
|
||||
|
||||
**Purpose:** Platform administration and management
|
||||
|
||||
**Location:**
|
||||
- Templates: `app/templates/admin/`
|
||||
- Static: `static/admin/`
|
||||
|
||||
**Pages:**
|
||||
- Dashboard
|
||||
- Vendor management
|
||||
- User management
|
||||
- Content management
|
||||
- Theme customization
|
||||
- System settings
|
||||
- Logs and monitoring
|
||||
- Code quality dashboard
|
||||
|
||||
**Technology Stack:**
|
||||
- Alpine.js for reactive components
|
||||
- Tailwind CSS for styling
|
||||
- Heroicons for icons
|
||||
- Centralized logging system
|
||||
- API-driven architecture
|
||||
|
||||
**Routes:** `/admin/*`
|
||||
|
||||
**Authentication:** Admin role required
|
||||
|
||||
---
|
||||
|
||||
### 3. Vendor Frontend
|
||||
|
||||
**Purpose:** Vendor portal for product and order management
|
||||
|
||||
**Location:**
|
||||
- Templates: `app/templates/vendor/`
|
||||
- Static: `static/vendor/`
|
||||
|
||||
**Pages:**
|
||||
- Vendor dashboard
|
||||
- Product management
|
||||
- Inventory management
|
||||
- Order management
|
||||
- Analytics
|
||||
- Profile settings
|
||||
|
||||
**Technology Stack:**
|
||||
- Alpine.js for reactive components
|
||||
- Tailwind CSS for styling
|
||||
- Heroicons for icons
|
||||
- API-driven architecture
|
||||
- Vendor context middleware
|
||||
|
||||
**Routes:** `/vendor/{vendor_code}/*`
|
||||
|
||||
**Authentication:** Vendor role required
|
||||
|
||||
---
|
||||
|
||||
### 4. Shop Frontend
|
||||
|
||||
**Purpose:** Customer-facing e-commerce store
|
||||
|
||||
**Location:**
|
||||
- Templates: `app/templates/shop/`
|
||||
- Static: `static/shop/`
|
||||
|
||||
**Pages:**
|
||||
- Product catalog
|
||||
- Product details
|
||||
- Shopping cart
|
||||
- Checkout
|
||||
- Order tracking
|
||||
- Customer account
|
||||
|
||||
**Technology Stack:**
|
||||
- Alpine.js for interactive features
|
||||
- Tailwind CSS for styling
|
||||
- E-commerce specific components
|
||||
- Payment integration
|
||||
- Shopping cart management
|
||||
|
||||
**Routes:** `/shop/*`
|
||||
|
||||
**Authentication:** Optional (required for checkout)
|
||||
|
||||
---
|
||||
|
||||
## Using Static Assets
|
||||
|
||||
Each frontend has its own static directory for frontend-specific assets. Use the appropriate directory based on which frontend the asset belongs to.
|
||||
|
||||
### Platform Static Assets (`static/platform/`)
|
||||
|
||||
**JavaScript Files:**
|
||||
```html
|
||||
<!-- In platform templates -->
|
||||
<script src="{{ url_for('static', path='platform/js/homepage.js') }}"></script>
|
||||
<script src="{{ url_for('static', path='platform/js/animations.js') }}"></script>
|
||||
```
|
||||
|
||||
**CSS Files:**
|
||||
```html
|
||||
<link href="{{ url_for('static', path='platform/css/styles.css') }}" rel="stylesheet">
|
||||
<link href="{{ url_for('static', path='platform/css/landing.css') }}" rel="stylesheet">
|
||||
```
|
||||
|
||||
**Images:**
|
||||
```html
|
||||
<img src="{{ url_for('static', path='platform/img/hero-banner.jpg') }}" alt="Hero">
|
||||
<img src="{{ url_for('static', path='platform/img/features/feature-1.svg') }}" alt="Feature">
|
||||
```
|
||||
|
||||
**Current Usage:** Platform currently uses only shared assets (fonts, Tailwind CSS). Platform-specific directories are ready for future platform-specific assets.
|
||||
|
||||
---
|
||||
|
||||
### Admin Static Assets (`static/admin/`)
|
||||
|
||||
**JavaScript Files:**
|
||||
```html
|
||||
<!-- In admin templates -->
|
||||
<script src="{{ url_for('static', path='admin/js/dashboard.js') }}"></script>
|
||||
<script src="{{ url_for('static', path='admin/js/vendors.js') }}"></script>
|
||||
```
|
||||
|
||||
**CSS Files:**
|
||||
```html
|
||||
<link href="{{ url_for('static', path='admin/css/custom.css') }}" rel="stylesheet">
|
||||
```
|
||||
|
||||
**Images:**
|
||||
```html
|
||||
<img src="{{ url_for('static', path='admin/img/placeholder.png') }}" alt="Placeholder">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Vendor Static Assets (`static/vendor/`)
|
||||
|
||||
**JavaScript Files:**
|
||||
```html
|
||||
<!-- In vendor templates -->
|
||||
<script src="{{ url_for('static', path='vendor/js/dashboard.js') }}"></script>
|
||||
<script src="{{ url_for('static', path='vendor/js/products.js') }}"></script>
|
||||
```
|
||||
|
||||
**CSS Files:**
|
||||
```html
|
||||
<link href="{{ url_for('static', path='vendor/css/custom.css') }}" rel="stylesheet">
|
||||
```
|
||||
|
||||
**Images:**
|
||||
```html
|
||||
<img src="{{ url_for('static', path='vendor/img/no-products.svg') }}" alt="No Products">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Shop Static Assets (`static/shop/`)
|
||||
|
||||
**JavaScript Files:**
|
||||
```html
|
||||
<!-- In shop templates -->
|
||||
<script src="{{ url_for('static', path='shop/js/cart.js') }}"></script>
|
||||
<script src="{{ url_for('static', path='shop/js/checkout.js') }}"></script>
|
||||
```
|
||||
|
||||
**CSS Files:**
|
||||
```html
|
||||
<link href="{{ url_for('static', path='shop/css/product-gallery.css') }}" rel="stylesheet">
|
||||
```
|
||||
|
||||
**Images:**
|
||||
```html
|
||||
<img src="{{ url_for('static', path='shop/img/placeholder-product.jpg') }}" alt="Product">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### When to Use Shared vs. Frontend-Specific
|
||||
|
||||
**Use `static/shared/` when:**
|
||||
- Asset is used by 2 or more frontends
|
||||
- Common utilities (icons, API client, utilities)
|
||||
- Brand assets (logos, favicons)
|
||||
- Core libraries (Alpine.js, Tailwind CSS fallbacks)
|
||||
|
||||
**Use `static/{frontend}/` when:**
|
||||
- Asset is only used by one specific frontend
|
||||
- Frontend-specific styling
|
||||
- Frontend-specific JavaScript components
|
||||
- Frontend-specific images/graphics
|
||||
|
||||
**Example Decision Tree:**
|
||||
```
|
||||
Icon system (used by all 4 frontends) → static/shared/js/icons.js
|
||||
Admin dashboard chart → static/admin/js/charts.js
|
||||
Vendor product form → static/vendor/js/product-form.js
|
||||
Platform hero image → static/platform/img/hero.jpg
|
||||
Shop product carousel → static/shop/js/carousel.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Shared Resources
|
||||
|
||||
### Templates (`app/templates/shared/`)
|
||||
|
||||
**Shared components used across multiple frontends:**
|
||||
- Email templates
|
||||
- Error pages (404, 500)
|
||||
- Common partials
|
||||
|
||||
### Static Assets (`static/shared/`)
|
||||
|
||||
**Shared JavaScript:**
|
||||
- `js/icons.js` - Heroicons system (used by all frontends)
|
||||
- `js/utils.js` - Common utilities
|
||||
- `js/api-client.js` - API communication
|
||||
- `js/log-config.js` - Centralized logging
|
||||
|
||||
**Shared CSS:**
|
||||
- Common utility classes
|
||||
- Shared theme variables
|
||||
|
||||
**Shared Images:**
|
||||
- Logos
|
||||
- Brand assets
|
||||
- Icons
|
||||
|
||||
---
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
### 1. Separation of Concerns
|
||||
|
||||
Each frontend is completely isolated:
|
||||
- Own templates directory
|
||||
- Own static assets directory
|
||||
- Own JavaScript components
|
||||
- Own CSS styles
|
||||
|
||||
**Benefits:**
|
||||
- Clear boundaries
|
||||
- Independent development
|
||||
- No cross-contamination
|
||||
- Easy to maintain
|
||||
|
||||
### 2. Shared Core
|
||||
|
||||
Common functionality is shared via `static/shared/`:
|
||||
- Icon system
|
||||
- API client
|
||||
- Utilities
|
||||
- Logging
|
||||
|
||||
**Benefits:**
|
||||
- DRY principle
|
||||
- Consistent behavior
|
||||
- Single source of truth
|
||||
- Easy updates
|
||||
|
||||
### 3. Template Inheritance
|
||||
|
||||
Each frontend has a base template:
|
||||
- `platform/base.html`
|
||||
- `admin/base.html`
|
||||
- `vendor/base.html`
|
||||
- `shop/base.html`
|
||||
|
||||
**Benefits:**
|
||||
- Consistent layout within frontend
|
||||
- Easy to customize per frontend
|
||||
- Different design systems possible
|
||||
|
||||
### 4. API-Driven
|
||||
|
||||
All frontends communicate with backend via APIs:
|
||||
- `/api/v1/admin/*` - Admin APIs
|
||||
- `/api/v1/vendor/*` - Vendor APIs
|
||||
- `/api/v1/shop/*` - Shop APIs
|
||||
- `/api/v1/platform/*` - Platform APIs
|
||||
|
||||
**Benefits:**
|
||||
- Clear backend contracts
|
||||
- Testable independently
|
||||
- Can be replaced with SPA if needed
|
||||
- Mobile app ready
|
||||
|
||||
---
|
||||
|
||||
## Frontend Technology Matrix
|
||||
|
||||
| Frontend | Framework | CSS | Icons | Auth Required | Base URL |
|
||||
|----------|-----------|-----------|------------|---------------|-------------------|
|
||||
| Platform | Alpine.js | Tailwind | Heroicons | No | `/` |
|
||||
| Admin | Alpine.js | Tailwind | Heroicons | Yes (Admin) | `/admin` |
|
||||
| Vendor | Alpine.js | Tailwind | Heroicons | Yes (Vendor) | `/vendor/{code}` |
|
||||
| Shop | Alpine.js | Tailwind | Heroicons | Optional | `/shop` |
|
||||
|
||||
---
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Adding a New Page
|
||||
|
||||
1. **Determine which frontend** the page belongs to
|
||||
2. **Create template** in appropriate `app/templates/{frontend}/` directory
|
||||
3. **Create JavaScript** (if needed) in `static/{frontend}/js/`
|
||||
4. **Create CSS** (if needed) in `static/{frontend}/css/`
|
||||
5. **Add route** in appropriate route handler
|
||||
6. **Update navigation** in frontend's base template
|
||||
|
||||
### Using Shared Resources
|
||||
|
||||
**Icons:**
|
||||
```html
|
||||
<span x-html="$icon('icon-name', 'w-5 h-5')"></span>
|
||||
```
|
||||
|
||||
**API Client:**
|
||||
```javascript
|
||||
const data = await apiClient.get('/api/v1/admin/users');
|
||||
```
|
||||
|
||||
**Utilities:**
|
||||
```javascript
|
||||
Utils.showToast('Success!', 'success');
|
||||
Utils.formatDate(dateString);
|
||||
```
|
||||
|
||||
**Logging:**
|
||||
```javascript
|
||||
const log = window.LogConfig.loggers.myPage;
|
||||
log.info('Page loaded');
|
||||
```
|
||||
|
||||
### Frontend-Specific Resources
|
||||
|
||||
**Platform-specific JavaScript:**
|
||||
```html
|
||||
<script src="{{ url_for('static', path='platform/js/homepage.js') }}"></script>
|
||||
```
|
||||
|
||||
**Admin-specific CSS:**
|
||||
```html
|
||||
<link href="{{ url_for('static', path='admin/css/dashboard.css') }}" rel="stylesheet">
|
||||
```
|
||||
|
||||
**Vendor-specific images:**
|
||||
```html
|
||||
<img src="{{ url_for('static', path='vendor/img/logo.png') }}">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
### Moving Assets Between Frontends
|
||||
|
||||
If an asset is used by multiple frontends:
|
||||
1. **Move to `static/shared/`**
|
||||
2. **Update all references**
|
||||
3. **Test all affected frontends**
|
||||
|
||||
If an asset is only used by one frontend:
|
||||
1. **Move to `static/{frontend}/`**
|
||||
2. **Update references in that frontend only**
|
||||
|
||||
### Deprecation Path
|
||||
|
||||
When removing a frontend:
|
||||
1. Remove `app/templates/{frontend}/`
|
||||
2. Remove `static/{frontend}/`
|
||||
3. Remove routes
|
||||
4. Update documentation
|
||||
|
||||
---
|
||||
|
||||
## Future Considerations
|
||||
|
||||
### Potential Additional Frontends
|
||||
|
||||
- **Partner Portal** - For business partners/affiliates
|
||||
- **API Documentation** - Interactive API docs (Swagger UI)
|
||||
- **Mobile App** - Native mobile using existing APIs
|
||||
|
||||
### Frontend Modernization
|
||||
|
||||
Each frontend can be independently modernized:
|
||||
- Replace Alpine.js with React/Vue/Svelte
|
||||
- Add TypeScript
|
||||
- Implement SSR/SSG
|
||||
- Convert to PWA
|
||||
|
||||
The API-driven architecture allows this flexibility.
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Per-Frontend Testing
|
||||
|
||||
Each frontend should have:
|
||||
- **Unit tests** for JavaScript components
|
||||
- **Integration tests** for API interactions
|
||||
- **E2E tests** for critical user flows
|
||||
- **Accessibility tests**
|
||||
- **Responsive design tests**
|
||||
|
||||
### Shared Resource Testing
|
||||
|
||||
Shared resources need:
|
||||
- **Unit tests** for utilities
|
||||
- **Integration tests** with all frontends
|
||||
- **Visual regression tests** for icons
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Per-Frontend Optimization
|
||||
|
||||
Each frontend can optimize independently:
|
||||
- Code splitting
|
||||
- Lazy loading
|
||||
- Asset minification
|
||||
- CDN deployment
|
||||
- Browser caching
|
||||
|
||||
### Shared Resource Optimization
|
||||
|
||||
Shared resources are cached globally:
|
||||
- Long cache headers
|
||||
- Versioning via query params
|
||||
- CDN distribution
|
||||
- Compression
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Frontend-Specific Security
|
||||
|
||||
Each frontend has different security needs:
|
||||
- **Platform:** XSS protection, CSP
|
||||
- **Admin:** CSRF tokens, admin-only routes
|
||||
- **Vendor:** Vendor isolation, rate limiting
|
||||
- **Shop:** PCI compliance, secure checkout
|
||||
|
||||
### Shared Security
|
||||
|
||||
All frontends use:
|
||||
- JWT authentication
|
||||
- HTTPS only
|
||||
- Secure headers
|
||||
- Input sanitization
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The 4-frontend architecture provides:
|
||||
- ✅ Clear separation of concerns
|
||||
- ✅ Independent development and deployment
|
||||
- ✅ Shared core functionality
|
||||
- ✅ Flexibility for future changes
|
||||
- ✅ Optimized for each user type
|
||||
- ✅ Maintainable and scalable
|
||||
|
||||
Each frontend serves a specific purpose and audience, with shared infrastructure for common needs.
|
||||
Reference in New Issue
Block a user