orion/README-NEXTGEN.md

Multi-Tenant Ecommerce Platform with Marketplace Integration

Project Overview

This document outlines the comprehensive architecture for a state-of-the-art multi-tenant ecommerce platform that enables vendors to operate independent webshops while integrating with external marketplaces. The platform implements complete vendor isolation with self-service capabilities and marketplace product imports.

Core Architecture

Technology Stack

• Backend: Python FastAPI with PostgreSQL
• Frontend: Vanilla HTML, CSS, JavaScript with AJAX
• Deployment: Docker with environment-based configuration
• Authentication: JWT-based with role-based access control

Multi-Tenancy Model

The platform operates on a complete vendor isolation principle where:

• Each vendor has their own independent webshop
• Full Chinese wall between vendors (no data sharing)
• Vendors can manage their own teams with granular permissions
• Self-service marketplace integration capabilities

System Architecture

1. Application Structure

app/
├── admin/                     # Super admin functionality
│   ├── models.py             # Super admin, vendor bulk operations
│   ├── routers.py            # Admin endpoints
│   ├── services/
│   │   ├── vendor_importer.py # Bulk vendor CSV import
│   │   └── admin_auth.py      # Super admin authentication
│   └── tasks.py              # Background bulk operations
├── auth/                      # Authentication & authorization
│   ├── models.py             # Users, roles, permissions
│   ├── routers.py            # Team member auth
│   ├── services/
│   │   ├── permissions.py    # Role-based access control
│   │   └── invitations.py    # Team member invites
│   └── middleware.py         # User + vendor context
├── teams/                     # Team management
│   ├── models.py             # Team management models
│   ├── routers.py            # Team CRUD operations
│   └── services.py           # Team operations
├── marketplace/               # Marketplace integrations
│   ├── models.py             # Import jobs, marketplace configs
│   ├── services/
│   │   ├── letzshop.py       # Letzshop CSV processor
│   │   └── importer.py       # Generic import orchestrator
│   ├── routers.py            # Import management endpoints
│   └── tasks.py              # Background import jobs
├── ecommerce/                 # Core business logic
│   ├── models.py             # Products, orders, customers
│   ├── routers/
│   │   ├── products.py       # Product catalog management
│   │   ├── orders.py         # Order processing
│   │   └── customers.py      # Customer management
│   └── services/             # Business logic services
└── shared/                    # Common utilities
    ├── database.py           # Database configuration
    ├── models.py             # Shared base models
    └── utils.py              # Common utilities

2. Data Models

Core Models

# Vendor Management
class Vendor(BaseModel):
    id: int
    name: str
    subdomain: str
    owner_user_id: int
    business_address: str
    business_email: str
    business_phone: str
    letzshop_csv_url: Optional[str]
    theme_config: dict
    is_active: bool = True
    created_at: datetime

# User Management
class User(BaseModel):
    id: int
    email: str
    first_name: str
    last_name: str
    hashed_password: str
    is_active: bool = True
    created_at: datetime

# Team Management
class VendorUser(BaseModel):
    id: int
    vendor_id: int
    user_id: int
    role_id: int
    invited_by: int
    is_active: bool = True

class Role(BaseModel):
    id: int
    vendor_id: int
    name: str  # "Owner", "Manager", "Editor", "Viewer"
    permissions: List[str]  # ["products.create", "orders.view", etc.]

# Product Management
class Product(BaseModel):
    id: int
    vendor_id: int
    sku: str
    name: str
    price: Decimal
    imported_product_id: Optional[int]
    custom_description: Optional[str]
    custom_price: Optional[Decimal]

class ImportedProduct(BaseModel):
    id: int
    vendor_id: int
    import_job_id: int
    external_sku: str
    raw_data: dict
    is_selected: bool = False
    is_published: bool = False

User Roles & Permissions

Role Hierarchy

1. Super Admin: Platform-level administration
2. Vendor Owner: Full vendor control including team management
3. Vendor Manager: Operational management without team control
4. Vendor Editor: Product and order management
5. Vendor Viewer: Read-only access

Permission System

DEFAULT_ROLES = {
    "Owner": [
        "team.manage", "team.invite", "team.remove",
        "products.create", "products.edit", "products.delete", "products.view",
        "orders.create", "orders.edit", "orders.view",
        "imports.trigger", "imports.view", "imports.configure",
        "settings.edit", "analytics.view"
    ],
    "Manager": [
        "team.invite", "team.view",
        "products.create", "products.edit", "products.view",
        "orders.create", "orders.edit", "orders.view",
        "imports.trigger", "imports.view",
        "analytics.view"
    ],
    "Editor": [
        "products.create", "products.edit", "products.view",
        "orders.view", "orders.edit",
        "imports.view"
    ],
    "Viewer": [
        "products.view", "orders.view", "imports.view"
    ]
}

Marketplace Integration

Current Integration: Letzshop

• Import Method: CSV file processing (one file per language per vendor)
• Data Handling: Complete import of all CSV data into staging area
• Vendor Control: Vendors select which products to publish to their catalog
• Override Capability: Vendors can modify prices, descriptions, and other attributes

Import Workflow

1. Configuration: Vendors provide their Letzshop CSV URLs
2. Import Execution: System downloads and processes CSV files
3. Product Staging: All products imported to ImportedProduct table
4. Vendor Selection: Vendors browse and select products to publish
5. Catalog Integration: Selected products become active Product entries
6. Customization: Vendors can override imported data

Import Models

class ImportJob(BaseModel):
    id: int
    vendor_id: int
    marketplace: str = "letzshop"
    csv_url: str
    status: ImportStatus
    total_products: int
    imported_at: datetime

class ImportConfiguration(BaseModel):
    vendor_id: int
    marketplace: str
    config: dict  # CSV URLs, mapping rules
    is_active: bool

Team Management System

Team Invitation Flow

1. Invitation Creation: Owner/Manager invites team member via email
2. Secure Token Generation: Cryptographically secure invitation tokens
3. Email Notification: Invitation email with acceptance link
4. User Registration: New users create account or existing users join team
5. Role Assignment: Automatic role assignment based on invitation
6. Access Activation: Immediate access to vendor resources

Multi-Vendor Users

• Users can be members of multiple vendor teams
• Context switching between vendor environments
• Isolated permissions per vendor relationship

Super Admin Capabilities

Vendor Management

• Bulk Import: CSV-based vendor creation with owner details
• Individual Management: Create, edit, deactivate vendors
• Team Oversight: View all teams across vendors
• System Monitoring: Import job monitoring, system health

Bulk Import Format

vendor_name,subdomain,owner_name,owner_email,owner_phone,business_address,business_city,business_postal_code,business_country,letzshop_csv_url,initial_password

Admin Features

• Vendor CRUD operations
• Mass password resets
• System-wide import monitoring
• Audit logging
• Analytics dashboard

Frontend Architecture

Multi-Tenant Single Application

• Single Codebase: One frontend serving all vendors
• Dynamic Theming: Vendor-specific customization
• Context Detection: Automatic vendor identification
• Role-Based UI: Permission-driven interface elements

Application Structure

ecommerce_frontend/
├── vendor/                    # Vendor admin interface
│   ├── dashboard.html
│   ├── products.html
│   ├── orders.html
│   ├── team.html
│   ├── imports.html
│   └── settings.html
├── shop/                      # Customer-facing shop
│   ├── home.html
│   ├── products.html
│   ├── cart.html
│   └── checkout.html
├── css/
│   ├── vendor/               # Admin styles
│   ├── shop/                 # Shop styles
│   └── themes/               # Vendor themes
└── js/
    ├── vendor/               # Admin logic
    ├── shop/                 # Shop functionality
    └── shared/               # Common utilities

Vendor Context Detection

1. Subdomain-based: vendor1.platform.com (Production)
2. Path-based: platform.com/vendor/vendor1 (Development)
3. Custom Domain: vendor-custom.com (Enterprise)

Deployment Strategy

Environment Configuration

• Development: Path-based routing, debug enabled
• Staging: Subdomain-based, testing features
• Production: Subdomain + custom domains, optimized performance

Single Build Deployment

• Environment-agnostic build artifacts
• Runtime configuration injection
• Dynamic vendor context resolution
• Theme and feature adaptation

Configuration Flow

1. Build Phase: Create environment-neutral assets
2. Deployment: Environment-specific configuration injection
3. Runtime: Vendor context detection and configuration loading
4. Customization: Dynamic theme and feature application

API Structure

Vendor-Scoped Endpoints

/api/v1/
├── auth/
│   ├── POST /login           # Universal login
│   └── POST /register        # Accept invitations
├── teams/
│   ├── GET /members          # Team management
│   ├── POST /invite          # Invite members
│   └── PUT /members/{id}     # Update roles
├── products/
│   ├── GET /                 # Vendor catalog
│   ├── POST /                # Create products
│   └── POST /from-import/{id} # Import from marketplace
├── marketplace/
│   ├── POST /import          # Trigger imports
│   ├── GET /imports          # Import history
│   └── GET /imports/{id}/products # Browse imported products
└── orders/
    ├── GET /                 # Order management
    └── POST /                # Create orders

Admin Endpoints

/api/v1/admin/
├── vendors/
│   ├── GET /                 # List vendors
│   ├── POST /bulk-import     # Bulk vendor creation
│   └── PUT /{id}             # Edit vendor
├── marketplace/
│   ├── GET /import-jobs      # System-wide import monitoring
│   └── POST /trigger-imports # Mass import trigger
└── system/
    ├── GET /health           # System health
    └── GET /analytics        # Platform analytics

Security Features

Authentication & Authorization

• JWT-based authentication with refresh tokens
• Role-based access control with granular permissions
• Vendor-scoped data access with automatic filtering
• Secure invitation system with expiring tokens

Data Isolation

• Complete vendor data separation at database level
• Automatic vendor ID injection in all queries
• Permission verification on all operations
• Audit logging for admin actions

Security Middleware

async def vendor_context_middleware(request: Request):
    # Extract vendor context
    # Validate user permissions
    # Inject vendor ID in request state
    # Ensure data isolation

Current Status & Next Steps

Implemented Features

• ✅ Multi-tenant architecture with vendor isolation
• ✅ Team management with role-based permissions
• ✅ Letzshop marketplace integration
• ✅ Super admin bulk vendor management
• ✅ Environment-agnostic deployment strategy

Upcoming Development

• 🔄 Frontend implementation with dynamic theming
• 🔄 Customer-facing shop interfaces
• 🔄 Order processing system
• 🔄 Payment gateway integration
• 🔄 Advanced analytics dashboard

Future Enhancements

• 📋 Additional marketplace integrations
• 📋 Advanced product management features
• 📋 Customer loyalty programs
• 📋 Multi-language support
• 📋 Mobile application

Technical Advantages

Scalability

• Horizontal scaling through vendor isolation
• Microservice-ready architecture
• Environment-flexible deployment
• Database partitioning capabilities

Maintainability

• Single codebase for all vendors
• Centralized feature updates
• Consistent development patterns
• Automated testing strategies

Flexibility

• Vendor-specific customization
• Multiple deployment modes
• Extensible marketplace integration
• Theme system for brand customization

This architecture provides a robust foundation for a scalable, multi-tenant ecommerce platform that can efficiently serve multiple vendors while maintaining complete data isolation and providing flexible marketplace integration capabilities.