23 KiB
23 KiB
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.