diff --git a/README-NEXTGEN.md b/README-NEXTGEN.md deleted file mode 100644 index 8b594045..00000000 --- a/README-NEXTGEN.md +++ /dev/null @@ -1,400 +0,0 @@ -# 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. \ No newline at end of file