docs: Add docs on multi-tenancy

docs/content/developer-guide/channels.md → docs/content/developer-guide/channels/index.md

@@ -15,6 +15,8 @@ Channels are a feature of Vendure which allows multiple sales channels to be rep
 
 Every Vendure server always has a **default Channel**, which contains _all_ entities. Subsequent channels can then contain a subset of the above entities.
 
+{{< figure src="channels_diagram.png" >}}
+
 Use-cases of Channels include:
 
 * Multi-region stores, where there is a distinct website for each territory with its own available inventory, pricing, tax and shipping rules.
@@ -28,3 +30,5 @@ To specify which channel to use when making an API call, set the `'vendure-token
 ## Multi-Tenant (Marketplace) Support
 
 Channels can also be used to implement a multi-tenant or marketplace application. In such a setup, each merchant would have their own dedicated Channel and would be granted permissions on that Channel only.
+ 
+For a detailed guide on how this would be set up, see our [Multi-Tenant guide]({{< relref "multi-tenant" >}}).

docs/content/developer-guide/multi-tenant/index.md

@@ -0,0 +1,69 @@
+---
+title: 'Multi-Tenant'
+showtoc: true
+---
+
+# Multi-tenancy Support
+
+Vendure supports multi-tenant headless commerce solutions through its powerful [Channels]({{< relref "channels" >}}) feature.
+
+Channels allow us to segment our business entities per tenant. To do this, you would create a separate Channel per tenant.
+
+## Creating Tenants
+
+Let's say we want to use a single Vendure instance to run 2 separate e-commerce businesses: **Ace Parts** and **Best Choice**. First we need to create a new Channel for each:
+
+{{< figure src="create-channel.png" title="Creating a new Channel via the Admin UI" >}}
+
+Do this for both of our tenants: `ace-parts` and `best-choice`.
+
+## Defining Roles
+
+The next requirement is being able to create Administrators who have permissions only for a given tenant. This is supported by Vendure's role-based access control system.
+
+First we will create a new Role, and grant all permissions on the `ace-parts` Channel only:
+
+{{< figure src="create-role.png" title="Creating a Channel-specific Role" >}}
+
+Next we create a new Administrator, and assign the Role that was just created.
+
+{{< figure src="create-admin.png" title="Creating a Channel-specific Role" >}}
+
+Repeat the steps of creating a Role and Administrator for the `best-choice` Channel.
+
+Now you've successfully set up your two tenants and you have an admin account for each.
+
+## Mechanics of Multi-Tenancy
+
+Each tenant is modelled as a Channel, and both of our new Channels can be considered "children" of the **default Channel**. That is, the default Channel contains every Product, Customer, Order, Promotion etc., no matter which Channel they were created in.
+
+{{< figure src="../channels/channels_diagram.png" >}}
+
+In this way, the default Channel can be used by the superadmin account to get an overview of the entire instance, whereas the admins of each tenant will only have access to the entities assigned to their respective Channels.
+
+The following entities are "channel-aware", i.e. they can be assigned to a specific Channel:
+
+* Asset
+* Collection
+* Customer
+* Facet/FacetValue
+* Order
+* PaymentMethod
+* Product/ProductVariant
+* Promotion
+* Role
+* ShippingMethod
+
+In the Admin UI, you can switch between active Channels using the switcher component in the top bar:
+
+{{< figure src="channel-selector.png" title="Switching between Channels" >}}
+
+For example, switching to the `ace-parts` Channel, and then creating a new Product will assign that new Product to the `ace-parts` Channel (_and_ the default Channel, since _everything_ is assigned to the default Channel).
+
+## The Storefront
+
+Your storefront applications will need to specify which channel they are interested in. This is done by adding a query parameter or header to each API requests, with the key being `vendure-token` and the value being the target Channel's `token` property.
+
+```text
+https://my-vendure-server.com/shop-api?vendure-token=best-choice
+```

docs/diagrams/channels-diagram.puml

@@ -0,0 +1,25 @@
+@startuml
+!include theme.puml
+title Channels in Vendure
+
+node DefaultChannel as "Default Channel" {
+  [All Products\nAll Collections\nAll Customers\nAll Orders]
+}
+
+package ChannelA as "Channel A" {
+  [Products A\nCollections A\nCustomers A\nOrders A]
+}
+
+package ChannelB as "Channel B" {
+  [Products B\nCollections B\nCustomers B\nOrders B]
+}
+
+package ChannelC as "Channel C" {
+  [Products C\nCollections C\nCustomers C\nOrders C]
+}
+
+DefaultChannel -down-> ChannelA
+DefaultChannel -down-> ChannelB
+DefaultChannel -down-> ChannelC
+
+@enduml