docs: More core concepts guides

docs/docs/guides/core-concepts/authentication/index.md → docs/docs/guides/core-concepts/auth/index.md

@@ -1,22 +1,107 @@
 ---
-title: 'Authentication'
+title: 'Auth'
 ---
 
-Authentication is the process of determining the identity of a user. Common ways of authenticating a user are by asking the user for secret credentials (username & password) or by a third-party authentication provider such as Facebook or Google login.
+**Authentication** is the process of determining the identity of a user. Common ways of authenticating a user are by asking the user for secret credentials (username & password) or by a third-party authentication provider such as Facebook or Google login.
 
-By default, Vendure uses a username/email address and password to authenticate users, but also supports a wide range of authentication methods via configurable AuthenticationStrategies.
+**Authorization** is a related concept, which means that once we have verified the identity of a user, we can then determine what that user is allowed to do. For example, a user may be authorized to view a product, but not to edit it.
+
+The term **auth** is shorthand for _both_ authentication and authorization.
+
+Auth in Vendure applies to both **administrators** and **customers**. Authentication is controlled by the configured `AuthenticationStrategies`, and authorization is controlled by the configured `Roles` and `Permissions`.
+
+## Administrator auth
+
+Administrators are required to authenticate before they can perform any operations in the Admin API.
+
+Here is a diagram of the parts that make up Administrator authentication:
+
+![Administrator authentication](./admin.webp)
+
+Roles can be created to allow fine-grained control over what a particular administrator has access to (see the section below).
+
+## Customer auth
+
+Customer only need to authenticate if they want to access a restricted operation related to their account, such as 
+viewing past orders or updating an address.
+
+Here are the parts that make up Customer authentication:
+
+![Customer authentication](./customer.webp)
+
+### Guest customers
+
+Vendure also supports **guest customers**, meaning that a customer can place an order without needing to register an account, and thus not getting an
+associated user or role. A guest customer, having no roles and thus no permissions, is then unable to view past orders or access any other restricted API
+operations.
+
+However, a guest customer can at a later point register an account using the same email address, at which point they will get a user with the "Customer" role,
+and be able to view their past orders.
+
+
+## Roles & Permissions
+
+Both the `Customer` and `Administrator` entities relate to a single [`User`](/reference/typescript-api/entities/user/) entity which in turn has one or more [`Roles`](/reference/typescript-api/entities/role/) for controlling permissions.
+
+
+![Administrators & Roles](./admin-role.webp)
+
+In the example above, the administrator Sam Bailey has two roles assigned: "Order Manager" and "Catalog Manager". An administrator
+can have any number of roles assigned, and the permissions of all roles are combined to determine the permissions of the
+administrator. In this way, you can have fine-grained control over which administrators can perform which actions.
+
+There are 2 special roles which are created by default and cannot be changed:
+
+- **SuperAdmin**: This role has all permissions, and cannot be edited or deleted. It is assigned to the first administrator
+  created when the server is started.
+- **Customer**: This role is assigned to all registered customers.
+
+
+All other roles can be user-defined. Here's an example of an "Inventory Manager" role being defined in the Admin UI:
+
+![Inventory Manager role](./roles.webp)
+
+
+
+## Native authentication
+
+By default, Vendure uses a username/email address and password to authenticate users, which is implemented by the [`NativeAuthenticationStrategy`](/reference/typescript-api/auth/native-authentication-strategy/).
+
+There is a `login` mutation available in both the Shop API and Admin API which allows a customer or administrator to authenticate using
+native authentication:
+
+```graphql title="Admin API"
+mutation {
+  login(username: "superadmin", password: "superadmin") {
+    ...on CurrentUser {
+      id
+      identifier
+    }
+    ...on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
 
 :::info
 See the [Managing Sessions guide](/TODO) for how to manage authenticated sessions in your storefront/client applications.
 :::
 
-## Adding support for external authentication
+## External authentication
+
+In addition to the built-in `NativeAuthenticationStrategy`, it is possible to define a custom [`AuthenticationStrategy`](/reference/typescript-api/auth/authentication-strategy) which allows your Vendure server to support other authentication methods such as:
 
-This is done via the [`VendureConfig.authOptions` object](/reference/typescript-api/auth/auth-options/#shopauthenticationstrategy):
+- Social logins (Facebook, Google, GitHub, etc.)
+- Single Sign-On (SSO) providers such as Keycloak, Auth0, etc.
+- Alternative factors such as SMS, TOTP, etc.
+
+Custom authentication strategies are set via the [`VendureConfig.authOptions` object](/reference/typescript-api/auth/auth-options/#shopauthenticationstrategy):
 
 ```ts title="vendure-config.ts"
-import { VendureConfig } from '@vendure/core';
-import { NativeAuthenticationStrategy } from './plugins/authentication/native-authentication-strategy';
+import { VendureConfig, NativeAuthenticationStrategy } from '@vendure/core';
+
 import { FacebookAuthenticationStrategy } from './plugins/authentication/facebook-authentication-strategy';
 import { GoogleAuthenticationStrategy } from './plugins/authentication/google-authentication-strategy';
 import { KeycloakAuthenticationStrategy } from './plugins/authentication/keycloak-authentication-strategy';
@@ -42,11 +127,13 @@ The other strategies would be custom-built (or provided by future npm packages)
 
 Let's take a look at a couple of examples of what a custom AuthenticationStrategy implementation would look like.
 
-## Example: Google authentication
+## Custom authentication examples
+
+### Google authentication
 
 This example demonstrates how to implement a Google login flow.
 
-### Storefront setup
+#### Storefront setup
 
 In your storefront, you need to integrate the Google sign-in button as described in ["Integrating Google Sign-In into your web app"](https://developers.google.com/identity/sign-in/web/sign-in). Successful authentication will result in a `onSignIn` function being called in your app. It will look something like this:
 
@@ -70,7 +157,7 @@ function onSignIn(googleUser) {
 }
 ```
 
-### Backend
+#### Backend
 
 On the backend, you'll need to define an AuthenticationStrategy to take the authorization token provided by the
 storefront in the `authenticate` mutation, and use it to get the necessary personal information on that user from
@@ -158,11 +245,11 @@ export class GoogleAuthenticationStrategy implements AuthenticationStrategy<Goog
 }
 ```
 
-## Example: Facebook authentication
+### Facebook authentication
 
 This example demonstrates how to implement a Facebook login flow.
 
-### Storefront setup
+#### Storefront setup
 
 In this example, we are assuming the use of the [Facebook SDK for JavaScript](https://developers.facebook.com/docs/javascript/) in the storefront.
 
@@ -225,6 +312,8 @@ export const FBLoginButton = () => {
 };
 ```
 
+#### Backend
+
 ```ts title="/src/plugins/authentication/facebook-authentication-strategy.ts"
 import {
     AuthenticationStrategy,
@@ -325,13 +414,13 @@ export class FacebookAuthenticationStrategy implements AuthenticationStrategy<Fa
 }
 ```
 
-## Example: Keycloak authentication
+### Keycloak authentication
 
 Here's an example of an AuthenticationStrategy intended to be used on the Admin API. The use-case is when the company has an existing identity server for employees, and you'd like your Vendure shop admins to be able to authenticate with their existing accounts.
 
 This example uses [Keycloak](https://www.keycloak.org/), a popular open-source identity management server. To get your own Keycloak server up and running in minutes, follow the [Keycloak on Docker](https://www.keycloak.org/getting-started/getting-started-docker) guide.
 
-### Configure a login page & Admin UI
+#### Configure a login page & Admin UI
 
 In this example, we'll assume the login page is hosted at `http://intranet/login`. We'll also assume that a "login to Vendure" button has been added to that page and that the page is using the [Keycloak JavaScript adapter](https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter), which can be used to get the current user's authorization token:
 
@@ -379,7 +468,7 @@ export const config: VendureConfig = {
 };
 ```
 
-### Backend
+#### Backend
 
 First we will need to be making an HTTP call to our Keycloak server to validate the token and get the user's details. We'll use the [`node-fetch`](https://www.npmjs.com/package/node-fetch) library to make the HTTP call:
 

docs/docs/guides/core-concepts/channels/index.md

@@ -23,7 +23,7 @@ This is useful for a number of use-cases, including:
 
 Every Vendure server always has a **default Channel**, which contains _all_ entities. Subsequent channels can then contain a subset of channel-aware entities.
 
-![Channels high level](../../developer-guide/data-model/channels.webp)
+![Channels high level](./channels.webp)
 
 ## Channel-aware entities
 

docs/docs/guides/core-concepts/collections/index.mdx

@@ -0,0 +1,125 @@
+---
+title: 'Collections'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+[`Collections`](/reference/typescript-api/entities/collection/) are used to categorize and organize your catalog. A collection
+contains multiple product variants, and a product variant can belong to multiple collections. Collections can be nested to
+create a hierarchy of categories, which is typically used to create a menu structure in the storefront.
+
+![Collections](./collections.webp)
+
+Collections are not _only_ used as the basis of storefront navigation. They are a general-purpose organization tool which can be used
+for many purposes, such as:
+
+- Creating a collection of "new arrivals" which is used on the homepage.
+- Creating a collection of "best sellers" which is used to display a list of popular products.
+- Creating a collection of "sale items" which is used to apply a discount to all products in the collection, via a promotion.
+
+## Collection filters
+
+The specific product variants that belong to a collection are determined by the collection's [`CollectionFilters`](/reference/typescript-api/configuration/collection-filter/).
+A collection filter is a piece of logic which is used to determine whether a product variant should be included in the collection. By default, Vendure
+includes a number of collection filters:
+
+- **Filter by facet values**: Include all product variants which have a specific set of facet values.
+- **Filter by product variant name**: Include all product variants whose name matches a specific string.
+- **Manually select product variants**: Allows manual selection of individual product variants.
+- **Manually select products**: Allows manual selection of entire products, and then includes all variants of those products.
+
+![Collection filters](./collection-filters.webp)
+
+It is also possible to create your own custom collection filters, which can be used to implement more complex logic. See the section on [creating a collection filter](#creating-a-collection-filter) for more details.
+
+### Filter inheritance
+
+When a collection is nested within another collection, the child collection can inherit the parent's collection filters. This means that the child collection
+will _combine_ its own filters with the parent's filters.
+
+![Filter inheritance](./filter-inheritance.webp)
+
+In the example above, we have a parent collection "Menswear", with a child collection "Mens' Casual". The parent collection has a filter which includes all
+product variants with the "clothing" and "mens" facet values. The child collection is set to inherit the parent's filters, and has an additional filter which
+includes all product variants with the "casual" facet value.
+
+Thus, the child collection will include all product variants which have the "clothing", "mens" and "casual" facet values.
+
+:::note
+When filter inheritance is enabled, a child collection will contain a **subset** of the product variants of its parent collection.
+
+In order to create a child collection which contains product variants _not_ contained by the parent collection, you must disable filter inheritance
+in the child collection.
+:::
+
+### Creating a collection filter
+
+You can create your own custom collection filters with the [`CollectionFilter`](/reference/typescript-api/configuration/collection-filter/) class. This class
+is a [configurable operation](/guides/developer-guide/strategies-configurable-operations/#configurable-operations) where the specific
+filtering logic is implemented in the `apply()` method passed to its constructor.
+
+The `apply()` method receives an instance of the [TypeORM SelectQueryBuilder](https://typeorm.io/select-query-builder) which should have filtering logic
+added to it using the `.andWhere()` method.
+
+Here's an example of a collection filter which filters by SKU:
+
+```ts title="src/config/sku-collection-filter.ts"
+import { CollectionFilter, LanguageCode } from '@vendure/core';
+
+export const skuCollectionFilter = new CollectionFilter({
+    args: {
+        // The `args` object defines the user-configurable arguments
+        // which will get passed to the filter's `apply()` function.
+        sku: {
+            type: 'string',
+            label: [{ languageCode: LanguageCode.en, value: 'SKU' }],
+            description: [
+                {
+                    languageCode: LanguageCode.en,
+                    value: 'Matches any product variants with an SKU containing this value',
+                },
+            ],
+        },
+    },
+    code: 'variant-sku-filter',
+    description: [{ languageCode: LanguageCode.en, value: 'Filter by matching SKU' }],
+
+    // This is the function that defines the logic of the filter.
+    apply: (qb, args) => {
+        // Sometimes syntax differs between database types, so we use
+        // the `type` property of the connection options to determine
+        // which syntax to use.
+        const LIKE = qb.connection.options.type === 'postgres' ? 'ILIKE' : 'LIKE';
+
+        return qb.andWhere(`productVariant.sku ${LIKE} :sku`, {
+            sku: `%${args.sku}%`
+        });
+    },
+});
+```
+
+In the `apply()` method, the product variant entity is aliased as `'productVariant'`.
+
+This custom filter is then added to the defaults in your config:
+
+```ts title="src/vendure-config.ts"
+import { defaultCollectionFilters, VendureConfig } from '@vendure/core';
+import { skuCollectionFilter } from './config/sku-collection-filter';
+
+export const config: VendureConfig = {
+    // ...
+    catalogOptions: {
+        collectionFilters: [
+            ...defaultCollectionFilters,
+            // highlight-next-line
+            skuCollectionFilter
+        ],
+    },
+};
+```
+
+:::info
+To see some more advanced collection filter examples, you can look at the source code of the
+[default collection filters](https://github.com/vendure-ecommerce/vendure/blob/master/packages/core/src/config/catalog/default-collection-filters.ts).
+:::

docs/docs/guides/core-concepts/customers/index.mdx

@@ -0,0 +1,21 @@
+---
+title: "Customers"
+---
+
+A [`Customer`](/reference/typescript-api/entities/customer/) is a person who can buy from your shop. A customer can have one or more
+[`Addresses`](/reference/typescript-api/entities/address/), which are used for shipping and billing.
+
+If a customer has registered an account, they will have an associated [`User`](/reference/typescript-api/entities/user/). The user
+entity is used for authentication and authorization. **Guest checkouts** are also possible, in which case a customer will not have a user.
+
+:::info
+See the [Auth guide](/guides/core-concepts/auth/#customer-auth) for a detailed explanation of the relationship between
+customers and users.
+:::
+
+![Customer](./customer.webp)
+
+Customers can be organized into [`CustomerGroups`](/reference/typescript-api/entities/customer-group/). These groups can be used in
+logic relating to promotions, shipping rules, payment rules etc. For example, you could create a "VIP" customer group and then create
+a promotion which grants members of this group free shipping. Or a "B2B" group which is used in a custom tax calculator to
+apply a different tax rate to B2B customers.

docs/docs/guides/core-concepts/images-assets/index.mdx

@@ -0,0 +1,42 @@
+---
+title: "Images & Assets"
+---
+
+[`Assets`](/reference/typescript-api/entities/asset/) are used to store files such as images, videos, PDFs, etc. Assets can be
+assigned to **products**, **variants** and **collections** by default. By using [custom fields](/guides/concepts/custom-fields/) it is
+possible to assign assets to other entities. For example, for implementing customer profile images.
+
+The handling of assets in Vendure is implemented in a modular way, allowing you full control over the way assets
+are stored, named, imported and previewed.
+
+![Asset creation and retrieval](./asset-flow.webp)
+
+1. An asset is created by uploading an image. Internally the [`createAssets` mutation](/reference/graphql-api/admin/mutations/#createassets) will be executed.
+2. The [`AssetNamingStrategy`](/reference/typescript-api/assets/asset-naming-strategy/) is used to generate file names for the source image and the preview. This is useful for normalizing file names as well as handling name conflicts.
+3. The [`AssetPreviewStrategy`](/reference/typescript-api/assets/asset-preview-strategy) generates a preview image of the asset. For images, this typically involves creating a version with constraints on the maximum dimensions. It could also be used to e.g. generate a preview image for uploaded PDF files, videos or other non-image assets (such functionality would require a custom `AssetPreviewStrategy` to be defined).
+4. The source file as well as the preview image are then passed to the [`AssetStorageStrategy`](/reference/typescript-api/assets/asset-storage-strategy) which stores the files to some form of storage. This could be the local disk or an object store such as AWS S3 or Minio.
+5. When an asset is later read, e.g. when a customer views a product detail page which includes an image of the product, the `AssetStorageStrategy` can be used to
+read the file from the storage location.
+
+
+## AssetServerPlugin
+
+Vendure comes with the `@vendure/asset-server-plugin` package pre-installed. This provides the [`AssetServerPlugin`](/reference/typescript-api/core-plugins/asset-server-plugin/) which provides many advanced features to make working with
+assets easier.
+
+The plugin provides a ready-made set of strategies for handling assets, but also allows you to replace these defaults with
+your own implementations. For example, here are instructions on how to replace the default storage strategy with one
+that stores your assets on AWS S3 or Minio: [configure S3 asset storage](/reference/typescript-api/core-plugins/asset-server-plugin/s3asset-storage-strategy#configures3assetstorage)
+
+It also features a powerful image transformation API, which allows you to specify the dimensions, crop, and image format
+using query parameters.
+
+:::info
+See the [AssetServerPlugin docs](/reference/typescript-api/core-plugins/asset-server-plugin/) for a detailed description of all the features.
+:::
+
+## Asset Tags
+
+Assets can be tagged. A [`Tag`](/reference/typescript-api/entities/tag/) is a simple text label that can be applied to an asset. An asset can have multiple tags or none. Tags are useful for organizing assets, since assets are otherwise organized as a flat list with no concept of a directory structure.
+
+![Asset tags](./asset-tags.webp)

docs/docs/guides/core-concepts/orders/index.md

@@ -8,9 +8,14 @@ import TabItem from '@theme/TabItem';
 
 In Vendure, the [`Order`](/reference/typescript-api/entities/order/) entity represents the entire lifecycle of an order, from the moment a customer adds an item to their cart, through to the point where the order is completed and the customer has received their goods.
 
-The `Order` contains all the information about the order, such as the items (represented by the `OrderLine` entity), shipping address, payment method, shipping method, and so on.
+An [`Order`](/reference/typescript-api/entities/order/) is composed of one or more [`OrderLines`](/reference/typescript-api/entities/order-line/).
+Each order line represents a single product variant, and contains information such as the quantity, price, tax rate, etc.
+
+In turn, the order is associated with a [`Customer`](/reference/typescript-api/entities/customer/) and contains information such as
+the shipping address, billing address, shipping method, payment method, etc.
+
+![Order](./order.webp)
 
-![Order entity](../../developer-guide/data-model/order.webp)
 
 ## The Order Process
 

docs/docs/guides/core-concepts/products/index.mdx

@@ -0,0 +1,59 @@
+---
+title: "Products"
+---
+
+Your catalog is composed of [`Products`](/reference/typescript-api/entities/product/) and [`ProductVariants`](/reference/typescript-api/entities/product-variant/).
+A `Product` always has _at least one_ `ProductVariant`. You can think of the product as a "container" which includes a name, description, and images that apply to all of
+its variants.
+
+Here's a visual example, in which we have a "Hoodie" product which is available in 3 sizes. Therefore, we have
+3 variants of that product:
+
+![Products and ProductVariants](./products-variants.webp)
+
+Multiple variants are made possible by adding one or more [`ProductOptionGroups`](/reference/typescript-api/entities/product-option-group) to
+the product. These option groups then define the available [`ProductOptions`](/reference/typescript-api/entities/product-option)
+
+If we were to add a new option group to the example above for "Color", with 2 options, "Black" and "White", then in total
+we would be able to define up to 6 variants:
+
+- Hoodie Small Black
+- Hoodie Small White
+- Hoodie Medium Black
+- Hoodie Medium White
+- Hoodie Large Black
+- Hoodie Large White
+
+:::info
+When a customer adds a product to their cart, they are adding a specific `ProductVariant` to their cart, not the `Product` itself.
+It is the `ProductVariant` that contains the SKU ("stock keeping unit", or product code) and price information.
+:::
+
+## Product price and stock
+
+The `ProductVariant` entity contains the price and stock information for a product. Since a given product variant can have more
+than one price, and more than one stock level (in the case of multiple warehouses), the `ProductVariant` entity contains
+relations to one or more [`ProductVariantPrice`](/reference/typescript-api/entities/product-variant-price) entities and
+one or more [`StockLevel`](/reference/typescript-api/entities/stock-level) entities.
+
+![Price and stock](./product-relations.webp)
+
+## Facets
+
+[`Facets`](/reference/typescript-api/entities/facet/) are used to add structured labels to products and variants. A facet has
+one or more [`FacetValues`](/reference/typescript-api/entities/facet-value/). Facet values can be assigned to products or
+product variants.
+
+For example, a "Brand" facet could be used to label products with the brand name, with each facet value representing a different brand. You can
+also use facets to add other metadata to products and variants such as "New", "Sale", "Featured", etc.
+
+![Facets and FacetValues](./facets.webp)
+
+These are the typical uses of facets in Vendure:
+
+- As the **basis of [Collections](/guides/core-concepts/collections)**, in order to categorize your catalog.
+- To **filter products** in the storefront, also known as "faceted search". For example, a customer is on the "hoodies" collection
+page and wants to filter to only show Nike hoodies.
+- For **internal logic**, such as a promotion that applies to all variants with the "Summer Sale" facet value, or a shipping calculation
+that applies a surcharge to all products with the "Fragile" facet value. Such facets can be set to be private so that they
+are not exposed to the storefront.

docs/docs/guides/developer-guide/data-model/index.mdx

@@ -1,172 +0,0 @@
----
-title: 'Data Model'
-sidebar_position: 0
----
-
-This section will explain the main parts of Vendure's data model and how they relate to one another. In Vendure these
-objects are referred to as **entities**, following the terminology of the [TypeORM](https://typeorm.io/entities) library which
-is used to manage the database.
-
-## Catalog
-
-### Products & ProductVariants
-
-Your catalog is composed of [`Products`](/reference/typescript-api/entities/product/) and [`ProductVariants`](/reference/typescript-api/entities/product-variant/).
-A `Product` always has _at least one_ `ProductVariant`. You can think of the product as a "container" which includes a name, description, and images that apply to all of
-its variants.
-
-Here's a visual example, in which we have a "Hoodie" product which is available in 3 sizes. Therefore, we have
-3 variants of that product:
-
-![Products and ProductVariants](./products-variants.webp)
-
-Multiple variants are made possible by adding one or more [`ProductOptionGroups`](/reference/typescript-api/entities/product-option-group) to
-the product. These option groups then define the available [`ProductOptions`](/reference/typescript-api/entities/product-option)
-
-If we were to add a new option group to the example above for "Color", with 2 options, "Black" and "White", then in total
-we would be able to define up to 6 variants:
-
-- Hoodie Small Black
-- Hoodie Small White
-- Hoodie Medium Black
-- Hoodie Medium White
-- Hoodie Large Black
-- Hoodie Large White
-
-:::info
-When a customer adds a product to their cart, they are adding a specific `ProductVariant` to their cart, not the `Product` itself.
-It is the `ProductVariant` that contains the SKU ("stock keeping unit", or product code) and price information.
-:::
-
-### Facets
-
-[`Facets`](/reference/typescript-api/entities/facet/) are used to add structured labels to products and variants. A facet has
-one or more [`FacetValues`](/reference/typescript-api/entities/facet-value/). Facet values can be assigned to products or
-product variants.
-
-For example, a "Brand" facet could be used to label products with the brand name, with each facet value representing a different brand. You can
-also use facets to add other metadata to products and variants such as "New", "Sale", "Featured", etc.
-
-![Facets and FacetValues](./facets.webp)
-
-These are the typical uses of facets in Vendure:
-
-- As the **basis of Collections**, in order to categorize your catalog (see next section).
-- To **filter products** in the storefront, also known as "faceted search". For example, a customer is on the "hoodies" collection
-page and wants to filter to only show Nike hoodies.
-- For **internal logic**, such as a promotion that applies to all variants with the "Summer Sale" facet value, or a shipping calculation
-that applies a surcharge to all products with the "Fragile" facet value. Such facets can be set to be private so that they
-are not exposed to the storefront.
-
-### Collections
-
-[`Collections`](/reference/typescript-api/entities/collection/) are used to categorize and organize your catalog. A collection
-contains multiple product variants, and a product variant can belong to multiple collections. Collections can be nested to
-create a hierarchy of categories, which is typically used to create a menu structure in the storefront.
-
-![Collections](./collections.webp)
-
-The specific product variants that belong to a collection are determined by the collection's [`CollectionFilters`](/reference/typescript-api/configuration/collection-filter/).
-A collection filter is a piece of logic which is used to determine whether a product variant should be included in the collection. By default, Vendure
-includes a number of collection filters:
-
-- **Filter by facet values**: Include all product variants which have a specific set of facet values.
-- **Filter by product variant name**: Include all product variants whose name matches a specific string.
-- **Manually select product variants**: Allows manual selection of individual product variants.
-- **Manually select products**: Allows manual selection of entire products, and then includes all variants of those products.
-
-![Collection filters](./collection-filters.webp)
-
-It is also possible to create your own custom collection filters, which can be used to implement more complex logic. This is
-covered in the [custom collection filters](/TODO) guide.
-
-Collections are not _only_ used as the basis of storefront navigation. They are a general-purpose organization tool which can be used
-for many purposes, such as:
-
-- Creating a collection of "new arrivals" which is used on the homepage.
-- Creating a collection of "best sellers" which is used to display a list of popular products.
-- Creating a collection of "sale items" which is used to apply a discount to all products in the collection, via a promotion.
-
-### Assets
-
-[`Assets`](/reference/typescript-api/entities/asset/) are used to store files such as images, videos, PDFs, etc. Assets can be
-assigned to **products**, **variants** and **collections** by default. By using [custom fields](/guides/concepts/custom-fields/) it is
-possible to assign assets to other entities. For example, for implementing customer profile images.
-
-## Orders
-
-Orders are the central concept of Vendure's checkout process. An order is created when a customer adds a product to their cart, and
-is completed when the customer has paid for the order and the products have been shipped.
-
-:::note
-In Vendure, there is no distinction between a "cart" and an "order". The same entity is used for both. A "cart" is simply an order
-which is still "active" according to its current state.
-:::
-
-An [`Order`](/reference/typescript-api/entities/order/) is composed of one or more [`OrderLines`](/reference/typescript-api/entities/order-line/).
-Each order line represents a single product variant, and contains information such as the quantity, price, tax rate, etc.
-
-In turn, the order is associated with a [`Customer`](/reference/typescript-api/entities/customer/) and contains information such as
-the shipping address, billing address, shipping method, payment method, etc.
-
-![Order](./order.webp)
-
-## Customers
-
-A [`Customer`](/reference/typescript-api/entities/customer/) is a person who can buy from your shop. A customer can have one or more
-[`Addresses`](/reference/typescript-api/entities/address/), which are used for shipping and billing.
-
-If a customer has registered an account, they will have an associated [`User`](/reference/typescript-api/entities/user/). The user
-entity is used for authentication and authorization. **Guest checkouts** are also possible, in which case a customer will not have a user.
-
-![Customer](./customer.webp)
-
-Customers can be organized into [`CustomerGroups`](/reference/typescript-api/entities/customer-group/). These groups can be used in
-logic relating to promotions, shipping rules, payment rules etc. For example, you could create a "VIP" customer group and then create
-a promotion which grants members of this group free shipping. Or a "B2B" group which is used in a custom tax calculator to
-apply a different tax rate to B2B customers.
-
-## Administrators & Roles
-
-An [`Administrator`](/reference/typescript-api/entities/administrator/) is a user who has some degree of access to the
-functions of the Admin API and the Admin UI. Similar to customers, administrators are also associated with a user, which
-is responsible for managing authentication and authorization.
-Administrators are assigned one or more [`Roles`](/reference/typescript-api/entities/role/),
-which define specific [`Permissions`](/reference/typescript-api/common/permission/). Each query or mutation in the Admin API
-declares which permissions are required to execute it. If an administrator does not have the required permissions, the request
-will be rejected.
-
-![Administrators & Roles](./admin-role.webp)
-
-In the example above, the administrator Sam Bailey has two roles assigned: "Order Manager" and "Catalog Manager". An administrator
-can have any number of roles assigned, and the permissions of all roles are combined to determine the permissions of the
-administrator. In this way, you can have fine-grained control over which administrators can perform which actions.
-
-There are 2 special roles which are created by default and cannot be changed:
-
-- **SuperAdmin**: This role has all permissions, and cannot be edited or deleted. It is assigned to the first administrator
-  created when the server is started.
-- **Customer**: This role is assigned to all registered customers.
-
-## Channels
-
-A [`Channel`](/reference/typescript-api/entities/channel/) represents a distinct sales channel, and has several uses in Vendure:
-
-- **Multi-tenancy**: Each channel can be configured with its own set of products, shipping methods, payment methods, etc. This
-  allows you to run multiple shops from a single Vendure server.
-- **Multi-vendor**: Each channel can represent a distinct vendor or seller, which can be used to implement a marketplace.
-- **Region-specific stores**: Each channel can be configured with its own set of languages, currencies, tax rates, etc. This
-  allows you to run multiple stores for different regions from a single Vendure server.
-- **Distinct sales channels**: Each channel can represent a sales channel of a single business, with one channel for the online
-  store, one for selling via Amazon, one for selling via Facebook etc.
-
-:::info
-Channels are covered in much more detail in the dedicated [Channels guide](/guides/core-concepts/channels/).
-:::
-
-There is _always_ the **default channel**, which cannot be deleted. This channel is the parent of all other channels, and also
-contains all entities in the entire application, no matter which channel they are associated with. This means that channel-aware
-entities are always associated with the default channel and _may_ additionally be associated with other channels.
-
-![Channels](./channels.webp)
-

docs/docs/guides/developer-guide/the-api-layer/index.mdx

@@ -363,7 +363,7 @@ export class ProductsController {
 The `@Controller()` decorator takes a path argument which is the base path for all the endpoints defined in the controller.
 In this case, the path is `products`, so the endpoint will be available at `/products`.
 
-The controller can be registered with a plugin:
+The controller can be registered with a [plugin](/guides/developer-guide/plugins/):
 
 ```ts title="src/plugins/rest/products.plugin.ts"
 import { PluginCommonModule, VendurePlugin } from '@vendure/core';

docs/docs/guides/getting-started/first-steps/index.mdx

@@ -0,0 +1,220 @@
+---
+title: "Try The API"
+---
+
+Once you have successfully installed Vendure locally following the [installation guide](/guides/getting-started/installation),
+it's time to try out the API!
+
+:::note
+This guide assumes you chose to populate sample data when installing Vendure.
+:::
+
+## GraphQL Playground
+
+The Vendure server comes with a GraphQL Playground which allows you to explore the API and run queries and mutations. It is
+a great way to explore the API and to get a feel for how it works.
+
+In this guide, we'll be using the GraphQL Playground to run queries and mutations against the Shop and Admin APIs. At each
+step, you paste the query or mutation into the left-hand pane of the Playground, and then click the "Play" button to run it.
+You'll then see the response in the right-hand pane.
+
+![Graphql playground](./playground.webp)
+
+:::note
+Before we start using the GraphQL Playground, we need to alter a setting to make sure it is handling session cookies
+correctly.
+
+In the "settings" panel, we need to change the `request.credentials` setting from `omit` to `include`:
+
+![Graphql playground setup](./playground-setup.webp)
+:::
+
+## Shop API
+
+The Shop API is the public-facing API which is used by the storefront application.
+
+Open the GraphQL Playground at [http://localhost:3000/shop-api](http://localhost:3000/shop-api).
+
+### Fetch a list of products
+
+Let's start with a **query**. Queries are used to fetch data. We will make a query to get a list of products.
+
+```graphql title="Shop API"
+query {
+  products {
+    totalItems
+    items {
+      id
+      name
+    }
+  }
+}
+```
+
+Note that the response only includes the properties we asked for in our query (id and name). This is one of the key benefits
+of GraphQL - the client can specify exactly which data it needs, and the server will only return that data!
+
+Let's add a few more properties to the query:
+
+```graphql title="Shop API"
+query {
+  products {
+    totalItems
+    items {
+      id
+      name
+      // highlight-start
+      slug
+      description
+      featuredAsset {
+        id
+        preview
+      }
+      // highlight-end
+    }
+  }
+}
+```
+
+You should see that the response now includes the `slug`, `description` and `featuredAsset` properties. Note that the
+`featuredAsset` property is itself an object, and we can specify which properties of that object we want to include in the
+response. This is another benefit of GraphQL - you can "drill down" into the data and specify exactly which properties you
+want to include.
+
+Now let's add some arguments to the query. Some queries (and most mutations) can accept argument, which you put in parentheses
+after the query name. For example, let's fetch the first 5 products:
+
+```graphql title="Shop API"
+query {
+  // highlight-next-line
+  products(options: { take: 5 }) {
+    totalItems
+    items {
+      id
+      name
+    }
+  }
+}
+```
+
+On running this query, you should see just the first 5 results being returned.
+
+Let's add a more complex argument: this time we'll filter for only those products which contain the string "shoe" in the
+name:
+
+```graphql title="Shop API"
+query {
+  products(options: {
+    // highlight-next-line
+    filter: { name: { contains: "shoe" } }
+  }) {
+    totalItems
+    items {
+      id
+      name
+    }
+  }
+}
+```
+
+### Add a product to an order
+
+Next, let's look at a **mutation**. Mutations are used to modify data on the server.
+
+Here's a mutation which adds a product to an order:
+
+```graphql title="Shop API"
+mutation {
+  addItemToOrder(productVariantId: 42, quantity: 1) {
+    ...on Order {
+      id
+      code
+      totalQuantity
+      totalWithTax
+      lines {
+        productVariant {
+          name
+        }
+        quantity
+        linePriceWithTax
+      }
+    }
+    ...on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+This mutation adds a product variant with ID `42` to the order. The response will either be an `Order` object, or an `ErrorResult`.
+We use a special syntax called a **fragment** to specify which properties we want to include in the response. In this case,
+we are saying that if the response is an `Order`, we want to include the `id`, `code`, `totalQuantity`, `totalWithTax` etc., and
+if the response is an `ErrorResult`, we want to include the `errorCode` and `message`.
+
+Running this mutation a second time should show that the quantity of the product in the order has increased by 1. If not,
+then the session is not being persisted correctly (see the note earlier in this guide about the `request.credentials` setting).
+
+:::info
+For more information about `ErrorResult` and the handling of errors in Vendure, see the [Error Handling guide](/guides/advanced-topics/error-handling).
+:::
+
+## Admin API
+
+The Admin API exposes all the functionality required to manage the store. It is used by the Admin UI, but can also be used
+by integrations and custom scripts.
+
+Open the GraphQL Playground at [http://localhost:3000/admin-api](http://localhost:3000/admin-api).
+
+### Logging in
+
+Most Admin API operations are restricted to authenticated users. So first of all we'll need to log in.
+
+```graphql title="Admin API"
+mutation {
+  login(username: "superadmin", password: "superadmin") {
+    ...on CurrentUser {
+      id
+      identifier
+    }
+    ...on ErrorResult {
+      errorCode
+      message
+    }
+  }
+}
+```
+
+### Fetch a product
+
+The Admin API exposes a lot more information about products than you can get from the Shop API:
+
+```graphql title="Admin API"
+query {
+  product(id: 42) {
+    enabled
+    name
+    variants {
+      id
+      name
+      enabled
+      prices {
+        currencyCode
+        price
+      }
+      stockLevels {
+        stockLocationId
+        stockOnHand
+        stockAllocated
+      }
+    }
+  }
+}
+```
+
+:::info
+GraphQL is statically typed and uses a **schema** containing information about all the available queries, mutations and types. In the
+GraphQL playground, you can explore the schema by clicking the "docs" tab on the right hand side.
+
+![Graphql playground docs](./playground-docs.webp)
+:::

docs/docs/guides/getting-started/installation.md

@@ -1,81 +0,0 @@
----
-title: "Installation"
-sidebar_position: 1
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-## Requirements
- 
-* [Node.js](https://nodejs.org/en/) **v16** or above, with support for **even-numbered Node.js versions**.
-* The [supported TypeScript version](https://github.com/vendure-ecommerce/vendure/blob/master/packages/create/src/constants.ts#L7) is set upon installation. Upgrading to a newer version of TypeScript might result in compilation errors.
-* If you want to use MySQL, MariaDB, or Postgres as your data store, then you'll need an instance available locally. However, if you are just testing out Vendure, we recommend using SQLite, which has no external requirements.
-
-## Installation with @vendure/create
-
-The recommended way to get started with Vendure is by using the [@vendure/create](https://github.com/vendure-ecommerce/vendure/tree/master/packages/create) tool. This is a command-line tool which will scaffold and configure your new Vendure project and install all dependencies.
-
-
-<Tabs>
-<TabItem value="npx" label="npx" default>
-
-```
-npx @vendure/create my-shop
-```
-
-</TabItem>
-<TabItem value="npm init" label="npm init">
-
-```
-npm init @vendure my-shop
-```
-
-</TabItem>
-<TabItem value="yarn create" label="yarn create">
-
-```
-yarn create @vendure my-shop
-``` 
-
-</TabItem>
-</Tabs>
-
-:::note
-By default, the `@vendure/create` tool will use [Yarn](https://yarnpkg.com/) to manage your dependencies if you have it installed. If you want to force it to use npm, use the `--use-npm` flag.
-:::
-
-*For other installation options see the [@vendure/create documentation](https://github.com/vendure-ecommerce/vendure/blob/master/packages/create/README.md).*
-
-
-"my-shop" in the above command would be replaced by whatever you'd like to name your new project.
-Vendure Create will guide you through the setup. When done, you can run:
-
-```sh
-cd my-shop
-
-yarn dev
-# or
-npm run dev
-```
-
-Assuming the default config settings, you can now access:
-
-* The Vendure Admin GraphQL API: [http://localhost:3000/admin-api](http://localhost:3000/admin-api)
-* The Vendure Shop GraphQL API: [http://localhost:3000/shop-api](http://localhost:3000/shop-api)
-* The Vendure Admin UI: [http://localhost:3000/admin](http://localhost:3000/admin)
-
-:::tip
-Open [http://localhost:3000/admin](http://localhost:3000/admin) in your browser and log in with the superadmin credentials you specified, which default to:
-
-* **username**: superadmin
-* **password**: superadmin
-:::
-
-## Troubleshooting
-
-If you encounter any issues during installation, you can get a more detailed output by setting the log level to `verbose`:
-
-```sh
-npx @vendure/create my-shop --log-level verbose
-```

docs/docs/guides/getting-started/installation/index.md

@@ -0,0 +1,119 @@
+---
+title: "Installation"
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Requirements
+ 
+* [Node.js](https://nodejs.org/en/) **v16** or above, with support for **even-numbered Node.js versions**.
+* The [supported TypeScript version](https://github.com/vendure-ecommerce/vendure/blob/master/packages/create/src/constants.ts#L7) is set upon installation. Upgrading to a newer version of TypeScript might result in compilation errors.
+* If you want to use MySQL, MariaDB, or Postgres as your data store, then you'll need an instance available locally. However, **if you are just testing out Vendure, we recommend using SQLite**, which has no external requirements.
+
+## @vendure/create
+
+The recommended way to get started with Vendure is by using the [@vendure/create](https://github.com/vendure-ecommerce/vendure/tree/master/packages/create) tool. This is a command-line tool which will scaffold and configure your new Vendure project and install all dependencies.
+
+### 1. Run the command
+
+<Tabs>
+<TabItem value="npx" label="npx" default>
+
+```
+npx @vendure/create my-shop
+```
+
+</TabItem>
+<TabItem value="npm init" label="npm init">
+
+```
+npm init @vendure my-shop
+```
+
+</TabItem>
+<TabItem value="yarn create" label="yarn create">
+
+```
+yarn create @vendure my-shop
+``` 
+
+</TabItem>
+</Tabs>
+
+:::note
+By default, the `@vendure/create` tool will use [Yarn](https://yarnpkg.com/) to manage your dependencies if you have it installed. If you want to force it to use npm, use the `--use-npm` flag.
+:::
+
+### 2. Select a database
+
+Vendure supports a number of different databases. The `@vendure/create` tool will prompt you to select one. 
+
+**To quickly test out Vendure, we recommend using SQLite**, which requires no external dependencies. You can always switch to a different database later by changing your configuration file.
+
+
+![Vendure Create step 1](./create-1.webp)
+
+:::tip
+If you select MySQL, MariaDB or Postgres, you need to make sure you:
+
+1. have the database server running and accessible
+2. have created a database for Vendure to use
+3. know the username and password for a user with access to that database
+:::
+
+### 3. Populate with data
+
+The final prompt will ask whether to populate your new Vendure server with some sample product data.
+
+**We recommend you do so**, as it will give you a good starting point for exploring the APIs which we will cover 
+in the [next section](/guides/getting-started/first-steps/).
+
+![Vendure Create step 2](./create-2.webp)
+
+### 4. Complete setup
+
+Next, a project scaffold will be created and dependencies installed. This may take a few minutes.
+
+Once complete, you'll see a message like this:
+
+![Vendure Create step 3](./create-3.webp)
+
+
+### 5. Start the server
+
+Follow the instructions to move into the new directory created for your project, and start the server:
+
+```bash
+cd my-shop
+
+yarn dev
+# or
+npm run dev
+```
+
+You should not be able to access:
+
+* The Vendure Admin GraphQL API: [http://localhost:3000/admin-api](http://localhost:3000/admin-api)
+* The Vendure Shop GraphQL API: [http://localhost:3000/shop-api](http://localhost:3000/shop-api)
+* The Vendure Admin UI: [http://localhost:3000/admin](http://localhost:3000/admin)
+
+Congratulations! 🥳 You now have a fully-functional Vendure server running locally.
+
+Now you can explore Vendure by following our [Try The API guide](/guides/getting-started/first-steps/) to learn how to interact with the server.
+
+:::tip
+Open the Admin UI at [http://localhost:3000/admin](http://localhost:3000/admin) in your browser and log in with the superadmin credentials you specified, which default to:
+
+* **username**: superadmin
+* **password**: superadmin
+:::
+
+## Troubleshooting
+
+If you encounter any issues during installation, you can get a more detailed output by setting the log level to `verbose`:
+
+```sh
+npx @vendure/create my-shop --log-level verbose
+```

docs/docs/reference/typescript-api/core-plugins/asset-server-plugin/index.md

@@ -42,7 +42,7 @@ const config: VendureConfig = {
 };
 ```
 
-The full configuration is documented at [AssetServerOptions]({{< relref "asset-server-options" >}})
+The full configuration is documented at [AssetServerOptions](/reference/typescript-api/core-plugins/asset-server-plugin/asset-server-options)
 
 ## Image transformation
 
@@ -54,7 +54,7 @@ The above URL will return `some-asset.jpg`, resized to fit in the bounds of a 50
 
 ### Preview mode
 
-The `mode` parameter can be either `crop` or `resize`. See the [ImageTransformMode]({{< relref "image-transform-mode" >}}) docs for details.
+The `mode` parameter can be either `crop` or `resize`. See the [ImageTransformMode](/reference/typescript-api/core-plugins/asset-server-plugin/image-transform-mode) docs for details.
 
 ### Focal point
 
@@ -89,7 +89,7 @@ The `format` parameter can also be combined with presets (see below).
 ### Transform presets
 
 Presets can be defined which allow a single preset name to be used instead of specifying the width, height and mode. Presets are
-configured via the AssetServerOptions [presets property]({{< relref "asset-server-options" >}}#presets).
+configured via the AssetServerOptions [presets property](/reference/typescript-api/core-plugins/asset-server-plugin/asset-server-options/#presets).
 
 For example, defining the following preset:
 

docs/docs/reference/typescript-api/core-plugins/asset-server-plugin/s3asset-storage-strategy.md

@@ -152,13 +152,13 @@ Using type `any` in order to avoid the need to include `aws-sdk` dependency in g
 
 <GenerationInfo sourceFile="packages/asset-server-plugin/src/s3-asset-storage-strategy.ts" sourceLine="119" packageName="@vendure/asset-server-plugin" />
 
-Returns a configured instance of the <a href='/reference/typescript-api/core-plugins/asset-server-plugin/s3asset-storage-strategy#s3assetstoragestrategy'>S3AssetStorageStrategy</a> which can then be passed to the <a href='/reference/typescript-api/core-plugins/asset-server-plugin/asset-server-options#assetserveroptions'>AssetServerOptions</a>
-`storageStrategyFactory` property.
+Returns a configured instance of the <a href='/reference/typescript-api/core-plugins/asset-server-plugin/s3asset-storage-strategy#s3assetstoragestrategy'>S3AssetStorageStrategy</a> which can then be passed to the <a href='/reference/typescript-api/core-plugins/asset-server-plugin/asset-server-options#assetserveroptions'>AssetServerOptions</a>`storageStrategyFactory` property.
 
 Before using this strategy, make sure you have the `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` package installed:
 
 ```sh
-npm install
+npm install @aws-sdk/client-s3 @aws-sdk/lib-storage
+```
 
 *Example*
 

docs/docs/reference/typescript-api/orders/order-item-price-calculation-strategy.md

@@ -59,7 +59,7 @@ A custom OrderItemPriceCalculationStrategy can be used to implement things like:
 * A gift-wrapping service, where a boolean custom field is defined on the OrderLine. If `true`,
   a gift-wrapping surcharge would be added to the price.
 * A product-configurator where e.g. various finishes, colors, and materials can be selected and stored
-  as OrderLine custom fields (see [the Custom Fields guide](/guides/concepts/custom-fields/).
+  as OrderLine custom fields (see [the Custom Fields guide](/guides/developer-guide/custom-fields/).
 * Price lists or bulk pricing, where different price bands are stored e.g. in a customField on the ProductVariant, and this
   is used to calculate the price based on the current quantity.
 

docs/sidebars.js

@@ -16,9 +16,9 @@ const sidebars = {
     // By default, Docusaurus generates a sidebar from the docs folder structure
     learnSidebar: [
         {
-            type: 'doc',
-            label: 'Installation',
-            id: 'guides/getting-started/installation',
+            type: 'category',
+            label: 'Getting Started',
+            items: ['guides/getting-started/installation/index', 'guides/getting-started/first-steps/index'],
         },
         {
             type: 'category',
@@ -26,7 +26,6 @@ const sidebars = {
             items: [
                 'guides/developer-guide/overview/index',
                 'guides/developer-guide/configuration/index',
-                'guides/developer-guide/data-model/index',
                 'guides/developer-guide/the-api-layer/index',
                 'guides/developer-guide/the-service-layer/index',
                 'guides/developer-guide/strategies-configurable-operations/index',

packages/asset-server-plugin/src/plugin.ts

@@ -52,7 +52,7 @@ import { AssetServerOptions, ImageTransformPreset } from './types';
  * };
  * ```
  *
- * The full configuration is documented at [AssetServerOptions]({{< relref "asset-server-options" >}})
+ * The full configuration is documented at [AssetServerOptions](/reference/typescript-api/core-plugins/asset-server-plugin/asset-server-options)
  *
  * ## Image transformation
  *
@@ -64,7 +64,7 @@ import { AssetServerOptions, ImageTransformPreset } from './types';
  *
  * ### Preview mode
  *
- * The `mode` parameter can be either `crop` or `resize`. See the [ImageTransformMode]({{< relref "image-transform-mode" >}}) docs for details.
+ * The `mode` parameter can be either `crop` or `resize`. See the [ImageTransformMode](/reference/typescript-api/core-plugins/asset-server-plugin/image-transform-mode) docs for details.
  *
  * ### Focal point
  *
@@ -99,7 +99,7 @@ import { AssetServerOptions, ImageTransformPreset } from './types';
  * ### Transform presets
  *
  * Presets can be defined which allow a single preset name to be used instead of specifying the width, height and mode. Presets are
- * configured via the AssetServerOptions [presets property]({{< relref "asset-server-options" >}}#presets).
+ * configured via the AssetServerOptions [presets property](/reference/typescript-api/core-plugins/asset-server-plugin/asset-server-options/#presets).
  *
  * For example, defining the following preset:
  *

packages/asset-server-plugin/src/s3-asset-storage-strategy.ts

@@ -54,7 +54,7 @@ export interface S3Config {
  * Before using this strategy, make sure you have the `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` package installed:
  *
  * ```sh
- * npm install @aws-sdk/client-s3 @aws-sdk/lib-storage
+ * npm install \@aws-sdk/client-s3 \@aws-sdk/lib-storage
  * ```
  *
  * @example