Federation explanation docs

docs/explanations/federation.md

@@ -0,0 +1,42 @@
+# Federation
+
+## Preface
+
+API federation facilitates providing access to data from numerous underlying services via a single endpoint. This hides the complexity of the underlying implementation from clients.
+
+There are numerous methodologies for federating between GraphQL services. The Graph utilizes [Apollo Federation v2](https://www.apollographql.com/docs/federation/subgraph-spec/) which is the most widely adopted, supported, and featureful of the methods.
+
+## Schema Composition
+
+In order to compose the federated API each of the comprising services must supply a [Subgraph Schema](../references/terminology.md#subgraph-schema), which are then stitched together in order to form the [Supergraph Schema](../references/terminology.md#supergraph-schema). The Subgraph Schemas act as the source of truth for the API, whilst the composed Supergraph Schema is used by the Router to perform query planning, and by clients who are making requests against the federated API.
+
+Subgraph Schema registration for the Graph is performed by adding a schema file to the [schema directory of the graph-federation GitHub repo](https://github.com/DiamondLightSource/graph-federation/tree/main/schema). A continuous integration job will then build the Supergraph schema.
+
+## Request Routing
+
+At run time a proxy service known as the Router receives API requests, plans queries according to the [Supergraph](../references/terminology.md#supergraph) schema, queries the appropriate services, and constructs the response. The query planning stage allows the Router to optimally query the underlying service, taking into account any dependencies which may exist between services.
+
+An exemplary query sequence diagram is shown below, in which the queries to services B and C are dependent on the result of the query to service A.
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant R as Router
+  participant A as Service A
+  participant B as Service B
+  participant C as Service C
+  Client->>R: Request
+  activate R
+  R-->>R: Query Planning
+  deactivate R
+  R->>A: Request
+  A->>R: Response
+  par
+    R->>B: Request
+    B->>R: Response
+  and
+    R->>C: Request
+    C->>R: Response
+  end
+  R->>Client: Response
+```

docs/references/terminology.md

@@ -0,0 +1,15 @@
+# Terminology
+
+### Schema
+
+A GraphQL schema is an artifact describing the API provided by a given GraphQL endpoint.
+This is likely to contain a set of [Queries](https://spec.graphql.org/October2021/#sec-Query), [Mutations](https://spec.graphql.org/October2021/#sec-Mutation) and [Subscriptions](https://spec.graphql.org/October2021/#sec-Subscription), and a description of the [Objects](https://spec.graphql.org/October2021/#sec-Objects) which they return.
+
+
+### Subgraph Schema
+A Subgraph is the [Schema](#schema) of an individual service. These may be stitched together to form a [Supergraph](#supergraph).
+
+### Supergraph Schema
+
+A Supergraph is simply a GraphQL [Schema](#schema) which has been stitched together from various [Subgraphs](#subgraph).
+

mkdocs.yaml

@@ -9,3 +9,7 @@ nav:
   - Home: index
   - How-To Guides:
       - ... | flat | how-tos/*.md
+  - Explanations:
+      - ... | flat | explanations/*.md
+  - References:
+      - ... | flat | references/*.md