Broadleaf Microservices
  • v1.0.0-latest-prod


Tenants and Applications

Broadleaf is designed to allow running completely separate companies out of the same Broadleaf installation. We have several domain concepts in place to support this model: Tenant and Application. Think of a tenant as a company that has its own data, backoffice, and customer-facing experiences. A tenant is never able to see or interact with another tenant’s data. Think of an application as an API covering a unique combination of assets, pricing, offers, and catalogs in that tenant. This traditionally includes website, micro-sites, and even mobile-specific applications, if applicable. On top of these concepts is the global backoffice tooling controlled by super administrative users. These users own the maintenance of supporting concepts for the various applications in the tenant (e.g. shared catalogs, shared pricelists, etc…​). Tenancy can be further expanded into marketplace use cases where a tenant supports multiple catalogs, each maintained by a different vendor. These catalogs are then inherited by a marketplace application with final control over presentation and pricing exposed in the marketplace customer experience.


The model is further expanded beyond Tenant and Application with the concept of Catalogs. Catalogs are primarily a merchandising concept and allow configuration of category and product related concepts into an inheritance tree. Arranging catalog information in this manner allows for sophisticated composition and override behavior, based on the level at which the information is consumed. For example, a base catalog could establish a category structure. A second catalog could inherit that structure and add products. A third catalog could inherit from the second and change attributes, or add several more products. Next, an application could be assigned the second catalog, while a different application could get the third. This allows you to expose a different product mix with different characteristics to different applications. Combine this with other factors like user attributes and you can achieve very complex behavior.

Catalog filters are a fine-tuning construct available during catalog configuration that allows filtering control (inclusion and exclusion) of records from a parent catalog based on one or more persistence fields. This allows repurposing the same catalog with variations for tangential concerns. For example, a catalog might be setup to have all clothing from multiple brands. However, you want to create a micro-site that focuses on a single brand while still allowing that brand to co-exist in the larger clothing catalog for universal consumption in another application.

The cascade of updates through a catalog tree is referred to as Propagation. Propagation occurs when an admin user makes a change to a catalog discriminated entity, and then promotes and deploys that change. The deployed change trickles down through the catalog tree and updates any overrides in other catalogs as well (as long as the updated field(s) was not already overridden in the subordinate catalog).


Customer accounts can be scoped to any number of applications. For example, each application can have a unique set of customers, or multiple applications can share the same set of customers.


It is important to consider the applications that will be exposed, and then consider their merchandising needs. Setting up a catalog structure based on a partitioning scheme that mirrors the primary merchandising partitioning strategies will provide the most flexibility and simplicity.

Consider some example models:

Traditional B2C Model

  • For example, a clothing retailer

  • Single or few catalogs represent available products

  • Single application exposes products online through single site

Multiple Store Model

  • For example, and electronics retailer

  • Variation on traditional model

  • Single or few catalogs represent available products

  • Single application exposes products online through single site

  • Additional fulfillment options expose pick-up-in-store via multiple inventory locations

Dealer Model

  • Single or few catalogs represent available products (e.g. auto parts)

  • Products are common (or mostly common) to multiple dealers

  • Each dealer sells items from the common catalog (possibly filtered)

  • The aggregation site sells product through dealers, perhaps via shipping from the dealer, or pick up in store

  • The aggregation site handles context switching between dealers on behalf of the users based on some criteria (e.g. location)

  • White label sites are also offered for dealers to have a unique customer experience limited to just that dealer’s offering

Multi-Catalog / Multi-Target Model

  • For example, a loyalty program vendor

  • Curated gift collections customized to each program client

  • Basic category structure defined in top-level catalog

  • Individual catalog curated by each item vendor (vendor is responsible for basic merchandising)

  • Each application is customized for a particular program client, including the gift vendor catalogs to include in the customized program

Multi-Catalog / Single-Target Model

  • For example, a marketplace

  • Basic category structure defined in top-level catalog

  • Individual catalog curated by each vendor (vendor is responsible for basic merchandising)

  • The marketplace application inherits each vendor catalog

  • The marketplace may override values, if applicable

  • The same sku, possibly with different pricing, is distinguishable by vendor (if applicable)

Partitioned Catalog Model

  • For example, a florist

  • Because of logistics, not all products are available in all regions

  • Merchandisers already address their business in a partitioned way, for example, by region

  • A single application (possibly multiple) pull from one or more catalogs to create a specific available mix

  • The catalog mix could be driven by application configuration, or dynamically by customer attribute

Developer Considerations

For the most part, the aspects described above inform backoffice user decisions and behavior. The creation of applications and catalogs is a business user task in the admin tool. However, extensions of the application domain to add needed fields to support custom business cases is generally a code level concern. Furthermore, creation of new domain that adheres to proper catalog or application discrimination is supported in a straightforward way and is also a code level concern. By extending the Broadleaf domain, or adding new domain, you can enrich the catalog and application support and solve new use cases unique to your business. For example, extending the Broadleaf Product class is very common in order to add new required fields unique to your case. It is also common to introduce an entirely new domain class that participates in catalog discrimination and inherits all the sandbox transition and catalog propagation behavior. These types of customizations, and more, are supported.

Refer to Extensibility for more information on the types of extensions available.

Refer to Sandboxing In Detail for more information on domain class design.

Refer to Tenant Services for more information on tenant related domain, service API, and key flows.