#Multi-Tenant Architecture

⚠️ PRELIMINARY DOCUMENTATION - NEEDS REVIEW

Note: This documentation was created with assumptions about the project architecture and technology stack. It requires review and correction based on the actual implementation.

This document will be reworked once the project is closer to final release.

If you notice inaccuracies (e.g., assumed AWS/CDN usage, incorrect tech stack), please flag them so this can be updated with actual project details.

---

Technical overview of Flash Turbo CMS multi-tenant architecture.

#System Overview

Flash Turbo CMS is a multi-tenant SaaS platform where multiple independent stores (tenants) run on shared infrastructure while maintaining complete data isolation.

graph TB
    subgraph Internet["🌐 Internet"]
        Customer["Customers"]
        Admin["Store Admins"]
    end
    
    subgraph CDN["Content Delivery Network"]
        CloudFront["AWS CloudFront"]
    end
    
    subgraph Frontend["Next.js Apps"]
        Store1["Tenant 1 Store"]
        Store2["Tenant 2 Store"]
        Manager["Manager/Admin UI"]
    end
    
    subgraph Backend["Payload CMS Backend"]
        Auth["Authentication"]
        Collections["Collections API"]
        Media["Media Manager"]
    end
    
    subgraph Database["Data Layer"]
        MongoDB["MongoDB"]
        Cache["Redis Cache"]
        S3["AWS S3 Storage"]
    end
    
    Customer -->|Browse| CloudFront
    Admin -->|Manage| Manager
    CloudFront --> Store1
    CloudFront --> Store2
    Store1 --> Backend
    Store2 --> Backend
    Manager --> Backend
    Backend --> Auth
    Backend --> Collections
    Backend --> Media
    Collections --> MongoDB
    Auth --> MongoDB
    Media --> S3
    Collections --> Cache

#Multi-Tenant Data Isolation

#Tenant Resolution

Each request identifies the tenant from:

1. Domain/URL: tenant1.yourdomain.com vs tenant2.yourdomain.com
2. Subdomain: store1 vs store2
3. Path: /tenant1/dashboard vs /tenant2/dashboard

#Data Isolation Strategy

Every collection includes a tenantId or tenantKey field:

// Products collection
{
  id: "prod_123",
  name: "Coffee Beans",
  tenantId: "tenant_abc",        // ← Tenant isolation
  price: 29.99,
  createdAt: "2025-01-01T00:00:00Z"
}

Access Control:

// Only return products for current tenant
const products = await db.collection('products').find({
  tenantId: getCurrentTenantId()  // ← Enforced in queries
});

#Enforcement Points

1. API Layer: All queries filter by tenant automatically
2. Database Level: Indexes on tenantId for performance
3. Middleware: Tenant validation before processing
4. Hooks: Auto-set tenant on create operations

#Architectural Components

#1. Frontend Layer (Next.js)

Tenant Store (apps/multi-store/)

• Customer-facing storefront
• Product browsing
• Shopping cart
• Checkout

Tenant Manager (apps/multi-store/app/(manager)/)

• Admin dashboard
• Product management
• Order management
• Settings

Shared Components (apps/multi-store/src/components/)

• Reusable UI components
• Layout components
• AI Chat overlay

#2. Backend Layer (Payload CMS)

Collections (Data Models):

• Products, Orders, Customers, Pages, etc.
• Each has tenant isolation
• Custom access control via hooks

Endpoints (Custom APIs):

• Collection endpoints for CRUD
• Custom business logic endpoints
• Webhook handlers

Plugins (Extensions):

• Multi-tenant plugin (auto-adds tenantId)
• Payment plugin (Razorpay integration)
• Revalidation plugin (cache invalidation)

#3. Database Layer (MongoDB)

Collections (MongoDB):

• Stored as MongoDB collections
• Indexed by tenantId for queries
• Separate indexes per tenant
• Transactions within same tenant

Performance:

• Sharding by tenantId
• Indexes on common queries
• Connection pooling
• Query optimization

#4. Cache Layer (Redis)

Purpose: Speed up repeated queries

Strategy: Tenant-specific cache keys

// Cache key format
const key = `tenant_${tenantId}_products_${productId}`;

Invalidation: When data changes, clear tenant's cache

#5. Storage Layer (AWS S3)

Purpose: Store product images, documents, files

Organization:

s3://bucket/
├── tenant_abc/
│   ├── products/
│   ├── orders/
│   └── uploads/
├── tenant_xyz/
│   ├── products/
│   ├── orders/
│   └── uploads/

Access Control:

• Each tenant can only access their folder
• Pre-signed URLs for direct access
• Encryption at rest

#Request Flow

#Customer Browsing Product

sequence
    Customer->>CDN: GET /products
    CDN->>Store: Return cached page
    Store->>API: GET /api/products
    API->>Auth: Resolve tenant from domain
    Auth->>DB: Query products WHERE tenantId=ABC
    DB->>Cache: Check cache
    Cache-->>DB: Cache hit/miss
    DB->>Store: Return products
    Store->>Customer: Render page with products

#Admin Creating Product

sequence
    Admin->>Manager: Fill product form
    Manager->>API: POST /collections/products
    API->>Auth: Verify admin of tenant ABC
    Auth->>Validator: Validate product data
    Validator->>DB: Insert with tenantId=ABC
    DB->>Cache: Invalidate product cache
    Cache->>Revalidation: Trigger revalidation
    Revalidation->>CDN: Purge old page cache
    API->>Manager: Return created product
    Manager->>Admin: Show success

#Tenant Separation Layers

#1. Domain Layer

• Each tenant has own domain
• DNS resolves to same app
• App reads domain to identify tenant

#2. Request Layer

• Middleware validates tenant
• Ensures user belongs to tenant
• Prevents cross-tenant access

#3. Query Layer

• All queries filtered by tenant
• At ORM/API level
• Database enforces via indexes

#4. Cache Layer

• Separate cache namespaces per tenant
• Cache key includes tenantId
• No cross-contamination

#5. File Layer

• Separate S3 folders per tenant
• Pre-signed URLs scoped to tenant
• No direct bucket access

#Security Implications

#Isolation Guarantees

✅ No data leaks

• One tenant can't see another's data
• Queries filtered at every level

✅ Access control

• Users only access their tenant
• Admin/Manager permissions per-tenant

✅ Rate limiting

• Per-tenant rate limits
• Prevent one tenant impacting others

#Potential Risks (& Mitigations)

⚠️ SQL Injection

• Mitigation: Use parameterized queries (ORM)
• Mitigation: Validate all inputs

⚠️ Cache poisoning

• Mitigation: Tenant-specific cache keys
• Mitigation: Regular cache invalidation

⚠️ File access

• Mitigation: Pre-signed URLs with expiry
• Mitigation: S3 access policies per tenant

#Performance Considerations

#Query Optimization

1. Index Strategy

   db.products.createIndex({ tenantId: 1, name: 1 })
   

   • tenantId first (partition pruning)
   • Then business logic index

2. Query Pattern

   // Always lead with tenantId
   await db.products.find({
     tenantId: "tenant_abc",    // ← First
     status: "published"
   })
   

3. Avoiding N+1 Queries

   • Use joins/lookups when possible
   • Load related data together
   • Cache frequently accessed relationships

#Caching Strategy

1. Cache Keys

   tenant_{id}_{entity}_{pk}
   tenant_abc_products_123
   

2. TTL (Time To Live)

   • Products: 1 hour
   • Orders: 15 minutes
   • Settings: 30 minutes
   • Variable per entity

3. Invalidation

   • On create/update/delete
   • Pattern matching for related caches
   • Full cache clear for tenant on settings change

#Scaling Considerations

#Horizontal Scaling

Currently: Single MongoDB instance Future: MongoDB sharding by tenant

// Shard key ensures tenant locality
db.products.createIndex({ tenantId: "hashed" })

#Vertical Scaling

• Increase MongoDB RAM for larger dataset
• Increase Redis for better caching
• Increase Node.js instances behind load balancer

#Database Optimization

• Regular index maintenance
• Query analysis and optimization
• Connection pool tuning
• Archive old data

#Related Documentation

• Data Flow Diagram
• Payment Integration
• Caching Strategy
• Implementation: Multi-Tenancy Implementation

---

Last Updated: October 27, 2025 Version: 1.0 Status: ✅ Production Ready