403 lines
23 KiB
Markdown
403 lines
23 KiB
Markdown
# Multi-Tenant Ecommerce Platform - Complete Project Structure
|
|
|
|
## Project Overview
|
|
|
|
This document outlines the complete project structure for a production-ready multi-tenant ecommerce platform with marketplace integration. The platform implements complete vendor isolation with comprehensive business features including notifications, media management, search, caching, audit logging, and monitoring.
|
|
|
|
## Technology Stack
|
|
|
|
- **Backend**: Python FastAPI with PostgreSQL
|
|
- **Frontend**: Vanilla HTML, CSS, JavaScript with AJAX
|
|
- **Background Jobs**: Celery with Redis
|
|
- **Search**: Elasticsearch with database fallback
|
|
- **Caching**: Redis multi-layer caching
|
|
- **Storage**: Local/S3 with CDN integration
|
|
- **Monitoring**: Custom monitoring with alerting
|
|
- **Deployment**: Docker with environment-based configuration
|
|
|
|
## Complete Directory Structure
|
|
|
|
```
|
|
├── main.py # FastAPI application entry point
|
|
├── app/
|
|
│ ├── api/
|
|
│ │ ├── deps.py # Common dependencies
|
|
│ │ ├── main.py # API router setup
|
|
│ │ └── v1/ # API version 1 routes
|
|
│ │ ├── admin/ # Super admin endpoints
|
|
│ │ │ ├── __init__.py
|
|
│ │ │ ├── auth.py # Admin authentication
|
|
│ │ │ ├── vendors.py # Vendor management (CRUD, bulk import)
|
|
│ │ │ ├── dashboard.py # Admin dashboard & statistics
|
|
│ │ │ ├── users.py # User management across vendors
|
|
│ │ │ ├── marketplace.py # System-wide marketplace monitoring
|
|
│ │ │ └── monitoring.py # Platform monitoring & alerts
|
|
│ │ ├── vendor/ # Vendor-scoped endpoints
|
|
│ │ │ ├── __init__.py
|
|
│ │ │ ├── auth.py # Vendor team authentication
|
|
│ │ │ ├── dashboard.py # Vendor dashboard & statistics
|
|
│ │ │ ├── products.py # Vendor catalog management (Product table)
|
|
│ │ │ ├── marketplace.py # Marketplace import & selection (MarketplaceProduct table)
|
|
│ │ │ ├── orders.py # Vendor order management
|
|
│ │ │ ├── customers.py # Vendor customer management
|
|
│ │ │ ├── teams.py # Team member management
|
|
│ │ │ ├── inventory.py # Inventory operations (vendor catalog products)
|
|
│ │ │ ├── payments.py # Payment configuration & processing
|
|
│ │ │ ├── media.py # File and media management
|
|
│ │ │ ├── notifications.py # Notification management
|
|
│ │ │ └── settings.py # Vendor settings & configuration
|
|
│ │ ├── public/ # Public customer-facing endpoints
|
|
│ │ │ ├── __init__.py
|
|
│ │ │ └── vendors/ # Vendor-specific public APIs
|
|
│ │ │ ├── shop.py # Public shop info
|
|
│ │ │ ├── products.py # Public product catalog (Product table only)
|
|
│ │ │ ├── search.py # Product search functionality
|
|
│ │ │ ├── cart.py # Shopping cart operations
|
|
│ │ │ ├── orders.py # Order placement
|
|
│ │ │ ├── payments.py # Payment processing
|
|
│ │ │ └── auth.py # Customer authentication
|
|
│ │ └── shared/ # Shared/utility endpoints
|
|
│ │ ├── health.py # Health checks
|
|
│ │ ├── webhooks.py # External webhooks (Stripe, etc.)
|
|
│ │ └── uploads.py # File upload handling
|
|
│ ├── core/
|
|
│ │ ├── config.py # Configuration settings
|
|
│ │ ├── database.py # Database setup
|
|
│ │ └── lifespan.py # App lifecycle management
|
|
│ ├── exceptions/ # Custom exception handling
|
|
│ │ ├── __init__.py # All exception exports
|
|
│ │ ├── base.py # Base exception classes
|
|
│ │ ├── handler.py # Unified FastAPI exception handlers
|
|
│ │ ├── auth.py # Authentication/authorization exceptions
|
|
│ │ ├── admin.py # Admin operation exceptions
|
|
│ │ ├── marketplace.py # Import/marketplace exceptions
|
|
│ │ ├── marketplace_product.py # Marketplace staging exceptions
|
|
│ │ ├── product.py # Vendor catalog exceptions
|
|
│ │ ├── vendor.py # Vendor management exceptions
|
|
│ │ ├── customer.py # Customer management exceptions
|
|
│ │ ├── order.py # Order management exceptions
|
|
│ │ ├── payment.py # Payment processing exceptions
|
|
│ │ ├── inventory.py # Inventory management exceptions
|
|
│ │ ├── media.py # Media/file management exceptions
|
|
│ │ ├── notification.py # Notification exceptions
|
|
│ │ ├── search.py # Search exceptions
|
|
│ │ ├── monitoring.py # Monitoring exceptions
|
|
│ │ └── backup.py # Backup/recovery exceptions
|
|
│ └── services/ # Business logic layer
|
|
│ ├── auth_service.py # Authentication/authorization services
|
|
│ ├── admin_service.py # Admin services
|
|
│ ├── vendor_service.py # Vendor management services
|
|
│ ├── customer_service.py # Customer services (vendor-scoped)
|
|
│ ├── team_service.py # Team management services
|
|
│ ├── marketplace_service.py # Marketplace import services (MarketplaceProduct)
|
|
│ ├── marketplace_product_service.py # Marketplace staging services
|
|
│ ├── product_service.py # Vendor catalog services (Product)
|
|
│ ├── order_service.py # Order services (vendor-scoped)
|
|
│ ├── payment_service.py # Payment processing services
|
|
│ ├── inventory_service.py # Inventory services (vendor catalog)
|
|
│ ├── media_service.py # File and media management services
|
|
│ ├── notification_service.py # Email/notification services
|
|
│ ├── search_service.py # Search and indexing services
|
|
│ ├── cache_service.py # Caching services
|
|
│ ├── audit_service.py # Audit logging services
|
|
│ ├── monitoring_service.py # Application monitoring services
|
|
│ ├── backup_service.py # Backup and recovery services
|
|
│ ├── configuration_service.py # Configuration management services
|
|
│ └── stats_service.py # Statistics services (vendor-aware)
|
|
├── tasks/ # Background task processing
|
|
│ ├── __init__.py
|
|
│ ├── task_manager.py # Celery configuration and task management
|
|
│ ├── marketplace_import.py # Marketplace CSV import tasks
|
|
│ ├── email_tasks.py # Email sending tasks
|
|
│ ├── media_processing.py # Image processing and optimization tasks
|
|
│ ├── search_indexing.py # Search index maintenance tasks
|
|
│ ├── analytics_tasks.py # Analytics and reporting tasks
|
|
│ ├── cleanup_tasks.py # Data cleanup and maintenance tasks
|
|
│ └── backup_tasks.py # Backup and recovery tasks
|
|
├── models/
|
|
│ ├── database/ # SQLAlchemy ORM models
|
|
│ │ ├── __init__.py # Import all models for easy access
|
|
│ │ ├── base.py # Base model class and common mixins
|
|
│ │ ├── user.py # User model (with vendor relationships)
|
|
│ │ ├── vendor.py # Vendor, VendorUser, Role models
|
|
│ │ ├── customer.py # Customer, CustomerAddress models (vendor-scoped)
|
|
│ │ ├── marketplace_product.py # MarketplaceProduct model (staging data)
|
|
│ │ ├── product.py # Product model (vendor catalog)
|
|
│ │ ├── order.py # Order, OrderItem models (vendor-scoped)
|
|
│ │ ├── payment.py # Payment, PaymentMethod, VendorPaymentConfig models
|
|
│ │ ├── inventory.py # Inventory, InventoryMovement models (catalog products)
|
|
│ │ ├── marketplace.py # MarketplaceImportJob model
|
|
│ │ ├── media.py # MediaFile, ProductMedia models
|
|
│ │ ├── notification.py # NotificationTemplate, NotificationQueue, NotificationLog models
|
|
│ │ ├── search.py # SearchIndex, SearchQuery models
|
|
│ │ ├── audit.py # AuditLog, DataExportLog models
|
|
│ │ ├── monitoring.py # PerformanceMetric, ErrorLog, SystemAlert models
|
|
│ │ ├── backup.py # BackupLog, RestoreLog models
|
|
│ │ ├── configuration.py # PlatformConfig, VendorConfig, FeatureFlag models
|
|
│ │ ├── task.py # TaskLog model
|
|
│ │ └── admin.py # Admin-specific models
|
|
│ └── schema/ # Pydantic models for API validation
|
|
│ ├── __init__.py # Common imports
|
|
│ ├── base.py # Base Pydantic models
|
|
│ ├── auth.py # Login, Token, User response models
|
|
│ ├── vendor.py # Vendor management models
|
|
│ ├── customer.py # Customer request/response models
|
|
│ ├── team.py # Team management models
|
|
│ ├── marketplace_product.py # Marketplace staging models
|
|
│ ├── product.py # Vendor catalog models
|
|
│ ├── order.py # Order models (vendor-scoped)
|
|
│ ├── payment.py # Payment models
|
|
│ ├── inventory.py # Inventory operation models
|
|
│ ├── marketplace.py # Marketplace import job models
|
|
│ ├── media.py # Media/file management models
|
|
│ ├── notification.py # Notification models
|
|
│ ├── search.py # Search models
|
|
│ ├── monitoring.py # Monitoring models
|
|
│ ├── admin.py # Admin operation models
|
|
│ └── stats.py # Statistics response models
|
|
├── middleware/
|
|
│ ├── auth.py # JWT authentication
|
|
│ ├── vendor_context.py # Vendor context detection and injection
|
|
│ ├── rate_limiter.py # Rate limiting
|
|
│ ├── logging_middleware.py # Request logging
|
|
│ └── decorators.py # Cross-cutting concern decorators
|
|
├── storage/ # Storage backends
|
|
│ ├── __init__.py
|
|
│ ├── backends.py # Storage backend implementations
|
|
│ └── utils.py # Storage utilities
|
|
├── static/ # Frontend assets
|
|
│ ├── admin/ # Super admin interface
|
|
│ │ ├── login.html # Admin login page
|
|
│ │ ├── dashboard.html # Admin dashboard
|
|
│ │ ├── vendors.html # Vendor management
|
|
│ │ ├── users.html # User management
|
|
│ │ ├── marketplace.html # System-wide marketplace monitoring
|
|
│ │ └── monitoring.html # System monitoring
|
|
│ ├── vendor/ # Vendor admin interface
|
|
│ │ ├── login.html # Vendor team login
|
|
│ │ ├── dashboard.html # Vendor dashboard
|
|
│ │ └── admin/ # Vendor admin pages
|
|
│ │ ├── products.html # Catalog management (Product table)
|
|
│ │ ├── marketplace/ # Marketplace integration
|
|
│ │ │ ├── imports.html # Import jobs & history
|
|
│ │ │ ├── browse.html # Browse marketplace products (staging)
|
|
│ │ │ ├── selected.html # Selected products (pre-publish)
|
|
│ │ │ └── config.html # Marketplace configuration
|
|
│ │ ├── orders.html # Order management
|
|
│ │ ├── customers.html # Customer management
|
|
│ │ ├── teams.html # Team management
|
|
│ │ ├── inventory.html # Inventory management (catalog products)
|
|
│ │ ├── payments.html # Payment configuration
|
|
│ │ ├── media.html # Media library
|
|
│ │ ├── notifications.html # Notification templates & logs
|
|
│ │ └── settings.html # Vendor settings
|
|
│ ├── shop/ # Customer-facing shop interface
|
|
│ │ ├── home.html # Shop homepage
|
|
│ │ ├── products.html # Product catalog (Product table only)
|
|
│ │ ├── product.html # Product detail page
|
|
│ │ ├── search.html # Search results page
|
|
│ │ ├── cart.html # Shopping cart
|
|
│ │ ├── checkout.html # Checkout process
|
|
│ │ └── account/ # Customer account pages
|
|
│ │ ├── login.html # Customer login
|
|
│ │ ├── register.html # Customer registration
|
|
│ │ ├── profile.html # Customer profile
|
|
│ │ ├── orders.html # Order history
|
|
│ │ └── addresses.html # Address management
|
|
│ ├── css/
|
|
│ │ ├── admin/ # Admin interface styles
|
|
│ │ ├── vendor/ # Vendor interface styles
|
|
│ │ ├── shop/ # Customer shop styles
|
|
│ │ ├── shared/ # Common styles
|
|
│ │ └── themes/ # Vendor-specific themes
|
|
│ └── js/
|
|
│ ├── shared/ # Common JavaScript utilities
|
|
│ │ ├── vendor-context.js # Vendor context detection & management
|
|
│ │ ├── api-client.js # API communication utilities
|
|
│ │ ├── notification.js # Notification handling
|
|
│ │ ├── media-upload.js # File upload utilities
|
|
│ │ └── search.js # Search functionality
|
|
│ ├── admin/ # Admin interface scripts
|
|
│ │ ├── dashboard.js # Admin dashboard
|
|
│ │ ├── vendors.js # Vendor management
|
|
│ │ ├── monitoring.js # System monitoring
|
|
│ │ └── analytics.js # Admin analytics
|
|
│ ├── vendor/ # Vendor interface scripts
|
|
│ │ ├── products.js # Catalog management
|
|
│ │ ├── marketplace.js # Marketplace integration
|
|
│ │ ├── orders.js # Order management
|
|
│ │ ├── payments.js # Payment configuration
|
|
│ │ ├── media.js # Media management
|
|
│ │ └── dashboard.js # Vendor dashboard
|
|
│ └── shop/ # Customer shop scripts
|
|
│ ├── catalog.js # Product browsing
|
|
│ ├── search.js # Product search
|
|
│ ├── cart.js # Shopping cart
|
|
│ ├── checkout.js # Checkout process
|
|
│ └── account.js # Customer account
|
|
├── tests/ # Comprehensive test suite
|
|
│ ├── unit/ # Unit tests
|
|
│ │ ├── services/ # Service layer tests
|
|
│ │ │ ├── test_marketplace_service.py # Marketplace staging tests
|
|
│ │ │ ├── test_product_service.py # Catalog management tests
|
|
│ │ │ ├── test_payment_service.py # Payment processing tests
|
|
│ │ │ ├── test_notification_service.py # Notification tests
|
|
│ │ │ ├── test_search_service.py # Search functionality tests
|
|
│ │ │ ├── test_media_service.py # Media management tests
|
|
│ │ │ └── test_cache_service.py # Caching tests
|
|
│ │ ├── models/ # Model tests
|
|
│ │ │ ├── test_marketplace_product.py # Staging model tests
|
|
│ │ │ ├── test_product.py # Catalog model tests
|
|
│ │ │ ├── test_payment.py # Payment model tests
|
|
│ │ │ └── test_vendor.py # Vendor model tests
|
|
│ │ └── api/ # API endpoint tests
|
|
│ │ ├── test_admin_api.py # Admin API tests
|
|
│ │ ├── test_vendor_api.py # Vendor API tests
|
|
│ │ └── test_public_api.py # Public API tests
|
|
│ ├── integration/ # Integration tests
|
|
│ │ ├── test_marketplace_workflow.py # End-to-end import workflow
|
|
│ │ ├── test_order_workflow.py # Complete order process
|
|
│ │ ├── test_payment_workflow.py # Payment processing
|
|
│ │ └── test_notification_workflow.py # Notification sending
|
|
│ ├── e2e/ # End-to-end tests
|
|
│ │ ├── test_vendor_onboarding.py # Complete vendor setup
|
|
│ │ ├── test_customer_journey.py # Customer shopping experience
|
|
│ │ └── test_admin_operations.py # Admin platform management
|
|
│ └── fixtures/ # Test data fixtures
|
|
│ ├── marketplace_data.py # Sample marketplace import data
|
|
│ ├── catalog_data.py # Sample vendor catalog data
|
|
│ ├── order_data.py # Sample order data
|
|
│ └── user_data.py # Sample user and vendor data
|
|
├── scripts/ # Utility scripts
|
|
│ ├── init_db.py # Database initialization
|
|
│ ├── create_admin.py # Create initial admin user
|
|
│ ├── backup_database.py # Manual backup script
|
|
│ ├── seed_data.py # Development data seeding
|
|
│ └── migrate_data.py # Data migration utilities
|
|
├── docker/ # Docker configuration
|
|
│ ├── Dockerfile # Application container
|
|
│ ├── docker-compose.yml # Development environment
|
|
│ ├── docker-compose.prod.yml # Production environment
|
|
│ └── nginx.conf # Nginx configuration
|
|
├── docs/ # Documentation
|
|
│ ├── api/ # API documentation
|
|
│ ├── deployment/ # Deployment guides
|
|
│ ├── development/ # Development setup
|
|
│ └── user_guides/ # User manuals
|
|
├── .env.example # Environment variables template
|
|
├── requirements.txt # Python dependencies
|
|
├── requirements-dev.txt # Development dependencies
|
|
├── README.md # Project documentation
|
|
└── DEPLOYMENT.md # Deployment instructions
|
|
```
|
|
|
|
## Architecture Principles
|
|
|
|
### Multi-Tenancy Model
|
|
- **Complete Vendor Isolation**: Each vendor operates independently with no data sharing
|
|
- **Chinese Wall**: Strict separation between vendor data and operations
|
|
- **Self-Service**: Vendors manage their own teams, products, and marketplace integrations
|
|
- **Scalable**: Single codebase serves all vendors with vendor-specific customization
|
|
|
|
### Data Flow Architecture
|
|
```
|
|
Marketplace CSV → MarketplaceProduct (staging) → Product (catalog) → Order → Analytics
|
|
↓
|
|
Email Notifications → Audit Logs → Monitoring
|
|
```
|
|
|
|
### API Structure
|
|
- **Admin APIs** (`/api/v1/admin/`): Platform-level administration
|
|
- **Vendor APIs** (`/api/v1/vendor/`): Vendor-scoped operations (requires vendor context)
|
|
- **Public APIs** (`/api/v1/public/vendors/{vendor_id}/`): Customer-facing operations
|
|
- **Shared APIs** (`/api/v1/shared/`): Utility endpoints (health, webhooks)
|
|
|
|
### Service Layer Architecture
|
|
- **Domain Services**: Each service handles one business domain (products, orders, payments)
|
|
- **Cross-Cutting Services**: Shared services (cache, audit, monitoring, notifications)
|
|
- **Integration Services**: External service integration (payments, search, storage)
|
|
|
|
### Frontend Architecture
|
|
- **Static Assets**: All frontend files served from `/static/` directory
|
|
- **Single Application**: One frontend codebase serving all vendors
|
|
- **Context-Aware Routing**: Automatic vendor detection via subdomain or path
|
|
- **Dynamic Theming**: Vendor-specific customization and branding
|
|
- **Role-Based UI**: Permission-driven interface elements
|
|
|
|
## Key Features
|
|
|
|
### Core Business Features
|
|
- Multi-vendor marketplace with complete isolation
|
|
- Marketplace product import and curation workflow
|
|
- Comprehensive order and payment processing
|
|
- Customer management with vendor-scoped accounts
|
|
- Team management with role-based permissions
|
|
- Inventory tracking and management
|
|
|
|
### Advanced Features
|
|
- Email notification system with vendor branding
|
|
- File and media management with CDN integration
|
|
- Advanced search with Elasticsearch
|
|
- Multi-layer caching for performance
|
|
- Comprehensive audit logging for compliance
|
|
- Real-time monitoring and alerting
|
|
- Automated backup and disaster recovery
|
|
- Configuration management with feature flags
|
|
|
|
### Security Features
|
|
- JWT-based authentication with vendor context
|
|
- Role-based access control with granular permissions
|
|
- Complete vendor data isolation at all layers
|
|
- Audit trails for all operations
|
|
- Secure file storage with access controls
|
|
- Rate limiting and abuse prevention
|
|
|
|
### Integration Capabilities
|
|
- Stripe Connect for multi-vendor payments
|
|
- Marketplace integrations (Letzshop with extensible framework)
|
|
- Multiple storage backends (Local, S3, GCS)
|
|
- Search engines (Elasticsearch with database fallback)
|
|
- Email providers (SendGrid, SMTP)
|
|
- Monitoring and alerting systems
|
|
|
|
## Deployment Modes
|
|
|
|
### Development Mode
|
|
- **Path-based routing**: `localhost:3000/vendor/vendorname/`
|
|
- **Admin access**: `localhost:3000/admin/`
|
|
- **Easy context switching**: Clear vendor separation in URLs
|
|
- **Local storage**: Files stored locally with hot reload
|
|
|
|
### Production Mode
|
|
- **Subdomain routing**: `vendorname.platform.com`
|
|
- **Admin subdomain**: `admin.platform.com`
|
|
- **Custom domains**: `customdomain.com` (enterprise feature)
|
|
- **CDN integration**: Optimized asset delivery
|
|
- **Distributed caching**: Redis cluster for performance
|
|
- **Automated backups**: Scheduled database and file backups
|
|
|
|
## Technology Integration
|
|
|
|
### Database Layer
|
|
- **PostgreSQL**: Primary database with ACID compliance
|
|
- **Redis**: Caching and session storage
|
|
- **Elasticsearch**: Search and analytics (optional)
|
|
|
|
### Background Processing
|
|
- **Celery**: Distributed task processing
|
|
- **Redis**: Message broker and result backend
|
|
- **Monitoring**: Task progress and error tracking
|
|
|
|
### External Services
|
|
- **Stripe Connect**: Payment processing
|
|
- **SendGrid/SMTP**: Email delivery
|
|
- **AWS S3/GCS**: Cloud storage
|
|
- **CloudFront/CloudFlare**: CDN
|
|
|
|
### Monitoring Stack
|
|
- **Custom Monitoring**: Application-specific metrics
|
|
- **Error Tracking**: Comprehensive error logging
|
|
- **Performance Monitoring**: Response times and throughput
|
|
- **Health Checks**: Automated system health monitoring
|
|
|
|
This structure provides a robust foundation for a scalable, multi-tenant ecommerce platform with enterprise-grade features while maintaining clean separation of concerns and supporting multiple deployment modes. |