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

```python
# 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
```python
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
```python
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
```csv
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
```python
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.