Skip to content

Multi-Tenancy Architecture

BadgerCommerce is built from the ground up as a true multi-tenant platform, allowing you to run multiple distinct storefronts from a single installation while maintaining complete separation of data and customization.

Key Features

Tenant Isolation

  • Secure Data Separation: Complete isolation of customer, product, and order data between sites
  • Tenant Context Awareness: All operations automatically scoped to the current tenant
  • Shared Infrastructure: Efficient resource utilization with shared database and application servers
  • Individual Branding: Each tenant can have its own branding, domain, and identity
  • Tenant-specific Settings: Configuration values can be defined at the tenant level

Multi-site Management

  • Centralized Administration: Manage all sites from a single admin interface
  • Per-site Administration: Delegate site-specific administration to individual teams
  • Site Templates: Create new sites quickly using predefined templates
  • Site Cloning: Clone existing sites as a starting point for new ones
  • Domain Management: Map multiple domains to each tenant

Customization Per Tenant

  • Theme System: Different visual themes per tenant
  • Layout Customization: Site-specific page layouts and components
  • Custom Extensions: Enable or disable specific features by tenant
  • Localization: Per-tenant language and currency settings
  • Custom Business Rules: Different pricing, tax, and shipping rules by tenant

Shared Capabilities

  • Catalog Sharing: Optionally share product catalogs between sites
  • Cross-site Reporting: Consolidated reporting across all tenants
  • Shared Services: Core services like payment processing shared across tenants
  • Global Configuration: Platform-wide settings affecting all tenants
  • Resource Pooling: Efficient utilization of system resources

Technical Implementation

The multi-tenancy system is implemented using:

  • Tenant context propagation throughout the application
  • Database-level tenant filtering
  • Request routing based on domain or URL patterns
  • Tenant-aware caching strategies
  • Hierarchical configuration system

Key components include: - TenantContext: Core class that maintains tenant context - SiteContextProducer: Resolves tenant information from requests - MongoDB queries automatically scoped to current tenant - Resource repositories with tenant-specific overrides

Integration Points

The multi-tenancy system integrates with: - Authentication: Tenant-specific user bases and authentication - Content Management: Site-specific content and assets - Theme Engine: Visual customization per tenant - Extension System: Feature customization by tenant - Analytics: Segmented reporting by tenant

Administration

Multi-tenant capabilities are managed through: - Global admin dashboard for tenant creation and management - Tenant-specific admin interfaces for site customization - Permissions system for delegated administration - Tenant activation/deactivation controls - Usage monitoring and resource allocation

Editing a tenant's image path

A tenant's Image path is the base URL every media image on that tenant (product, blog and page images) is loaded from. It is normally the image CDN, e.g. //images.bdgr.co.uk. Superadmins can change it under System → Tenants → {site}; it is deliberately not on the site-admin settings page.

Rules, enforced in Java (ProductImagePaths) both by the controller and by SiteManagementService.updateSite:

  • The value is trimmed and any trailing slash is removed.
  • Only //host[/path] or https://host[/path] is accepted. javascript:, data:, plain http:, relative paths, query strings and fragments are rejected.
  • A blank value is an error rather than a reset, so the field can't be wiped by accident. Leaving the field out of the request leaves the stored value unchanged.

The change takes effect without a restart: saving a SiteContext evicts the site caches on every pod (see SiteContextCacheEvictionListener), the same as other tenant edits such as name, logo and theme.

What a New Site Starts With

SiteManagementService.createSite gives a new site the following:

  • Home page: a page with seoName home. Its content is a welcome block plus a product grid (a jsonComponent bound to the featured collection). / shows it at the site root: the landingPageRedirectURL config key is /p/home, and useRedirectForLandingPage is false.
  • Featured collection: featured, which holds the sample product.
  • Default pages: About Us, Contact, and a blog with a welcome post.
  • Main menu: main-menu, made the storefront's navigation through default-menu-id. It links About Us, Blog and Contact. There is no Home item, because every theme's logo already links to /.
  • Default setup: the default stereotypes, one placeholder delivery option, and the owner account.

Sites created before this used a collection called home as the home page. It had a "Home Page" title and a sort row above everything. Those sites keep working unchanged: landingPageRedirectURL still defaults to /collection/home.

Site Data Transfer

BadgerCommerce includes built-in Site Data Transfer capabilities for copying catalogue and configuration data between tenants:

  • Export: Download products, collections, pages, and configuration as a portable ZIP file
  • Import: Import data into any tenant with automatic ID remapping
  • Privacy Safe: Automatically excludes all PII, orders, users, and sensitive configuration
  • Environment Sync: Ideal for syncing development/staging with production catalogue data

See the Site Data Transfer documentation for full details.

Upcoming Features

  • Enhanced tenant isolation options
  • White-label capabilities for resellers
  • Improved tenant resource monitoring
  • Cross-tenant search capabilities (optional)