New Top Level Federation Section (#619)

Co-authored-by: hasura-bot <[email protected]>

docs/federation/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Federation",
+  "position": 11,
+  "className": "federation-icon",
+  "customProps": {
+    "sidebar_pathname": "federation"
+  }
+}

docs/federation/architecture.mdx

@@ -0,0 +1,149 @@
+---
+sidebar_position: 2
+description: "Understand the architecture of subgraph federation in Hasura DDN and how it enables efficient data
+management across multiple subgraphs, promoting a collaborative development environment."
+keywords:
+  - subgraph federation
+  - supergraph architecture
+  - data management
+  - collaborative development
+  - hasura ddn
+  - graphql api
+  - data connectors
+  - subgraph composition
+  - schema stitching
+  - modular development
+seoFrontMatterUpdated: true
+---
+
+# Federation Architecture
+
+import Thumbnail from "@site/src/components/Thumbnail";
+
+## Introduction
+
+Federation in Hasura DDN upgrades how you build and manage your API.
+
+It is the process of combining multiple subgraphs with multiple data sources into a single supergraph to create a
+unified GraphQL API that provides access to all your data domains through a single endpoint.
+
+This architecture enables more collaborative workflows and allows teams to independently develop and deploy subgraphs
+while maintaining strong governance over the development process.
+
+:::warning DDN Advanced plan required
+
+Independent subgraph development is only available on the [DDN Advanced plan](https://hasura.io/pricing/).
+
+:::
+
+<Thumbnail src="/img/federation/whole-supergraph-erd.png" alt="Create a DDN project" width="1000px" />
+
+## Benefits
+
+- **Modular Development:** Subgraphs promote modular development by allowing teams to independently develop, test, and
+  deploy their code without impacting the functionality of other subgraphs. This can also be done in independent
+  repositories for each subgraph, in a "multi-repo" setup. This modular approach simplifies code management and reduces
+  the risk of breaking changes. Subgraphs can be tested in context of the full supergraph to ensure that they work as
+  expected when combined.
+- **Independent Deployment:** Subgraphs can also be deployed individually, ensuring that updates to one subgraph do not
+  require downtime for the entire supergraph. This flexibility allows for continuous integration and delivery (CI/CD)
+  practices that accelerate feature releases.
+- **Improved Collaboration:** Subgraphs allow different teams to focus on their specialized data domains, fostering
+  collaboration by enabling them to share their APIs and data through a unified interface. This collaborative but
+  isolated workflow environment accelerates development times and reduces friction between teams.
+- **Strong Governance:** Hasura DDN provides robust governance features, such as project collaboration roles and
+  permissions that ensure data integrity and security across subgraphs. These features enable teams to enforce data
+  policies and restrictions, protecting sensitive information and maintaining compliance with regulatory requirements.
+- **Efficient Data Management:** Federation simplifies data management by enabling teams to work with smaller, more
+  manageable data domains. Teams can focus on their specific data requirements without being overwhelmed by the entire
+  data schema.
+
+## Subgraphs
+
+In Hasura DDN, a subgraph represents a self-contained module of metadata and its accompanying data connector(s) which
+encapsulates a specific data domain. Subgraphs can be built completely independently of each other and also managed in
+their own isolated repositories.
+
+Subgraph fields which are exposed to the full supergraph [can be prefixed](/federation/subgraph-prefixing.mdx) to
+prevent conflicts in the schema.
+
+Data can be interlinked between subgraphs using [relationships](/supergraph-modeling/relationships.mdx) and even between
+[subgraphs in separate repositories](/federation/cross-repo-relationships.mdx).
+
+## Globals subgraph
+
+When running the `ddn supergraph init` command, a `globals` subgraph is created by default for your convenience. This
+subgraph is intended to hold global configuration objects for the supergraph, such as API configuration and auth
+settings.
+
+These configuration objects are `AuthConfig`, `CompatibilityConfig` and `GraphqlConfig` as well as the `subgraph.yaml`
+configuration file which defines the globals subgraph itself.
+
+These objects are located by default in the `globals` subgraph, but can be moved to any other subgraph if needed.
+
+## Subgraph-level authorization
+
+Authentication is managed at the supergraph level in Hasura DDN as defined by the `AuthConfig` object and cannot be
+customized at the subgraph level.
+
+Authorization however, is managed at the subgraph level in Hasura DDN. This means that the permissions for models and
+commands are defined within the context of those objects in their respective subgraphs, and do not affect other
+subgraphs.
+
+Authorization rules in one subgraph can also be defined to reference data in a foreign subgraph even if that subgraph is
+in another repository.
+
+## Data connectors
+
+[Data Connectors](/connectors/overview.mdx) connect subgraphs to data sources. They can communicate to data sources in
+their native language, and are data source specific so we can leverage all the data source specific functionality.
+
+Each independent subgraph can have one or more data connectors.
+
+Data connectors are [available for a variety of data sources](https://hasura.io/connectors), including databases,
+business logic functions, REST APIs, and GraphQL APIs. You can also create custom data connectors to integrate with
+other data sources.
+
+The same underlying data source can be connected to multiple subgraphs via data connector instances in each. This allows
+different teams to work with the same source from the perspective of different data domains.
+
+:::tip Read more about data connectors
+
+For a detailed overview of data connectors, check out our [Data Connectors Overview page](/connectors/overview.mdx) 📚
+
+:::
+
+## Relationships
+
+Defining a [relationship](/supergraph-modeling/relationships.mdx) allows you to make queries across linked information
+within and between subgraphs.
+
+As always when authoring metadata, the 
+[Hasura VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) can assist with 
+auto-complete and validation. When working with relationships across subgraphs in other repositories, there are some 
+differences to be aware of. Find out more about cross-repo relationships [here](/federation/cross-repo-relationships.mdx).
+
+## Example
+
+Imagine an e-commerce application with separate subgraphs for product catalog management, user profile information, and
+order processing.
+
+1. **Product Catalog Subgraph:** A team dedicated to managing product information owns and maintains this subgraph. They
+   use a dedicated PostgreSQL data connector to connect to a relational database containing product details, images, and
+   inventory data.
+2. **User Profile Subgraph:** The User Data team owns this subgraph, using a MongoDB data connector to interact with a
+   document database containing user profiles, preferences, and order history.
+3. **Order Processing Subgraph:** Managed by the fulfillment team, this subgraph utilizes a custom TypeScript connector
+   to handle business logic related to order creation, payment processing, and shipment tracking, integrating with
+   external APIs and services.
+
+Each subgraph is developed, tested, and deployed independently, allowing teams to focus on their specific data domains
+without interfering with other teams' work. The supergraph combines these subgraphs into a unified API that provides
+access to all data domains through a single GraphQL endpoint.
+
+## Next steps
+
+- Learn more about git workflows when building supergraphs in [single-repo or multi-repo](/federation/independent-subgraph-development.mdx)
+  setups.
+- Learn more about [subgraph prefixing](/federation/subgraph-prefixing.mdx) to avoid naming collisions in the schema.
+- Learn more about [cross-repo relationships](/federation/cross-repo-relationships.mdx) to link data in subgraphs across

docs/federation/build-commands.mdx

@@ -0,0 +1,74 @@
+---
+sidebar_position: 6
+sidebar_label: Build Commands
+description:
+  "Commands for building supergraphs and subgraphs on Hasura DDN"
+keywords:
+  - ddn
+  - build
+  - commands
+  - supergraph
+  - subgraph
+  - federation
+seoFrontMatterUpdated: true
+---
+
+# Federation Build Command Examples
+
+A supergraph build is a combination of subgraph builds. 
+
+This guide provides a overview of the commands available for building supergraphs and subgraphs on Hasura DDN.
+
+:::info Flags vs Context
+
+We are explicity using flags here to show what arguments are set, some of these can be set as 
+[context](/project-configuration/contexts.mdx). 
+
+:::
+
+## Supergraph Builds
+
+#### Build the supergraph, all subgraphs and all connectors from the same single-repo project
+```bash
+ddn supergraph build create --supergraph supergraph.yaml
+```
+
+#### Build a Supergraph using explicitly specified subgraph builds (DDN Advanced only)
+```bash
+ddn supergraph build create --subgraph-version subA:4235698557 --subgraph-version subB:46241f2bd9 --subgraph-version subC:1ef62e5024
+```
+
+#### Build a Supergraph using explicitly specified subgraph builds with an explicitly specified base supergraph version (DDN Advanced only)
+```bash
+ddn supergraph build create --subgraph-version globals:fc3ce56a69 --subgraph-version my_subgraph:ee738baa8f --base-supergraph-version 155e3569c4
+```
+
+## Subgraph Builds
+
+#### Build a subgraph and all connectors in that subgraph on DDN
+```bash
+ddn subgraph build create --subgraph ./subgraph.yaml
+```
+
+#### Build a subgraph but skip rebuilding connectors in that subgraph
+```bash
+ddn subgraph build create --subgraph ./subgraph.yaml --no-build-connectors
+```
+
+#### Apply a subgraph build to a supergraph (Make it available for queries)
+```bash
+ddn subgraph build apply a1620044d7
+```
+
+## Connector Builds
+
+#### Build a connector on DDN
+```bash
+ddn connector build create --connector ./connector.yaml
+```
+
+## Learn more
+
+- [Learn more about federation architecture](/federation/architecture.mdx)
+- [Learn more about independent subgraph development](/federation/independent-subgraph-development.mdx)
+- [Learn more about contexts](/project-configuration/contexts.mdx)

docs/federation/cross-repo-relationships.mdx

@@ -0,0 +1,120 @@
+---
+sidebar_label: Cross-repo Relationships
+sidebar_position: 4
+description: "Learn how to create relationships across subgraphs in different repositories in Hasura DDN."
+keywords:
+  - relationships
+  - cross-repo relationships
+  - subgraphs
+  - supergraph
+  - hasura ddn
+  - graphql api
+  - data connectors
+  - permissions
+  - federation
+  - multi-repo federation
+  - single-repo federation
+  - schema stitching
+  - modular development
+  - git workflows
+seoFrontMatterUpdated: true
+---
+
+# Cross-repo Relationships
+
+## Connecting across subgraphs with relationships
+
+When you have multiple subgraphs, either in a single-repo or multi-repo setup, you can query across linked information.
+This is done by creating a [`Relationship`](/supergraph-modeling/relationships.mdx) object in metadata which defines how
+fields from one type map to a `model` or `command`.
+
+### Single-repo relationships
+
+In a single-repo setup, relationships are straightforward to manage. All subgraphs are in the same repository and the
+[Hasura VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) can be used to assist
+with authoring relationships, providing auto-complete and validation.
+
+### Cross-repo relationships
+
+:::info Advanced plan
+
+You will need a project on the [DDN Advanced plan](https://hasura.io/pricing) to use multi-repo federation and
+cross-repo relationships.
+
+:::
+
+In a multi-repo setup, subgraphs that contain objects you want to relate can reside in different repositories, some of
+which you may not have access to. In these cases the Hasura VS Code extension cannot validate the entirety of the
+`Relationship` object and you will manually author cross-repo relationships and ensure that the field mappings are
+correct. However, upon creating a supergraph build, all cross-subgraph metadata is validated to prevent mistakes from
+being deployed to the final API.
+
+You can still easily use the Hasura DDN console to explore the supergraph and test relationships across subgraphs once
+you have created a build.
+
+### Example
+
+Let's say you have a supergraph with two subgraphs, each managed in different repositories: `users` and `products`.
+
+The `users` subgraph in repo 'A' has a `User` type with a field called `user_favorite_product_id`.
+
+The `products` subgraph in repo 'B' has a `Product` type with a field called `id`.
+
+To create a relationship between these two types in different repositories, you would create a `Relationship` object in
+the `users` subgraph metadata as normal.
+
+The LSP is able to understand that the `Product` type is in a different subgraph to which it does not have access and
+will not give a warning on the foreign type.
+
+```yaml
+kind: Relationship
+version: v1
+definition:
+  name: favorite_product
+  sourceType: User
+  target:
+    model:
+      name: Product
+      subgraph: products
+      relationshipType: Object
+  mapping:
+    - source:
+        fieldPath:
+          - fieldName: user_favorite_product_id
+      target:
+        modelField:
+          - fieldName: id
+```
+
+This `Relationship` object defines a relationship called `favorite_product` from the `User` type to the `Product` type.
+The `mapping` field specifies how the `user_favorite_product_id` field in the `User` type maps to the `id` field in the
+`Product` type.
+
+After defining the cross-repo relationship, it's important to note that you won't be able to test this locally. To see
+the relationship in action, you'll need to follow these steps:
+
+1. Create a new supergraph build on DDN using the `ddn supergraph build create` command. (Subgraph builds do not get an
+   API, so supergraph builds are required to test.)
+2. You can then use the Hasura DDN console to explore and test the relationship across subgraphs.
+3. If you have admin permissions, you can apply the subgraph to the supergraph with the `ddn subgraph apply` command.
+
+Remember, cross-repo relationships only come into effect when the subgraphs are combined in the DDN environment. Local
+development and testing are limited to the scope of your current repository.
+
+With this relationship defined, you can now query the `favorite_product` field on the `User` type to retrieve the
+related `Product`.
+
+```graphql
+query {
+  users {
+    id
+    name
+    favorite_product {
+      id
+      name
+    }
+  }
+}
+```
+
+For more information on how to create `Relationships` check out [this page](/supergraph-modeling/relationships.mdx).