sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme file update

Browse Source
This commit is contained in:
Samir Boulahtit
2025-09-27 15:59:33 +02:00
parent eaba11acb1
commit 32be301d83
1 changed files with 0 additions and 400 deletions
Download Patch File Download Diff File Expand all files Collapse all files

400
README-NEXTGEN.md
View File

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