610 lines
14 KiB
Markdown
610 lines
14 KiB
Markdown
# Multi-Tenant System
|
|
|
|
Complete guide to the multi-tenant architecture supporting custom domains, subdomains, and path-based routing.
|
|
|
|
## Overview
|
|
|
|
The Wizamart platform supports **three deployment modes** for multi-tenancy, allowing each vendor to have their own isolated shop while sharing the same application instance and database.
|
|
|
|
**Key Concept**: One application, multiple isolated vendor shops, each accessible via different URLs.
|
|
|
|
**Important Distinction:**
|
|
- **Vendor Dashboard** (all modes): `/vendor/{code}/*` (singular) - Management interface for vendors
|
|
- **Shop Storefront** (path-based only): `/vendors/{code}/shop/*` (plural) - Customer-facing shop
|
|
- This naming distinction helps separate administrative routes from public-facing shop routes
|
|
|
|
## The Three Routing Modes
|
|
|
|
### 1. Custom Domain Mode
|
|
|
|
**Concept**: Each vendor has their own domain pointing to the platform.
|
|
|
|
**Example**:
|
|
```
|
|
customdomain1.com → Vendor 1 Shop
|
|
anothershop.com → Vendor 2 Shop
|
|
beststore.net → Vendor 3 Shop
|
|
```
|
|
|
|
**How it works**:
|
|
1. Vendor registers a custom domain
|
|
2. Domain's DNS is configured to point to the platform
|
|
3. Platform detects vendor by matching domain in database
|
|
4. Vendor's shop is displayed with their theme/branding
|
|
|
|
**Use Case**: Professional vendors who want their own branded domain
|
|
|
|
**Configuration**:
|
|
```python
|
|
# Database: vendor_domains table
|
|
vendor_id | domain
|
|
----------|------------------
|
|
1 | customdomain1.com
|
|
2 | anothershop.com
|
|
3 | beststore.net
|
|
```
|
|
|
|
### 2. Subdomain Mode
|
|
|
|
**Concept**: Each vendor gets a subdomain of the platform domain.
|
|
|
|
**Example**:
|
|
```
|
|
vendor1.platform.com → Vendor 1 Shop
|
|
vendor2.platform.com → Vendor 2 Shop
|
|
vendor3.platform.com → Vendor 3 Shop
|
|
admin.platform.com → Admin Interface
|
|
```
|
|
|
|
**How it works**:
|
|
1. Vendor is assigned a unique code (e.g., "vendor1")
|
|
2. Subdomain is automatically available: `{code}.platform.com`
|
|
3. Platform detects vendor from subdomain prefix
|
|
4. No DNS configuration needed by vendor
|
|
|
|
**Use Case**: Easy setup, no custom domain required
|
|
|
|
**Configuration**:
|
|
```python
|
|
# Vendors table
|
|
id | code | name
|
|
---|---------|----------
|
|
1 | vendor1 | Vendor One Shop
|
|
2 | vendor2 | Vendor Two Shop
|
|
3 | vendor3 | Vendor Three Shop
|
|
```
|
|
|
|
### 3. Path-Based Mode
|
|
|
|
**Concept**: All vendors share the same domain, differentiated by URL path.
|
|
|
|
**Example**:
|
|
```
|
|
platform.com/vendors/vendor1/shop → Vendor 1 Shop
|
|
platform.com/vendors/vendor2/shop → Vendor 2 Shop
|
|
platform.com/vendors/vendor3/shop → Vendor 3 Shop
|
|
```
|
|
|
|
**How it works**:
|
|
1. URL path includes vendor code
|
|
2. Platform extracts vendor code from path
|
|
3. Path is rewritten for routing
|
|
4. All vendors on same domain
|
|
|
|
**Use Case**: Development and testing environments only
|
|
|
|
**Path Patterns**:
|
|
- `/vendors/{code}/shop/*` - Storefront pages (correct pattern)
|
|
- `/vendor/{code}/*` - Vendor dashboard pages (different context)
|
|
|
|
## Routing Mode Comparison
|
|
|
|
| Feature | Custom Domain | Subdomain | Path-Based |
|
|
|---------|---------------|-----------|------------|
|
|
| **Professionalism** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ |
|
|
| **Setup Complexity** | High (DNS required) | Low (automatic) | Very Low |
|
|
| **SSL Complexity** | Medium (wildcard or per-domain) | Low (wildcard SSL) | Very Low (single cert) |
|
|
| **SEO Benefits** | Best (own domain) | Good | Limited |
|
|
| **Cost** | High (domain + SSL) | Low (wildcard SSL) | Lowest |
|
|
| **Isolation** | Best (separate domain) | Good | Good |
|
|
| **URL Appearance** | `shop.com` | `shop.platform.com` | `platform.com/vendor/shop` |
|
|
|
|
## Implementation Details
|
|
|
|
### Vendor Detection Logic
|
|
|
|
The `VendorContextMiddleware` detects vendors using this priority:
|
|
|
|
```python
|
|
def detect_vendor(request):
|
|
host = request.headers.get("host")
|
|
|
|
# 1. Try custom domain first
|
|
vendor = find_by_custom_domain(host)
|
|
if vendor:
|
|
return vendor, "custom_domain"
|
|
|
|
# 2. Try subdomain
|
|
if host != settings.platform_domain:
|
|
vendor_code = host.split('.')[0]
|
|
vendor = find_by_code(vendor_code)
|
|
if vendor:
|
|
return vendor, "subdomain"
|
|
|
|
# 3. Try path-based
|
|
path = request.url.path
|
|
if path.startswith("/vendor/") or path.startswith("/vendors/"):
|
|
vendor_code = extract_code_from_path(path)
|
|
vendor = find_by_code(vendor_code)
|
|
if vendor:
|
|
return vendor, "path_based"
|
|
|
|
return None, None
|
|
```
|
|
|
|
### Path Extraction
|
|
|
|
For path-based routing, clean paths are extracted:
|
|
|
|
**Path-Based Shop Routes** (Development):
|
|
```
|
|
Original: /vendors/WIZAMART/shop/products
|
|
Extracted: vendor_code = "WIZAMART"
|
|
Clean: /shop/products
|
|
```
|
|
|
|
**Vendor Dashboard Routes** (All environments):
|
|
```
|
|
Original: /vendor/WIZAMART/dashboard
|
|
Extracted: vendor_code = "WIZAMART"
|
|
Clean: /dashboard
|
|
```
|
|
|
|
**Note**: The shop storefront uses `/vendors/` (plural) while the vendor dashboard uses `/vendor/` (singular). This distinction helps separate customer-facing shop routes from vendor management routes.
|
|
|
|
**Why Clean Path?**
|
|
- FastAPI routes don't include vendor prefix
|
|
- Routes defined as: `@app.get("/shop/products")`
|
|
- Path must be rewritten to match routes
|
|
|
|
## Database Schema
|
|
|
|
### Vendors Table
|
|
|
|
```sql
|
|
CREATE TABLE vendors (
|
|
id SERIAL PRIMARY KEY,
|
|
code VARCHAR(50) UNIQUE NOT NULL, -- For subdomain/path routing
|
|
name VARCHAR(255) NOT NULL,
|
|
is_active BOOLEAN DEFAULT true,
|
|
created_at TIMESTAMP DEFAULT NOW()
|
|
);
|
|
```
|
|
|
|
### Vendor Domains Table
|
|
|
|
```sql
|
|
CREATE TABLE vendor_domains (
|
|
id SERIAL PRIMARY KEY,
|
|
vendor_id INTEGER REFERENCES vendors(id),
|
|
domain VARCHAR(255) UNIQUE NOT NULL, -- Custom domain
|
|
is_verified BOOLEAN DEFAULT false,
|
|
created_at TIMESTAMP DEFAULT NOW()
|
|
);
|
|
```
|
|
|
|
**Example Data**:
|
|
```sql
|
|
-- Vendors
|
|
INSERT INTO vendors (code, name) VALUES
|
|
('wizamart', 'Wizamart Shop'),
|
|
('techstore', 'Tech Store'),
|
|
('fashionhub', 'Fashion Hub');
|
|
|
|
-- Custom Domains
|
|
INSERT INTO vendor_domains (vendor_id, domain) VALUES
|
|
(1, 'wizamart.com'),
|
|
(2, 'mytechstore.net');
|
|
```
|
|
|
|
## Deployment Scenarios
|
|
|
|
### Scenario 1: Small Platform (Path-Based)
|
|
|
|
**Setup**:
|
|
- Single domain: `myplatform.com`
|
|
- All vendors use path-based routing
|
|
- Single SSL certificate
|
|
- Simplest infrastructure
|
|
|
|
**URLs**:
|
|
```
|
|
myplatform.com/admin
|
|
myplatform.com/vendors/shop1/shop
|
|
myplatform.com/vendors/shop2/shop
|
|
myplatform.com/vendors/shop3/shop
|
|
```
|
|
|
|
**Infrastructure**:
|
|
```
|
|
[Internet] → [Single Server] → [PostgreSQL]
|
|
myplatform.com
|
|
```
|
|
|
|
### Scenario 2: Medium Platform (Subdomain)
|
|
|
|
**Setup**:
|
|
- Main domain: `myplatform.com`
|
|
- Vendors get subdomains automatically
|
|
- Wildcard SSL certificate (`*.myplatform.com`)
|
|
- Better branding for vendors
|
|
|
|
**URLs**:
|
|
```
|
|
admin.myplatform.com
|
|
shop1.myplatform.com
|
|
shop2.myplatform.com
|
|
shop3.myplatform.com
|
|
```
|
|
|
|
**Infrastructure**:
|
|
```
|
|
[Internet] → [Load Balancer] → [App Servers] → [PostgreSQL]
|
|
*.myplatform.com
|
|
```
|
|
|
|
### Scenario 3: Large Platform (Mixed Mode)
|
|
|
|
**Setup**:
|
|
- Supports all three modes
|
|
- Premium vendors get custom domains
|
|
- Regular vendors use subdomains
|
|
- Free tier uses path-based
|
|
|
|
**URLs**:
|
|
```
|
|
# Custom domains (premium)
|
|
customdomain.com → Vendor 1
|
|
anotherdomain.com → Vendor 2
|
|
|
|
# Subdomains (standard)
|
|
shop3.myplatform.com → Vendor 3
|
|
shop4.myplatform.com → Vendor 4
|
|
|
|
# Path-based (free tier)
|
|
myplatform.com/vendors/shop5/shop → Vendor 5
|
|
myplatform.com/vendors/shop6/shop → Vendor 6
|
|
```
|
|
|
|
**Infrastructure**:
|
|
```
|
|
[CDN/Load Balancer]
|
|
|
|
|
+-----------------+------------------+
|
|
| | |
|
|
[App Server 1] [App Server 2] [App Server 3]
|
|
| | |
|
|
+-----------------+------------------+
|
|
|
|
|
[PostgreSQL Cluster]
|
|
```
|
|
|
|
## DNS Configuration
|
|
|
|
### For Custom Domains
|
|
|
|
**Vendor Side**:
|
|
```
|
|
# DNS A Record
|
|
customdomain.com. A 203.0.113.10 (platform IP)
|
|
|
|
# Or CNAME
|
|
customdomain.com. CNAME myplatform.com.
|
|
```
|
|
|
|
**Platform Side**:
|
|
- Add domain to `vendor_domains` table
|
|
- Generate SSL certificate (Let's Encrypt)
|
|
- Verify domain ownership
|
|
|
|
### For Subdomains
|
|
|
|
**Platform Side**:
|
|
```
|
|
# Wildcard DNS
|
|
*.myplatform.com. A 203.0.113.10
|
|
|
|
# Or individual subdomains
|
|
shop1.myplatform.com. A 203.0.113.10
|
|
shop2.myplatform.com. A 203.0.113.10
|
|
```
|
|
|
|
**SSL Certificate**:
|
|
```bash
|
|
# Wildcard certificate
|
|
*.myplatform.com
|
|
myplatform.com
|
|
```
|
|
|
|
## Tenant Isolation
|
|
|
|
### Data Isolation
|
|
|
|
Every database query is scoped to `vendor_id`:
|
|
|
|
```python
|
|
# Example: Get products for current vendor
|
|
products = db.query(Product).filter(
|
|
Product.vendor_id == request.state.vendor_id
|
|
).all()
|
|
|
|
# Example: Create order for vendor
|
|
order = Order(
|
|
vendor_id=request.state.vendor_id,
|
|
customer_id=customer_id,
|
|
# ... other fields
|
|
)
|
|
```
|
|
|
|
**Critical**: ALWAYS filter by `vendor_id` in queries!
|
|
|
|
### Theme Isolation
|
|
|
|
Each vendor has independent theme settings:
|
|
|
|
```python
|
|
# Vendor 1 theme
|
|
{
|
|
"primary_color": "#3B82F6",
|
|
"logo_url": "/static/vendors/vendor1/logo.png"
|
|
}
|
|
|
|
# Vendor 2 theme
|
|
{
|
|
"primary_color": "#10B981",
|
|
"logo_url": "/static/vendors/vendor2/logo.png"
|
|
}
|
|
```
|
|
|
|
### File Storage Isolation
|
|
|
|
Vendor files stored in separate directories:
|
|
|
|
```
|
|
static/
|
|
└── vendors/
|
|
├── vendor1/
|
|
│ ├── logo.png
|
|
│ ├── favicon.ico
|
|
│ └── products/
|
|
│ ├── product1.jpg
|
|
│ └── product2.jpg
|
|
└── vendor2/
|
|
├── logo.png
|
|
└── products/
|
|
└── product1.jpg
|
|
```
|
|
|
|
## Request Examples
|
|
|
|
### Example 1: Custom Domain Request
|
|
|
|
**Request**:
|
|
```http
|
|
GET /shop/products HTTP/1.1
|
|
Host: customdomain.com
|
|
```
|
|
|
|
**Processing**:
|
|
```
|
|
1. VendorContextMiddleware
|
|
- Checks: domain = "customdomain.com"
|
|
- Queries: vendor_domains WHERE domain = "customdomain.com"
|
|
- Finds: vendor_id = 1
|
|
- Sets: request.state.vendor = <Vendor 1>
|
|
|
|
2. ContextDetectionMiddleware
|
|
- Analyzes: path = "/shop/products"
|
|
- Sets: context_type = SHOP
|
|
|
|
3. ThemeContextMiddleware
|
|
- Queries: vendor_themes WHERE vendor_id = 1
|
|
- Sets: request.state.theme = {...}
|
|
|
|
4. Route Handler
|
|
- Queries: products WHERE vendor_id = 1
|
|
- Renders: template with Vendor 1 theme
|
|
```
|
|
|
|
### Example 2: Subdomain Request
|
|
|
|
**Request**:
|
|
```http
|
|
GET /shop/products HTTP/1.1
|
|
Host: wizamart.myplatform.com
|
|
```
|
|
|
|
**Processing**:
|
|
```
|
|
1. VendorContextMiddleware
|
|
- Checks: host != "myplatform.com"
|
|
- Extracts: subdomain = "wizamart"
|
|
- Queries: vendors WHERE code = "wizamart"
|
|
- Sets: request.state.vendor = <Vendor "wizamart">
|
|
|
|
2-4. Same as Example 1
|
|
```
|
|
|
|
### Example 3: Path-Based Request
|
|
|
|
**Request**:
|
|
```http
|
|
GET /vendors/WIZAMART/shop/products HTTP/1.1
|
|
Host: myplatform.com
|
|
```
|
|
|
|
**Processing**:
|
|
```
|
|
1. VendorContextMiddleware
|
|
- Checks: path starts with "/vendor/"
|
|
- Extracts: code = "WIZAMART"
|
|
- Queries: vendors WHERE code = "WIZAMART"
|
|
- Sets: request.state.vendor = <Vendor>
|
|
- Sets: request.state.clean_path = "/shop/products"
|
|
|
|
2. FastAPI Router
|
|
- Routes registered with prefix: /vendors/{vendor_code}/shop
|
|
- Matches: /vendors/WIZAMART/shop/products
|
|
- vendor_code path parameter = "WIZAMART"
|
|
|
|
3-4. Same as previous examples (Context, Theme middleware)
|
|
```
|
|
|
|
## Testing Multi-Tenancy
|
|
|
|
### Unit Tests
|
|
|
|
```python
|
|
def test_vendor_detection_custom_domain():
|
|
request = MockRequest(host="customdomain.com")
|
|
middleware = VendorContextMiddleware()
|
|
|
|
vendor, mode = middleware.detect_vendor(request, db)
|
|
|
|
assert vendor.code == "vendor1"
|
|
assert mode == "custom_domain"
|
|
|
|
def test_vendor_detection_subdomain():
|
|
request = MockRequest(host="shop1.platform.com")
|
|
middleware = VendorContextMiddleware()
|
|
|
|
vendor, mode = middleware.detect_vendor(request, db)
|
|
|
|
assert vendor.code == "shop1"
|
|
assert mode == "subdomain"
|
|
```
|
|
|
|
### Integration Tests
|
|
|
|
```python
|
|
def test_shop_page_multi_tenant(client):
|
|
# Test subdomain routing
|
|
response = client.get(
|
|
"/shop/products",
|
|
headers={"Host": "wizamart.platform.com"}
|
|
)
|
|
assert "Wizamart" in response.text
|
|
|
|
# Test different vendor
|
|
response = client.get(
|
|
"/shop/products",
|
|
headers={"Host": "techstore.platform.com"}
|
|
)
|
|
assert "Tech Store" in response.text
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### 1. Tenant Isolation
|
|
|
|
**Always scope queries**:
|
|
```python
|
|
# ✅ Good - Scoped to vendor
|
|
products = db.query(Product).filter(
|
|
Product.vendor_id == request.state.vendor_id
|
|
).all()
|
|
|
|
# ❌ Bad - Not scoped, leaks data across tenants!
|
|
products = db.query(Product).all()
|
|
```
|
|
|
|
### 2. Domain Verification
|
|
|
|
Before activating custom domain:
|
|
1. Verify DNS points to platform
|
|
2. Check domain ownership (email/file verification)
|
|
3. Generate SSL certificate
|
|
4. Mark domain as verified
|
|
|
|
### 3. Input Validation
|
|
|
|
Validate vendor codes:
|
|
```python
|
|
# Sanitize vendor code
|
|
vendor_code = vendor_code.lower().strip()
|
|
|
|
# Validate format
|
|
if not re.match(r'^[a-z0-9-]{3,50}$', vendor_code):
|
|
raise ValidationError("Invalid vendor code")
|
|
```
|
|
|
|
## Performance Optimization
|
|
|
|
### 1. Cache Vendor Lookups
|
|
|
|
```python
|
|
# Cache vendor by domain/code
|
|
@lru_cache(maxsize=1000)
|
|
def get_vendor_by_code(code: str):
|
|
return db.query(Vendor).filter(Vendor.code == code).first()
|
|
```
|
|
|
|
### 2. Database Indexes
|
|
|
|
```sql
|
|
-- Index for fast lookups
|
|
CREATE INDEX idx_vendors_code ON vendors(code);
|
|
CREATE INDEX idx_vendor_domains_domain ON vendor_domains(domain);
|
|
CREATE INDEX idx_products_vendor_id ON products(vendor_id);
|
|
```
|
|
|
|
### 3. Connection Pooling
|
|
|
|
Ensure database connection pool is properly configured:
|
|
|
|
```python
|
|
# sqlalchemy engine
|
|
engine = create_engine(
|
|
DATABASE_URL,
|
|
pool_size=20,
|
|
max_overflow=40,
|
|
pool_pre_ping=True
|
|
)
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [Middleware Stack](middleware.md) - How vendor detection works
|
|
- [Request Flow](request-flow.md) - Complete request journey
|
|
- [Architecture Overview](overview.md) - System architecture
|
|
- [Authentication & RBAC](auth-rbac.md) - Multi-tenant security
|
|
|
|
## Migration Guide
|
|
|
|
### Adding Multi-Tenancy to Existing Tables
|
|
|
|
```python
|
|
# Alembic migration
|
|
def upgrade():
|
|
# Add vendor_id to existing table
|
|
op.add_column('products',
|
|
sa.Column('vendor_id', sa.Integer(), nullable=True)
|
|
)
|
|
|
|
# Set default vendor for existing data
|
|
op.execute("UPDATE products SET vendor_id = 1 WHERE vendor_id IS NULL")
|
|
|
|
# Make non-nullable
|
|
op.alter_column('products', 'vendor_id', nullable=False)
|
|
|
|
# Add foreign key
|
|
op.create_foreign_key(
|
|
'fk_products_vendor',
|
|
'products', 'vendors',
|
|
['vendor_id'], ['id']
|
|
)
|
|
|
|
# Add index
|
|
op.create_index('idx_products_vendor_id', 'products', ['vendor_id'])
|
|
```
|