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:**
```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.