Gateway — Subgraph Reference

Overview

The ngwenya-gateway is the single entry point for all client traffic. It composes 17 federated subgraphs into a unified supergraph and exposes it on port 30000. Since April 2026, the gateway runs on Hive Gateway (@graphql-hive/gateway, MIT license), replacing the previous Apollo Gateway (ELv2).

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ngwenya-gateway :30000                     │
│                    (Hive Gateway + Yoga)                      │
├────────┬────────┬────────┬────────┬────────┬────────────────┤
│ malets │products│services│ ucart  │ alerts │  + 9 NestJS    │
│ :3001  │ :3004  │ :3003  │ :3005  │ :3025  │  subgraphs     │
├────────┴────────┼────────┴────────┼────────┴────────────────┤
│      auth       │      uchat      │     scim / intelligence │
│     :3008       │   :3017/:3018   │     :3019 / :3026       │
├─────────────────┴─────────────────┴─────────────────────────┤
│  postgres  │  redis  │  mongo  │  meilisearch  │  conduit   │
│   :5432    │  :6379  │ :27017  │    :7700       │   :8448    │
└─────────────────────────────────────────────────────────────┘

Subgraph Registry

All 17 subgraphs are registered via a config-driven ServiceRegistry:

Migration from Apollo Gateway

The gateway was migrated from @apollo/gateway (ELv2) to @graphql-hive/gateway (MIT) in the upgrade/nestjs-11 branch for three reasons:

1. Licensing — Apollo Gateway uses ELv2 (not OSI-approved). Hive Gateway is MIT.
2. Performance — Hive Gateway is ~50% faster at p50 and delivers ~2× throughput under concurrent load.
3. NestJS 11 Compatibility — Hive Gateway natively supports GraphQL Yoga, which is the recommended driver for @nestjs/graphql v13.

Key Driver Changes

Federation v2.9 Compatibility

The composition library (@theguild/federation-composition@0.22.2) supports Federation spec up to v2.9. However, @apollo/subgraph@2.13.3 (used by NestJS subgraphs prior to Yoga migration) auto-injects v2.10+ directive definitions.

The Problem

[ERROR] Cannot import unknown element "@listSize"
[ERROR] duplicate directive "@federation__context"

The Solution — Two-Layer Fix

Layer 1: pnpm patch on @nestjs/graphql@13.3.0

The patch downgrades the default federation importUrl from v2.12 to v2.9 and trims the directive list to v2.9-compatible directives only:

- https://specs.apollo.dev/federation/v2.12
+ https://specs.apollo.dev/federation/v2.9

Layer 2: SDL Sanitization at Gateway

The gateway's fetchSubgraphSdl function strips v2.10+ directive definitions before composition:

// Strip v2.10+ directive definitions that @apollo/subgraph injects
const sanitized = sdl.replace(
  /^directive @federation__(context|fromContext|cost|listSize)\b[^}]*$/gm,
  ''
);

This ensures that even if a subgraph emits v2.10+ directives, they are stripped before reaching the composition engine.

Response Caching & APQ

Response caching and Automatic Persisted Queries are implemented as native Yoga plugins with Redis-backed stores:

plugins: [
  useResponseCache({
    session: (req) => req.headers.get('x-user-id') ?? null,
    cache: createRedisCache({ redis }),
  }),
  useAPQ({ store: createRedisAPQStore({ redis }) }),
]

See Gateway Tracing & Observability for the full caching architecture, metrics export, and Prometheus integration.

Header Propagation

The gateway forwards authentication and context headers to all subgraphs:

propagateHeaders: {
  fromClientToSubgraphs({ request, subgraphRequest }) {
    const headers = ['x-user-id', 'x-org-id', 'x-guest-id', 'x-email', 'authorization'];
    for (const h of headers) {
      const val = request.headers.get(h);
      if (val) subgraphRequest.headers.set(h, val);
    }
  },
}

WebSocket Subscriptions

With Hive Gateway's Yoga driver, GraphQL subscriptions are natively supported through the federated subgraph. The previous architecture required a separate non-federated WS server (port 3027) because Apollo Federation Driver did not support subscriptions.

The frontend connects subscriptions through the same /graphql endpoint using the ws: protocol upgrade.

WebSocket Authentication

The gateway's graphql-ws server uses an onConnect hook to validate session cookies during the WebSocket handshake:

1. Browser sends session cookie automatically on WS upgrade (same-origin)
2. ws-auth.ts extracts the cookie header from the HTTP upgrade request
3. Cookie is validated against the auth service (POST /auth/validate)
4. Valid session → connection accepted, user identity injected into context
5. Invalid/missing → connection rejected at the transport layer (4403 Forbidden)

This ensures unauthenticated users cannot subscribe to notification streams. See Notification Connection Modes for the full auth flow.

Patching Details

The patches/@nestjs__graphql@13.3.0.patch file applies three critical fixes:

Startup Orchestration

The scripts/dev/start_services.sh script orchestrates service startup with health-check wait loops:

1. Infrastructure (Postgres, Redis, MongoDB, Meilisearch, Conduit) — 30s timeout
2. Rust subgraphs (auth, uchat, scim, intelligence) — 60s timeout
3. NestJS subgraphs (services, products, alerts) — 120s timeout (webpack compilation)
4. Gateway — starts after all subgraphs are healthy

NestJS subgraphs require ~90–120s on first boot due to webpack compilation. The wait loops poll the GraphQL endpoint until it responds with a valid __typename.

Benchmarks

Hive Gateway significantly outperforms the legacy Apollo Gateway:

See benchmark report for the full comparison.

Environment Variables

Module Structure

apps/ngwenya-gateway/src/
├── app.module.ts                # Gateway module with HiveGatewayDriver config + SDL sanitization
├── auth.context.ts              # Session cookie / Bearer token → user identity resolution
├── ws-auth.ts                   # WebSocket session cookie validation (onConnect hook)
├── rate-limit/                  # Dual-window throttling (see /dev/gateway-rate-limiting)
├── tracing/                     # Response cache, APQ, metrics, health (see /dev/gateway-tracing)
├── deprecation/                 # Field deprecation tracking
├── sitemap/                     # XML sitemap generation
└── rss/                         # RSS feed controller

Related

• Gateway Rate Limiting — Dual-window throttling, auth uplift, mutation penalties
• Gateway Tracing & Observability — Response caching, APQ, Prometheus metrics
• Notification Connection Modes — WebSocket subscription transport architecture
• Local Development Environment — Full-stack setup, Podman, make targets