Skip to main content

Multi-Tenant Architecture

LusterCMS supports a full multi-tenant SaaS architecture, allowing you to run a platform where multiple organizations share the same infrastructure while maintaining complete data isolation. This enterprise-grade architecture includes per-tenant databases, isolated object storage, and dedicated Kubernetes deployments for themes.

Hierarchy​

SUPERADMIN (Platform Owner)
    │
    ├── Partner Groups (optional grouping)
    │
    └── ADMIN / AGENCY (Supervisor/Reseller)
            │
            └── ORGANIZATION (End Customer)
                    │
                    ├── Users (client_admin, editor, viewer)
                    │
                    └── Isolated Resources:
                        ├── Database (tenant_{slug})
                        ├── S3 Bucket (org-{id}-media)
                        └── K8s Theme Pod (theme-{id})

Roles​

RoleDescriptionAccess
superadminPlatform ownerFull access to everything
admin / agency_adminAgency managing 1..N organizationsOwn org + all descendant clients
client_adminOrganization adminFull access to their own organization
editorContent editorContent management, no settings
viewerRead-only userView only

Access Rule: "Everything Down, Nothing Up" (Golden Rule)​

Permissions, data, and credits flow downward only:

🔴 Superadmin                    → sees ALL organizations and data
🟡 Agency Admin (All Orgs view)  → sees OWN org + ALL descendant clients
🟢 Regular User                  → sees ONLY own organization
  • Superadmins can see and manage all organizations and their admins
  • Agency admins can see their agency org + all client organizations they manage
  • Client admins see only their own organization
  • Credits are always scoped per organization and can be allocated downward, but never upward

This means a client_admin can never see data from other organizations, and an agency admin can never access other agencies or platform-level settings.

Key Features​

1. Database Isolation​

Each organization has its own separate PostgreSQL database.
No data is shared between organizations; superadmins and agency admins can switch contexts for management, but each org's data stays completely isolated.

This ensures:

  • Complete data separation
  • Individual backup/restore capability
  • Performance isolation
  • Compliance with data residency requirements

2. Media Storage Isolation (MinIO S3)​

Enterprise-grade media storage with per-organization buckets:

MinIO S3 Storage
├── org-1-media/         # Organization 1's files
│   └── 2024/12/
├── org-2-media/         # Organization 2's files
│   └── 2024/12/
└── system-media/        # Platform-wide assets

Features:

  • Each organization gets isolated bucket: org-{id}-media
  • RBAC-aware file access (agency admins see their scope)
  • Cloudflare CDN for public asset delivery
  • Automatic bucket provisioning during registration

3. Theme Deployment (Kubernetes)​

Per-organization theme deployments for complete isolation:

  • Each organization gets a dedicated Kubernetes pod
  • Resource tiers: Starter, Pro, Enterprise
  • Horizontal Pod Autoscaling (Pro/Enterprise)
  • Network policies prevent cross-tenant access
  • Automatic SSL via cert-manager

4. Registration Flow​

Two registration paths based on account type:

ORGANIZATION (website or e-commerce):

  1. Customer submits registration form
  2. Selects project type: website or e-commerce
  3. Auto-provisioned immediately:
    • Database created
    • Theme assigned based on project type
    • Demo data seeded (optional, default ON)
    • Theme deployed to Kubernetes
  4. Email verification sent
  5. First-login loader + welcome tour

AGENCY (requires approval):

  1. Customer submits registration + agency survey
  2. Request enters approval queue
  3. Superadmin reviews and approves/rejects
  4. Upon approval: database, theme, K8s deployment
  5. Customer receives welcome email

5. Credit System​

Credits flow from top to bottom:

  • Superadmin grants credits to Admins/Agencies
  • Admins set credit limits for their organizations
  • Organizations can also purchase credits directly via Stripe
  • Usage is tracked and limited automatically

Credits are always scoped per organization and can be allocated downward, but never upward.

6. Plugin Management​

Each organization can have different plugins enabled based on project_type:

Project TypeDefault Plugins
WebsiteSEO Assistant
E-commerceE-commerce, SEO Assistant

Available plugins:

  • E-Commerce (shop, products, orders)
  • LinkedIn Publisher (scheduling)
  • Calendar (events)
  • Analytics
  • Forms
  • And more...

The sidebar automatically shows only enabled plugins.

7. Organization Context Switching​

The admin panel header includes an organization switcher:

  • Superadmins: Can switch to any organization or "All Organizations"
  • Agency Admins: Can switch between their agency org and client organizations
  • Regular users: See only their own organization (no switcher)

8. Custom Domains​

Organizations can use custom domains (e.g., shop.yourcompany.com) for white-label access:

  • Automatic SSL provisioning
  • DNS record instructions provided
  • Custom domains per tier limits

9. White-Label Branding​

Admins can configure branding for their clients:

  • Custom logo
  • Brand colors
  • Custom app name
  • Footer text
  • Support contact

10. First-Login Experience​

New users see a beautiful animated loader on first login:

  • Progress through setup steps
  • Followed by Intro.js welcome tour
  • Highlights key navigation areas