orion/docs/frontend/store/architecture.md

╔══════════════════════════════════════════════════════════════════╗ ║ STORE ADMIN FRONTEND ARCHITECTURE OVERVIEW ║ ║ Alpine.js + Jinja2 + Tailwind CSS ║ ╚══════════════════════════════════════════════════════════════════╝

📦 WHAT IS THIS? ═════════════════════════════════════════════════════════════════

Store admin frontend provides stores with a complete management interface for their store. Built with: ✅ Jinja2 Templates (server-side rendering) ✅ Alpine.js (client-side reactivity) ✅ Tailwind CSS (utility-first styling) ✅ 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

📁 FILE STRUCTURE ═════════════════════════════════════════════════════════════════

app/ ├── templates/store/ │ ├── base.html ← Base template (layout) │ ├── login.html ← Public login page │ ├── dashboard.html ← Authenticated pages │ ├── products.html │ ├── orders.html │ ├── customers.html │ ├── inventory.html │ ├── marketplace.html │ ├── team.html │ ├── settings.html │ ├── profile.html │ ├── partials/ ← Reusable components │ │ ├── header.html ← Top navigation │ │ ├── sidebar.html ← Main navigation │ │ ├── store_info.html ← Store details card │ │ └── notifications.html ← Toast notifications │ └── errors/ ← Error pages │ ├── static/store/ │ ├── css/ │ │ ├── tailwind.output.css ← Generated Tailwind │ │ └── store.css ← Custom styles │ ├── js/ │ │ ├── init-alpine.js ← Alpine.js base data │ │ ├── dashboard.js ← Dashboard logic │ │ ├── products.js ← Products page logic │ │ ├── orders.js ← Orders page logic │ │ ├── customers.js ← Customers page logic │ │ ├── inventory.js ← Inventory page logic │ │ ├── marketplace.js ← Marketplace page logic │ │ ├── team.js ← Team page logic │ │ └── settings.js ← Settings page logic │ └── img/ │ ├── login-office.jpeg │ └── login-office-dark.jpeg │ ├── 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 │ └── routes/ └── store_pages.py ← Route handlers

🏗️ 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/routes/store_pages.py

Example: @router.get("/{store_code}/dashboard") async def store_dashboard_page( request: Request, store_code: str = Path(..., description="Store code"), current_user: User = Depends(get_current_store_from_cookie_or_header) ): return templates.TemplateResponse( "store/dashboard.html", { "request": request, "user": current_user, "store_code": store_code } )

Responsibilities: ✅ Verify authentication ✅ Extract route parameters ✅ Render template ❌ NO database queries ❌ NO business logic

Layer 2: TEMPLATES (Jinja2) ────────────────────────────────────────────────────────────────── Purpose: HTML Structure + Server-Side Data Location: app/templates/store/

Template Hierarchy: base.html (layout) ↓ dashboard.html (page) ↓ partials/sidebar.html (components)

Example: {% extends "store/base.html" %} {% block title %}Dashboard{% endblock %} {% block alpine_data %}storeDashboard(){% endblock %} {% block content %}

Loading...

{% endblock %}

Key Features: ✅ Template inheritance ✅ Server-side variables (user, store_code) ✅ Include partials ✅ Block overrides

Layer 3: JAVASCRIPT (Alpine.js) ────────────────────────────────────────────────────────────────── Purpose: Client-Side Interactivity + Data Loading Location: app/static/store/js/

Example: function storeDashboard() { return { loading: false, stats: {},

      async init() {
          await this.loadStats();
      },

      async loadStats() {
          this.loading = true;
          try {
              this.stats = await apiClient.get(
                  `/api/v1/store/dashboard/stats`
              );
          } finally {
              this.loading = false;
          }
      }
  };

}

Responsibilities: ✅ Load data from API ✅ Manage UI state ✅ Handle user interactions ✅ Update DOM reactively

Layer 4: API (REST) ────────────────────────────────────────────────────────────────── Purpose: Business Logic + Data Access Location: app/api/v1/store/*.py

Example Endpoints: GET /api/v1/store/dashboard/stats GET /api/v1/store/products POST /api/v1/store/products PUT /api/v1/store/products/{id} DELETE /api/v1/store/products/{id}

🔄 DATA FLOW ═════════════════════════════════════════════════════════════════

Page Load Flow: ──────────────────────────────────────────────────────────────────

1. User → GET /store/ACME/dashboard
2. FastAPI → Check authentication
3. FastAPI → Render template with minimal context
4. Browser → Load HTML + CSS + JS
5. Alpine.js → init() executes
6. JavaScript → API call for data
7. API → Return JSON data
8. Alpine.js → Update reactive state
9. Browser → DOM updates automatically

User Interaction Flow: ──────────────────────────────────────────────────────────────────

1. User → Click "Add Product"
2. Alpine.js → openCreateModal()
3. Alpine.js → Show modal
4. User → Fill form + submit
5. Alpine.js → POST to API
6. API → Create product + return
7. Alpine.js → Update local state
8. Browser → DOM updates automatically
9. Alpine.js → Close modal

🎨 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 (store/css/store.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)

🔐 AUTHENTICATION ═════════════════════════════════════════════════════════════════

Auth Flow:

1. Login → POST /api/v1/store/auth/login
2. API → Return JWT token + set store_token cookie
3. JavaScript → Token stored in localStorage (optional)
4. Cookie → Automatically sent with page requests
5. API Client → Add Authorization header for API calls
6. Routes → Verify with get_current_store_from_cookie_or_header

Token Storage: • HttpOnly Cookie: store_token (path=/store) - For page navigation • LocalStorage: Optional, for JavaScript API calls • Dual authentication: Supports both cookie and header-based auth

Protected Routes: • All /store/{code}/* routes (except /login) • Require valid JWT token (cookie or header) • Redirect to login if unauthorized

Public Routes: • /store/{code}/login • No authentication required • Uses get_current_store_optional to redirect if already logged in

📱 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 • Hide sidebar on mobile • Stack cards vertically

Example:

🌙 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: toggleTheme() { this.dark = !this.dark; localStorage.setItem('theme', this.dark ? 'dark' : 'light'); }

🔧 COMPONENT PATTERNS ═════════════════════════════════════════════════════════════════

Pattern 1: DATA TABLE ────────────────────────────────────────────────────────────────── Use For: Lists (products, orders, customers)

Structure: • Loading state • Error state • Empty state • Data rows • Actions column • Pagination

Key Features: ✅ Server-side pagination ✅ Filtering ✅ Sorting ✅ Responsive

Pattern 2: DASHBOARD ────────────────────────────────────────────────────────────────── Use For: Overview pages with stats

Structure: • Stats cards grid • Recent activity list • Quick actions

Key Features: ✅ Real-time stats ✅ Charts (optional) ✅ Refresh button

Pattern 3: FORM MODAL ────────────────────────────────────────────────────────────────── Use For: Create/Edit operations

Structure: • Modal overlay • Form fields • Validation • Save/Cancel buttons

Key Features: ✅ Client-side validation ✅ Error messages ✅ Loading state ✅ Escape to close

Pattern 4: DETAIL PAGE ────────────────────────────────────────────────────────────────── Use For: Single item view (product detail, order detail)

Structure: • Header with actions • Info cards • Related data tabs

Key Features: ✅ Edit inline ✅ Related items ✅ Status badges

🔄 STATE MANAGEMENT ═════════════════════════════════════════════════════════════════

Alpine.js Reactive State:

Global State (init-alpine.js): • dark mode • current user • store info • menu state

Page State (e.g., products.js): • items array • loading boolean • error string • filters object • pagination object

State Updates: • Direct assignment: this.items = [] • Alpine auto-updates DOM • No manual DOM manipulation

📡 API CLIENT ═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/api-client.js

Usage: const data = await apiClient.get('/endpoint'); await apiClient.post('/endpoint', { data }); await apiClient.put('/endpoint/{id}', { data }); await apiClient.delete('/endpoint/{id}');

Features: ✅ Automatic auth headers ✅ Error handling ✅ JSON parsing ✅ Retry logic

🐛 LOGGING ═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/log-config.js

Usage: logInfo('Operation completed', data); logError('Operation failed', error); logDebug('Debug info', context); logWarn('Warning message');

Levels: • INFO: General information • ERROR: Errors and failures • DEBUG: Detailed debugging • WARN: Warnings

🎭 ICONS ═════════════════════════════════════════════════════════════════

Location: app/static/shared/js/icons.js

Usage:

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 with Fallback • Tailwind CSS from CDN (fallback to local) • Alpine.js from CDN (fallback to local) • Works offline and in restricted networks • See: CDN Fallback Strategy

🧪 TESTING APPROACH ═════════════════════════════════════════════════════════════════

Unit Tests: • Route handlers (Python) • API endpoints (Python) • Utility functions (JavaScript)

Integration Tests: • Full page load • Data fetching • Form submission • Authentication flow

Manual Testing: • Visual regression • Cross-browser • Mobile devices • Dark mode

🔒 SECURITY ═════════════════════════════════════════════════════════════════

Best Practices:

1. Authentication ✅ JWT tokens ✅ HttpOnly cookies option ✅ Token expiration

2. Authorization ✅ Route-level checks ✅ API-level validation ✅ Store-scoped data

3. Input Validation ✅ Client-side validation ✅ Server-side validation ✅ XSS prevention

4. CSRF Protection ✅ Token-based ✅ SameSite cookies

📊 PAGE-BY-PAGE BREAKDOWN ═════════════════════════════════════════════════════════════════

/store/{code}/dashboard ────────────────────────────────────────────────────────────────── Purpose: Overview of store operations Components: • Stats cards (products, orders, revenue) • Recent orders table • Quick actions Data Sources: • GET /api/v1/store/dashboard/stats • GET /api/v1/store/orders?limit=5

/store/{code}/products ────────────────────────────────────────────────────────────────── Purpose: Manage product catalog Components: • Product list table • Search and filters • Create/Edit modal Data Sources: • GET /api/v1/store/products • POST /api/v1/store/products • PUT /api/v1/store/products/{id}

/store/{code}/orders ────────────────────────────────────────────────────────────────── Purpose: View and manage orders Components: • Orders table • Status filters • Order detail modal Data Sources: • GET /api/v1/store/orders • PUT /api/v1/store/orders/{id}

/store/{code}/customers ────────────────────────────────────────────────────────────────── Purpose: Customer management Components: • Customer list • Search functionality • Customer detail view Data Sources: • GET /api/v1/store/customers

/store/{code}/inventory ────────────────────────────────────────────────────────────────── Purpose: Track stock levels Components: • Inventory table • Stock adjustment modal • Low stock alerts Data Sources: • GET /api/v1/store/inventory • PUT /api/v1/store/inventory/{id}

/store/{code}/marketplace ────────────────────────────────────────────────────────────────── Purpose: Import products from marketplace Components: • Import job list • Product browser • Import wizard Data Sources: • GET /api/v1/store/marketplace/jobs • POST /api/v1/store/marketplace/import

/store/{code}/team ────────────────────────────────────────────────────────────────── Purpose: Manage team members Components: • Team member list • Role management • Invitation form Data Sources: • GET /api/v1/store/team • POST /api/v1/store/team/invite

/store/{code}/profile ────────────────────────────────────────────────────────────────── Purpose: Manage store profile and branding Components: • Profile information form • Branding settings • Business details Data Sources: • GET /api/v1/store/profile • PUT /api/v1/store/profile

/store/{code}/settings ────────────────────────────────────────────────────────────────── Purpose: Configure store settings Components: • Settings tabs • Form sections • Save buttons Data Sources: • GET /api/v1/store/settings • PUT /api/v1/store/settings

🎓 LEARNING PATH ═════════════════════════════════════════════════════════════════

For New Developers:

1. Understand Architecture (1 hour) → Read this document → Review file structure → Examine base template

2. Study Existing Page (2 hours) → Open dashboard.html → Open dashboard.js → Trace data flow

3. Create Simple Page (4 hours) → Copy templates → Modify for new feature → Test thoroughly

4. Add Complex Feature (1 day) → Forms with validation → Modal dialogs → API integration

5. Master Patterns (1 week) → All common patterns → Error handling → Performance optimization

🔄 DEPLOYMENT CHECKLIST ═════════════════════════════════════════════════════════════════

Before Deploying: □ Build Tailwind CSS □ Minify JavaScript □ Test all routes □ Verify authentication □ Check mobile responsive □ Test dark mode □ Validate API endpoints □ Review error handling □ Check console for errors □ Test in production mode

📚 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_STORE_ALPINE_PAGE_TEMPLATE.md • API Documentation: API_REFERENCE.md • Database Schema: DATABASE_SCHEMA.md

══════════════════════════════════════════════════════════════════ STORE ADMIN ARCHITECTURE Modern, Maintainable, and Developer-Friendly ══════════════════════════════════════════════════════════════════