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. A domain belongs to one tenant only: creating or editing a tenant, or adding a domain to one, is refused while another tenant holds that domain (as its primary or one of its other domains). Two tenants on one domain would make every request to it fail. Removing a domain is never refused, so an existing clash can be cleared from either tenant

Customization Per Tenant

  • Theme System: Different visual themes per tenant
  • Layout Customization: Site-specific page layouts and components
  • Extensions per tenant: each tenant chooses which extensions appear on its pages, and an extension written for one customer can be offered to that customer's site only
  • Localization: Per-tenant language and currency (one currency per site)
  • Custom Business Rules: Different pricing, VAT settings 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

Hosts that aren't a live shop

A host that is no shop's (including a shop's own domain on a plan without one) and every page of an archived shop, its admin and fulfiller portal included, show the "shop not found" page ("This shop is lost in the forest", 404; TenantResolutionFilter and RequestInterceptFilter). On an archived shop, System, signing in and out, Stripe's payment webhooks and the unsubscribe and confirmation links in emails already sent stay open.

The admin and System sites' storefront pages (system.bdgr.co.uk/collection/home) redirect (302) to badger.shop.platform-home-url (production: https://www.bdgr.co.uk, overridden by BADGER_PLATFORM_HOME_URL): they aren't shops. Their home (/) opens /admin or /system instead; admin, System, sign-in, the JSON their screens fetch and anything that isn't a GET or HEAD (webhooks) carry on. With the setting blank (the local stack) they keep their storefront.

The admin and System sites can't be archived or deleted (SiteManagementServiceImpl.archiveSite, SiteDataDeletionServiceImpl.canDeleteSite): every admin and System screen loads their records. To take a hostname off one, set its primary domain to a name that never resolves (admin.invalid, system.invalid; the primary domain can't be blank) and remove its other domains; the host then counts as no shop's. Their themes (System, Admin) have no theme record, so the tenant form lists the current one on its own and updateSite never moves them onto a storefront theme: on Nova, System and every admin page fail to render.

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)