orion/13.updated_application_workflows_final.md

Multi-Tenant Ecommerce Platform - Complete Application Workflows

Overview

This document describes the complete workflows for the production-ready multi-tenant ecommerce platform, from marketplace import to customer analytics. Each workflow shows the interaction between different user types and the data flow through all system components including notifications, payments, media management, and monitoring.

Core Data Flow Architecture

Marketplace CSV → MarketplaceProduct (staging) → Product (catalog) → Customer Orders → Analytics
                         ↓                           ↓                    ↓
                   Email Notifications         Media Files         Payment Processing
                         ↓                           ↓                    ↓
                   Audit Logging              Search Index         Performance Monitoring

Workflow 1: Platform Setup and Vendor Onboarding

Participants

• Admin: Platform administrator
• New Vendor: Business owner registering
• System: Automated onboarding processes

Workflow Steps

1.1 Admin Creates Vendor

Admin → Access admin panel (admin.platform.com)
  ↓
POST /api/v1/admin/auth/login
  ↓
Admin dashboard loads with platform metrics
  ↓
Admin → Create new vendor
  ↓
POST /api/v1/admin/vendors
  ↓
System creates:
  - Vendor record with subdomain
  - Owner user account
  - Default role structure (Owner, Manager, Editor, Viewer)
  - Default notification templates
  - Vendor payment configuration (inactive)
  - Initial search index
  - Audit log entry
  ↓
Email notification sent to vendor owner
  ↓
Vendor appears in admin vendor list

1.2 Vendor Owner Account Activation

Vendor Owner → Receives welcome email
  ↓
Click activation link → vendor.platform.com/admin/login
  ↓
POST /api/v1/vendor/auth/login
  ↓
Vendor context middleware detects vendor from subdomain
  ↓
Dashboard loads with vendor setup checklist:
  - ✅ Account created
  - ⏸️ Payment setup pending
  - ⏸️ Marketplace integration pending
  - ⏸️ First product pending

1.3 Payment Configuration

Vendor → Configure payments
  ↓
GET /api/v1/vendor/payments/config (returns needs_setup: true)
  ↓
POST /api/v1/vendor/payments/setup
  ↓
System creates Stripe Connect account
  ↓
Vendor redirected to Stripe onboarding
  ↓
Stripe webhook updates account status
  ↓
VendorPaymentConfig.accepts_payments = true
  ↓
Audit log: payment configuration completed

Data States After Onboarding

• Vendor: Active with configured payments
• User: Owner with full permissions
• Notifications: Welcome sequence completed
• Audit Trail: Complete onboarding history

---

Workflow 2: Marketplace Import and Product Curation

Participants

• Vendor: Store owner/manager
• Background System: Import processing
• Notification System: Status updates

Workflow Steps

2.1 Marketplace Configuration

Vendor → Configure Letzshop integration
  ↓
POST /api/v1/vendor/settings/marketplace
  ↓
Update Vendor.letzshop_csv_url
  ↓
Configuration validated and saved
  ↓
Audit log: marketplace configuration updated

2.2 Import Execution

Vendor → Trigger import
  ↓
POST /api/v1/vendor/marketplace/import
  ↓
System creates MarketplaceImportJob (status: pending)
  ↓
Background task queued: process_marketplace_import.delay(job_id)
  ↓
TaskLog created with progress tracking
  ↓
Celery worker processes import:
  - Downloads CSV from marketplace
  - Validates data format
  - Creates MarketplaceProduct records (staging)
  - Updates SearchIndex for browsing
  - Generates product image thumbnails
  - Updates job status with progress
  ↓
Email notification: import completed
  ↓
Audit log: import job completed

2.3 Product Discovery and Selection

Vendor → Browse imported products
  ↓
GET /api/v1/vendor/marketplace/imports/{job_id}/products
  ↓
Cache check for search results
  ↓
Display MarketplaceProduct records with:
  - Search and filtering capabilities
  - Thumbnail images
  - Selection status indicators
  - Bulk selection options
  ↓
Vendor → Select products for review
  ↓
POST /api/v1/vendor/marketplace/products/{id}/select
  ↓
MarketplaceProduct updated:
  - is_selected: true
  - selected_at: timestamp
  ↓
Search index updated
  ↓
Cache invalidation for product lists

2.4 Product Customization and Publishing

Vendor → Customize selected product
  ↓
Vendor uploads custom images:
  ↓
POST /api/v1/vendor/media/upload
  ↓
MediaService processes:
  - Creates vendor-scoped file path
  - Generates image variants (thumbnail, small, medium, large)
  - Uploads to storage backend (local/S3)
  - Creates MediaFile record
  ↓
Vendor customizes:
  - SKU (vendor-specific)
  - Price (markup from cost)
  - Description (enhanced/localized)
  - Images (vendor-uploaded + marketplace)
  - Categories (vendor taxonomy)
  - Inventory settings
  ↓
Vendor → Publish to catalog
  ↓
POST /api/v1/vendor/marketplace/products/{id}/publish
  ↓
System creates Product record:
  - Vendor-customized data
  - marketplace_product_id link
  - is_active: true
  ↓
Updates:
  - MarketplaceProduct: is_published: true
  - SearchIndex: product catalog entry
  - Cache invalidation: product catalogs
  ↓
Product now visible in vendor catalog
  ↓
Audit log: product published to catalog

Data States After Publication

• MarketplaceProduct: Selected and published
• Product: Active in vendor catalog
• MediaFile: Vendor-specific product images
• SearchIndex: Searchable in catalog
• Cache: Invalidated and refreshed

---

Workflow 3: Customer Shopping Experience

Participants

• Customer: End user shopping
• Vendor: Store owner (indirect)
• Search System: Product discovery
• Payment System: Transaction processing

Workflow Steps

3.1 Store Discovery and Browsing

Customer → Access vendor store
  ↓
vendor.platform.com OR platform.com/vendor/vendorname
  ↓
Vendor context middleware:
  - Identifies vendor from URL
  - Loads vendor-specific theme
  - Sets vendor_id context for all operations
  ↓
GET /api/v1/public/vendors/{vendor_id}/shop-info
  ↓
Cache check for vendor theme and configuration
  ↓
Store homepage loads with vendor branding

3.2 Product Search and Discovery

Customer → Search for products
  ↓
GET /api/v1/public/vendors/{vendor_id}/products/search?q=query
  ↓
SearchService processes query:
  - Cache check for search results
  - Elasticsearch query (if available) OR database search
  - Vendor-scoped results only
  - Logs search query for analytics
  ↓
Results include:
  - Product details with vendor customizations
  - Media files (images with variants)
  - Real-time inventory levels
  - Vendor-specific pricing
  ↓
Search analytics updated
  ↓
Cache results for future queries

3.3 Product Details and Media

Customer → View product details
  ↓
GET /api/v1/public/vendors/{vendor_id}/products/{id}
  ↓
System returns:
  - Product information from vendor catalog
  - Media gallery with all variants
  - Inventory availability
  - Vendor-specific descriptions and pricing
  ↓
Media files served from CDN for performance

3.4 Shopping Cart Management

Customer → Add to cart
  ↓
POST /api/v1/public/vendors/{vendor_id}/cart/{session_id}/items
  ↓
System:
  - Validates product availability
  - Checks inventory levels
  - Creates/updates session-based cart
  - Price validation against current Product prices
  ↓
Cart data cached for session

3.5 Customer Account Management

Customer → Create account
  ↓
POST /api/v1/public/vendors/{vendor_id}/customers/register
  ↓
System creates:
  - Customer record (vendor_id scoped)
  - Email unique within vendor only
  - Vendor-specific customer number
  - Default notification preferences
  ↓
Welcome email sent using vendor