GraphQL Architecture Diagram: Schema, Resolvers, Federation & Subscriptions (2026)
How to create GraphQL architecture diagrams. Covers schema design, resolver chains, Apollo Federation, DataLoader batching, subscriptions, persisted queries, and GraphQL vs REST — with AI prompt templates.
R
Ryan·Senior AI Engineer
GraphQL architecture diagrams need to convey several layers that REST diagrams don't: the schema as a contract, the resolver execution tree, the DataLoader batching layer that prevents N+1 queries, and — for federated systems — how a supergraph stitches together subgraph schemas from multiple microservices. A GraphQL diagram that only shows “client → GraphQL server → database” misses the details that actually matter for performance and maintainability. This guide covers the components to include at each layer and prompt templates for generating accurate GraphQL architecture diagrams.
Core components of a GraphQL architecture diagram
- Clients: Web (Apollo Client, urql, URQL), mobile (Apollo iOS/Android), and server-to-server clients. Show whether clients use query batching, persisted queries (APQ), or normalized caching (Apollo InMemoryCache).
- GraphQL gateway / router: For federated architectures, the Apollo Router or GraphQL Mesh acts as the supergraph entry point. It validates the query against the supergraph schema, plans execution across subgraphs, and federates results. Show the router separately from subgraph servers.
- Subgraphs (Apollo Federation): Individual microservices that expose a partial schema and implement the federation spec (entity types,
@keydirectives, stub resolvers). Each subgraph owns a domain (users, products, orders). Show subgraph service → its data source. - Schema registry: Apollo Schema Registry or a self-hosted alternative that stores schema versions, validates composition, and enables schema checks in CI. Show the CI pipeline pushing schema changes to the registry before deployment.
- Resolver layer: The resolver execution tree for a query — show how the root query resolver calls field resolvers, which call DataLoaders, which batch database queries. This is most useful in sequence diagram form.
- DataLoader: The batching and caching layer that prevents N+1 query problems. A DataLoader collects individual entity IDs requested across multiple resolver calls in a single tick, then issues one batched query. Show DataLoader between resolvers and the data source.
- Data sources: Databases (PostgreSQL, MongoDB), REST APIs, gRPC services, and caches (Redis) that resolvers call. For each subgraph, show its primary data source and any Redis caching layer in front of it.
- Subscriptions infrastructure: WebSocket or SSE transport, subscription manager (typically backed by Redis pub/sub for horizontal scaling), and how subscription events are published by mutation resolvers and delivered to subscribers.
- Middleware / plugins: Authentication (JWT validation, Datadog), rate limiting, query depth limiting, query complexity analysis, and query allow-listing. Show these as layers or interceptors on the request path.
Prompt examples for GraphQL architecture diagrams
Apollo Federation supergraph
"Apollo Federation 2 supergraph for an e-commerce platform. Apollo Router as the supergraph gateway (deployed on Kubernetes). Three subgraphs: (1) Users subgraph — owns User type with @key(fields: 'id'), backed by PostgreSQL; (2) Products subgraph — owns Product type with @key(fields: 'id'), backed by MongoDB; (3) Orders subgraph — owns Order type, references User and Product via stub resolvers, backed by PostgreSQL. Schema Registry: Apollo GraphOS validates composition on every schema change before deployment. Clients: React web app (Apollo Client with InMemoryCache) and a mobile app (Apollo iOS). Show: clients → Router → subgraphs → databases. Show the entity resolution flow when a client queries Order.user (Router fetches order from Orders subgraph, then fetches User entity from Users subgraph using the user ID from the order)."
N+1 prevention with DataLoader
"GraphQL resolver execution sequence for a query that fetches a list of 10 posts with their authors. Without DataLoader: root resolver fetches 10 posts (1 DB query) → for each post, Post.author resolver fires (10 separate SELECT queries by user_id) = 11 queries total. With DataLoader: root resolver fetches 10 posts (1 DB query) → all 10 Post.author resolver calls are collected in the same event loop tick → DataLoader batches the 10 user IDs into one SELECT WHERE id IN (1,2,...,10) → DataLoader caches results in request scope → 2 queries total. Show as a sequence diagram comparing the two flows. Annotate the event loop tick boundary where DataLoader collects IDs."
Real-time subscriptions with horizontal scaling
"GraphQL subscriptions architecture for a real-time chat app with horizontal scaling. Multiple GraphQL server instances behind a load balancer. Client connects via WebSocket to any server instance. When a message is sent via a mutation (handled by any server instance), the resolver publishes to a Redis pub/sub channel 'chat:{roomId}'. All server instances subscribe to Redis pub/sub and forward messages to their connected WebSocket clients who are subscribed to that room. Show: clients → WebSocket load balancer → GraphQL instances → Redis pub/sub → instances → clients. Annotate the cross-instance pub/sub flow. Note: Apollo Server uses graphql-ws, subscriptions-transport-ws is deprecated."
Single-server GraphQL with caching layers
"Production GraphQL server architecture (single server, not federated). Clients (React web, mobile) hit a CDN (CloudFront) first — persisted queries (APQ) with GET requests are cached at the CDN edge for public/anonymous queries (TTL 60s). Cache miss → Apollo Server (Node.js, ECS Fargate) with middleware stack: JWT auth → rate limiter (Redis-backed, per user) → query complexity analysis (block queries with complexity > 1000) → query depth limiter (max depth 10) → resolver execution with DataLoader (caches within request scope) → PostgreSQL read replica for reads, primary for mutations. Partial query result caching via @cacheControl directives at the field level, stored in Redis. Show all middleware layers and caching boundaries."
GraphQL vs REST: what changes in the diagram
| Aspect | REST architecture | GraphQL architecture |
|---|---|---|
| Endpoint topology | Many resource endpoints | Single /graphql endpoint, operation-based |
| Caching | HTTP cache (CDN, ETag) per resource URL | Persisted queries for CDN; client-side normalized cache |
| N+1 problem | Less common; usually per-resource batching | Critical; DataLoader required in resolver layer |
| Schema contract | OpenAPI/Swagger spec | SDL schema; needs schema registry for federation |
| Real-time | SSE or WebSockets as separate endpoint | Subscriptions as first-class operation type |
What to annotate on a GraphQL diagram
- Query complexity limits: Show the maximum query complexity and depth thresholds configured, and where in the middleware stack they're enforced — preventing expensive queries is a critical production concern.
- Authentication scope: Whether auth is enforced at the gateway/router level or within individual subgraph resolvers. In federation, documenting which subgraphs trust the router's forwarded identity header is important.
- DataLoader scope: DataLoaders should be scoped per request (not shared globally). Annotate that DataLoader instances are created fresh per request in the context object.
- Schema ownership: In federation, annotate which team or service owns each subgraph schema. This makes it clear who to contact when a type changes.
- Subscription transport: Specify whether subscriptions use WebSockets (graphql-ws protocol) or HTTP SSE (newer, firewall-friendly). These require different infrastructure.
Related guides: API gateway architecture, microservice architecture patterns, Redis architecture diagrams, and WebSocket architecture diagrams.
Ready to try it yourself?
Start Creating - Free