docs: Add GraphQL API guide

Relates to #214.

docs/content/docs/developer-guide/graphql-api-guide/_index.md

@@ -0,0 +1,45 @@
+---
+title: "GraphQL API Guide"
+weight: 0
+showtoc: true
+---
+
+# GraphQL API Guide
+
+This is an overview of the GraphQL Shop API, which is used when implementing a storefront application with Vendure. 
+
+{{% alert "warning" %}}
+This guide only lists some of the more common operations you'll need for your storefront. Please consult [the Shop API reference]({{< relref "/docs/graphql-api/shop" >}}) for a complete guide.
+{{% /alert %}}
+
+## Browsing the catalogue
+
+* {{< shop-api-operation operation="collections" type="query" >}}: List available Collections. Useful for creating navigation menus.
+* {{< shop-api-operation operation="search" type="query" >}}: Useful both for keyword searching, and for listing product results by collectionId and/or facetValueId. In practice this query can power all kinds of storefront product lists as it is backed by a search index optimized for performance.
+* {{< shop-api-operation operation="product" type="query" >}}: Use this for the Product detail view.
+
+## Order flow
+
+*See the [Order Workflow guide]({{< relref "/docs/developer-guide/order-workflow" >}}) for a detailed explanation of how Orders are handled in Vendure.*
+
+* {{< shop-api-operation operation="activeOrder" type="query" >}} returns the currently-active Order for the session.
+* {{< shop-api-operation operation="addItemToOrder" type="mutation" >}} adds an item to the order. The first time it is called will also create a new Order for the session.
+* {{< shop-api-operation operation="adjustOrderLine" type="mutation" >}} is used to adjust the quantity of an OrderLine.
+* {{< shop-api-operation operation="removeOrderLine" type="mutation" >}} removes an OrderLine from the Order.
+* {{< shop-api-operation operation="setCustomerForOrder" type="mutation" >}} specifies the Customer details (required if the customer is not logged in as an authenticated user).
+* {{< shop-api-operation operation="setOrderShippingAddress" type="mutation" >}} sets the shipping address for the Order.
+* {{< shop-api-operation operation="eligibleShippingMethods" type="mutation" >}} returns all available shipping methods based on the customer's shipping address and the contents of the Order.
+* {{< shop-api-operation operation="setOrderShippingMethod" type="mutation" >}} sets the shipping method to use.
+* {{< shop-api-operation operation="addPaymentToOrder" type="mutation" >}} adds a payment to the Order. If the payment amount equals the order total, then the Order will be transitioned to either the `PaymentAuthorized` or `PaymentSettled` state (depending on how the payment provider is configured) and the order process is complete from the customer's side.
+* {{< shop-api-operation operation="orderByCode" type="query" >}} allows even guest Customers to fetch the order they just placed for up to 2 hours after placing it. This is intended to be used to display an order confirmation page immediately after the order is completed.
+
+
+## Customer account management
+
+* {{< shop-api-operation operation="registerCustomerAccount" type="mutation" >}}: Creates a new Customer account.
+* {{< shop-api-operation operation="login" type="mutation" >}}: Log in with registered Customer credentials.
+* {{< shop-api-operation operation="logout" type="mutation" >}}: Log out from Customer account.
+* {{< shop-api-operation operation="activeCustomer" type="query" >}}: Returns the current logged-in Customer, or `null` if not logged in. This is useful for displaying the logged-in status in the storefront. The returned [`Customer`]({{< relref "/docs/graphql-api/shop/object-types" >}}#customer) type can also be used to query the Customer's Order history, list of Addresses and other personal details.
+* {{< shop-api-operation operation="requestPasswordReset" type="mutation" >}}: Use this to implement a "forgotten password" flow. This will trigger a password reset email to be sent.
+* {{< shop-api-operation operation="resetPassword" type="mutation" >}}: Use the token provided in the password reset email to set a new password.
+

docs/content/docs/developer-guide/order-workflow/_index.md

@@ -25,14 +25,5 @@ So if the customer adds 2 *Widgets* to the Order, there will be **one OrderLine*
 
 ## Shop client order workflow
 
-The following is a description of the flow and related GraphQL operations which are used when dealing with Orders in a customer-facing client application (i.e. a storefront).
-
-1. [`activeOrder` query]({{< relref "/docs/graphql-api/shop/queries#activeorder" >}}) returns the currently-active Order for the session.
-* [`addItemToOrder` mutation]({{< relref "/docs/graphql-api/shop/mutations#additemtoorder" >}}) adds an item to the order. The first time it is called will also create a new Order for the session.
-* [`adjustOrderLine` mutation]({{< relref "/docs/graphql-api/shop/mutations#adjustorderline" >}}) is used to adjust the quantity of an OrderLine.
-* [`removeOrderLine` mutation]({{< relref "/docs/graphql-api/shop/mutations#removeorderline" >}}) removes an OrderLine from the Order.
-* [`setCustomerForOrder` mutation]({{< relref "/docs/graphql-api/shop/mutations#setcustomerfororder" >}}) specifies the Customer details (required if the customer is not logged in as an authenticated user).
-* [`setOrderShippingAddress` mutation]({{< relref "/docs/graphql-api/shop/mutations#setordershippingaddress" >}}) sets the shipping address for the Order.
-* [`eligibleShippingMethods` query]({{< relref "/docs/graphql-api/shop/queries#eligibleshippingmethods" >}}) returns all available shipping methods based on the customer's shipping address and the contents of the Order.
-* [`setOrderShippingMethod` mutation]({{< relref "/docs/graphql-api/shop/mutations#setordershippingmethod" >}}) sets the shipping method to use.
-* [`addPaymentToOrder` mutation]({{< relref "/docs/graphql-api/shop/mutations#addpaymenttoorder" >}}) adds a payment to the Order. If the payment amount equals the order total, then the Order will be transitioned to either the `PaymentAuthorized` or `PaymentSettled` state (depending on how the payment provider is configured) and the order process is complete from the customer's side.
+The [GraphQL API Guide]({{< relref "/docs/developer-guide/graphql-api-guide" >}}#order-flow) lists the GraphQL operations you will need to implement this workflow in your storefront client application.
+

docs/content/docs/developer-guide/overview/_index.md

@@ -26,6 +26,10 @@ There are 2 separate GraphQL APIs: shop and admin.
 
     [Admin API Documentation]({{< relref "/docs/graphql-api/admin" >}}).
 
+## ServiceModule
+
+This is an internal module which contains the bulk of the Vendure business logic for managing products, customers, orders, collections etc.
+
 ## Database
 
 Vendure supports multiple databases. Currently it is tested with MySQL/MariaDB, PostgreSQL, SQLite and SQL.js. Since Vendure uses [TypeORM](https://typeorm.io/#/) to manage data access, it can theoretically also work with CockroachDB, Microsoft SQL Server and MongoDB, though these are as yet untested.

docs/content/docs/getting-started.md

@@ -69,3 +69,8 @@ Log in with the superadmin credentials:
 * **username**: superadmin
 * **password**: superadmin
 {{% /alert %}}
+
+## Next Steps
+
+* Get a better understanding of how Vendure works by reading the [Architecture Overview]({{< relref "/docs/developer-guide/overview" >}})
+* Learn how to implement a storefront with the [GraphQL API Guide]({{< relref "/docs/developer-guide/graphql-api-guide" >}})

docs/layouts/shortcodes/shop-api-operation.html

@@ -0,0 +1,4 @@
+{{- $operationName := .Get "operation" -}}
+{{- $operationSegment := cond (eq (.Get "type") "query") "queries" "mutations" -}}
+{{- $link := (print "/docs/graphql-api/shop/" $operationSegment  "#" (lower $operationName) ) -}}
+<em>{{ .Get "type" }}</em> <a href="{{ $link }}"><code>{{ $operationName }}</code></a>