# 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.