How It Works

This page explains how GraphQL Fusion composition works in Suite Framework, from backend services exposing their schemas to the generation of a composed BFF gateway.

Architecture

In Suite, GraphQL federation is structured around two service kinds:

• Backend services — own a bounded context and expose a GraphQL subgraph schema.
• BFFs (Backend for Frontend) — composed gateways that aggregate multiple subgraph schemas into a single GraphQL endpoint for client applications.

Each backend service declares which BFFs it publishes to via its application.yaml.

spec:
  build:
    dotnet:
      graphql:
        publish:
          - gateway: admin-center-bff
            extensions:
              - admin-center.fusion.extensions.graphql

A backend can publish to multiple BFFs, and each BFF aggregates all the subgraphs that declare it as their target gateway.

Composition Flow

The full composition process is driven by a single command:

suite graphql compose [application/s]

Internally, compose runs three sequential steps:

Step 1 — Config

For each backend subgraph being processed, the CLI configures its Fusion metadata:

• Sets the subgraph name (matching the application name).
• Sets the HTTP endpoint the gateway will use to reach this service at runtime (derived from the service's Kubernetes service name).

This step can also be run independently via suite graphql config. See CLI Usage.

Step 2 — Schema & Packaging

Each backend service is started in design time mode (IsRunningInDesignTime=true) and its GraphQL schema is exported. The schema is then packaged into a .fsp (Fusion Subgraph Package) for each BFF it publishes to, incorporating any gateway-specific extensions declared in application.yaml.

This step can also be run independently via suite graphql schema. See CLI Usage.

Step 3 — Compose

For each BFF, the CLI composes all its subgraph .fsp packages into a single gateway package, then exports the final composed schema. The gateway package is self-contained — at runtime, the BFF uses it to resolve queries without needing to contact downstream services for schema information.

This step can also be run independently via suite graphql compose. See CLI Usage.

Composition Lifecycle

The full Fusion workflow follows a simple lifecycle from backend services to a composed gateway that serves client applications.

graph LR

Client[Client Application]

Service1[Backend Service<br>Addresses]
Service2[Backend Service<br>Contacts]
Service3[Backend Service<br>Content]

Schema1[Exported GraphQL Schema]
Schema2[Exported GraphQL Schema]
Schema3[Exported GraphQL Schema]

FSP1[Fusion Subgraph Package .fsp]
FSP2[Fusion Subgraph Package .fsp]
FSP3[Fusion Subgraph Package .fsp]

Gateway[Composed BFF Gateway]

Service1 --> Schema1 --> FSP1 --> Gateway
Service2 --> Schema2 --> FSP2 --> Gateway
Service3 --> Schema3 --> FSP3 --> Gateway

Gateway --> Client

Target Resolution

The compose command behaves differently depending on what application/s are passed:

Input	Behavior
BFF	Regenerates schemas for all subgraphs publishing to that BFF, then composes the gateway.
Backend service	Regenerates the schema for that service only, then composes all BFFs it publishes to.

This means running suite graphql compose addresses will only regenerate the addresses schema but will fully recompose every BFF that addresses publishes to, ensuring all gateways stay consistent.

For the full CLI reference including available flags, see CLI Usage.
For configuring a backend service to publish to a BFF, see Configuration.