orion/docs/architecture/frontend-structure.md

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:

<!-- 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:

<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:

<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:

<!-- 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:

<link href="{{ url_for('static', path='admin/css/custom.css') }}" rel="stylesheet">

Images:

<img src="{{ url_for('static', path='admin/img/placeholder.png') }}" alt="Placeholder">

---

Vendor Static Assets (static/vendor/)

JavaScript Files:

<!-- 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:

<link href="{{ url_for('static', path='vendor/css/custom.css') }}" rel="stylesheet">

Images:

<img src="{{ url_for('static', path='vendor/img/no-products.svg') }}" alt="No Products">

---

Shop Static Assets (static/shop/)

JavaScript Files:

<!-- 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:

<link href="{{ url_for('static', path='shop/css/product-gallery.css') }}" rel="stylesheet">

Images:

<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:

<span x-html="$icon('icon-name', 'w-5 h-5')"></span>

API Client:

const data = await apiClient.get('/api/v1/admin/users');

Utilities:

Utils.showToast('Success!', 'success');
Utils.formatDate(dateString);

Logging:

const log = window.LogConfig.loggers.myPage;
log.info('Page loaded');

Frontend-Specific Resources

Platform-specific JavaScript:

<script src="{{ url_for('static', path='platform/js/homepage.js') }}"></script>

Admin-specific CSS:

<link href="{{ url_for('static', path='admin/css/dashboard.css') }}" rel="stylesheet">

Vendor-specific images:

<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.