You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@resilientdb.apache.org by ha...@apache.org on 2026/01/26 06:11:17 UTC
(incubator-resilientdb) branch development updated: GraphQ-LLM MCP server (#227)
This is an automated email from the ASF dual-hosted git repository.
harishgokul01 pushed a commit to branch development
in repository https://gitbox.apache.org/repos/asf/incubator-resilientdb.git
The following commit(s) were added to refs/heads/development by this push:
new f910800a GraphQ-LLM MCP server (#227)
f910800a is described below
commit f910800a5e8372ff6603dd8d11afbe1a6cb475be
Author: Harish <ha...@gmail.com>
AuthorDate: Sun Jan 25 22:11:13 2026 -0800
GraphQ-LLM MCP server (#227)
* Initial commit
* Initial commit
* Initial commit
* Initial commit
* setup
* setup
* Update docker-compose.dev.yml
* Update docker-compose.dev.yml
* setup update
* setup update
* fixed setup
* fixed setup
* Nexus integration
* Nexus integration
* nexus update
* nexus update
* setup update
* setup update
* feat: Dockerize MCP server and update documentation
- Add separate Docker service for MCP server in docker-compose.dev.yml
- MCP server runs as independent container using stdio transport
- Configured with stdin_open and tty for stdio communication
- Shares environment variables with backend service
- Update TEAM_SETUP.md with comprehensive MCP server setup instructions
- Add Step 5.1: Start MCP Server with Docker and local options
- Clarify separation between HTTP API backend and MCP server
- Update configuration summary and verification checklist
- Add MCP server to Quick Start Commands section
- Improve code clarity in src/index.ts
- Update console output to distinguish HTTP API Server from MCP Server
- Clarify port configuration display
- Add QUERY_TUTOR_EXAMPLES.md
- Comprehensive guide with GraphQL query examples
- Question-based prompts for RAG testing
- Recommended testing order and expected results
* feat: Dockerize MCP server and update documentation
- Add separate Docker service for MCP server in docker-compose.dev.yml
- MCP server runs as independent container using stdio transport
- Configured with stdin_open and tty for stdio communication
- Shares environment variables with backend service
- Update TEAM_SETUP.md with comprehensive MCP server setup instructions
- Add Step 5.1: Start MCP Server with Docker and local options
- Clarify separation between HTTP API backend and MCP server
- Update configuration summary and verification checklist
- Add MCP server to Quick Start Commands section
- Improve code clarity in src/index.ts
- Update console output to distinguish HTTP API Server from MCP Server
- Clarify port configuration display
- Add QUERY_TUTOR_EXAMPLES.md
- Comprehensive guide with GraphQL query examples
- Question-based prompts for RAG testing
- Recommended testing order and expected results
* test: Add comprehensive Docker services testing and MCP protocol verification
- Add TEST_DOCKER_SERVICES.md with complete testing guide
- Step-by-step verification procedures for all Docker services
- Network communication tests
- End-to-end flow testing
- Troubleshooting tips and common issues
- Add test-mcp-protocol.ts for MCP server protocol testing
- Tests MCP protocol communication via JSON-RPC over stdio
- Verifies all 5 core MCP operations:
* Initialize protocol
* List tools (9 tools verified)
* Check connection tool
* Execute GraphQL query tool
* Introspect schema tool
- All tests passing (5/5)
- Confirms MCP server is responding correctly to protocol calls
* test: Add comprehensive Docker services testing and MCP protocol verification
- Add TEST_DOCKER_SERVICES.md with complete testing guide
- Step-by-step verification procedures for all Docker services
- Network communication tests
- End-to-end flow testing
- Troubleshooting tips and common issues
- Add test-mcp-protocol.ts for MCP server protocol testing
- Tests MCP protocol communication via JSON-RPC over stdio
- Verifies all 5 core MCP operations:
* Initialize protocol
* List tools (9 tools verified)
* Check connection tool
* Execute GraphQL query tool
* Introspect schema tool
- All tests passing (5/5)
- Confirms MCP server is responding correctly to protocol calls
* Reslens integration
* my changes
* Apply changes after removing secret
* Clean up unnecessary files and add Docker setup for ResLens
- Removed temporary fix scripts and redundant documentation
- Added Docker support for ResLens Frontend and ResLens Middleware
- Updated docker-compose.dev.yml with ResLens services
- Fixed middleware connection URLs for browser compatibility
- Added check-docker-services.sh utility script
- Kept essential setup scripts and documentation
* Update README.md
* Update README.md
* Update README.md
* Fix backend container command and GraphQL URL configuration
- Fix docker-compose.dev.yml: Change backend command from 'npm run dev -- --http-api' to 'npm run http-api' for correct HTTP API mode
- Fix ingest-graphql-docs.ts: Remove incorrect RESILIENTDB_GRAPHQL_URL override pointing to HTTP wrapper (port 18001)
- HTTP wrapper only provides REST KV endpoints, not GraphQL server
- GraphQL operations must use port 5001
- Added clarifying comments about service separation
- Update environment.ts: Fix default RESILIENTDB_GRAPHQL_URL from port 18000 to 5001 with clarifying comment
- Enable ResLens Middleware and Frontend services in docker-compose.dev.yml
* Merge ResLens Docker setup into TEAM_SETUP.md and update TEST_DOCKER_SERVICES.md
- Merged DOCKER_RESLENS_SETUP.md content into TEAM_SETUP.md Step 5.2
- Added comprehensive ResLens Docker setup instructions including:
- Docker architecture details (multi-stage builds, Nginx setup)
- Complete environment variables documentation
- Networking configuration
- Service management commands (logs, stop, remove)
- Development vs Production comparison
- Enhanced troubleshooting sections
- Updated TEST_DOCKER_SERVICES.md to include ResLens services testing
- Added ResLens Middleware and Frontend to service architecture
- Added Step 5: Test ResLens Services with 6 sub-tests
- Added ResLens troubleshooting sections
- Updated verification checklists and success criteria
- Deleted standalone DOCKER_RESLENS_SETUP.md file
- Updated all documentation references
* Update README.md
* Update README.md
* Update README.md
* Update TEAM_SETUP.md to reference forked Nexus repository with GraphQ-LLM integration
* Fix remaining Nexus repository URLs to point to fork
* Add Nexus fork setup guide and script for team reference
* Add nexus/ to .gitignore and update scripts to use forked Nexus repository
* Remove nexus directory from git tracking (now using separate fork)
* Update README.md with Nexus fork information and setup instructions
* Add Nexus Fork Information section to README
* Simplify conclusion sentence in README
* Update README.md
* Add ResLens fork setup guide and script
* Configure ResLens to use separate fork repositories
- Update docker-compose.dev.yml to use absolute paths to forks
- Remove ResLens directories from git tracking (165 files)
- Update TEAM_SETUP.md with fork information
- Add ResLens to .gitignore
- Fork URLs:
- Frontend: sophiequynn/incubator-resilientdb-ResLens
- Middleware: sophiequynn/incubator-resilientdb-ResLens-Middleware
* Add ResLens fork clone commands to Quick Start section
* Update documentation for ResLens fork setup
- Add ResLens fork information to docs/README.md
- Update Quick Start to include ResLens fork cloning steps
- Add ResLens fork section similar to Nexus fork documentation
- Update TEAM_SETUP.md with detailed ResLens fork instructions
- Clarify that forks include GraphQ-LLM-specific modifications
* Clarify ResLens fork modifications in TEAM_SETUP.md
* Add ResLens fork cloning commands to prerequisites in Step 5.2
* Revise performance metrics section and add URLs
Updated section titles and added access URLs for various services.
* chore: Update docker-compose.dev.yml with local ResLens paths
- Update ResLens Middleware path to /Users/CelineJohnPhilip/DDS/ResLens-Middleware/middleware
- Update ResLens Frontend path to /Users/CelineJohnPhilip/DDS/ResLens
- Configured for local development environment
* Removed optimization related content.
Updated README to improve clarity and consistency in descriptions of features and sections.
* update
* update
* update
* Update README.md
* Fix ResLens frontend connection and enhance explanation quality
- Fix ResLens frontend middleware URL to use localhost instead of Docker service name (browser can't resolve service names)
- Increase token limits for detailed explanations (2000 for Gemini, 3000 for other models)
- Enhance system and detailed explanation prompts for more comprehensive responses
- Remove ResLens frontend dependency on middleware health check to allow startup
* Update docs/README.md with latest features and fixes
- Fix Nexus port inconsistency (3002 -> 3000)
- Document query stats button feature in efficiency tab
- Add note about ResLens frontend localhost configuration
- Enhance performance metrics section with ResLens integration details
* Fix ResLens paths to match current user setup
* Document chatbot UI route in README
---------
Co-authored-by: sophiequynn <39...@users.noreply.github.com>
Co-authored-by: celinejp <ce...@gmail.com>
Co-authored-by: Theodore Pan <77...@users.noreply.github.com>
Co-authored-by: sophiequynn <sj...@ucdavis.edu>
Co-authored-by: Sandhya <sg...@ucdavis.edu>
Co-authored-by: Ahadke <ha...@gmail.com>
---
ecosystem/ai-tools/mcp/graphq-llm/.dockerignore | 64 +
ecosystem/ai-tools/mcp/graphq-llm/.env.example | 52 +
ecosystem/ai-tools/mcp/graphq-llm/.eslintrc.json | 21 +
ecosystem/ai-tools/mcp/graphq-llm/.gitignore | 42 +
ecosystem/ai-tools/mcp/graphq-llm/Dockerfile | 54 +
.../ai-tools/mcp/graphq-llm/Dockerfile.all-in-one | 97 +
ecosystem/ai-tools/mcp/graphq-llm/Dockerfile.nexus | 55 +
.../ai-tools/mcp/graphq-llm/NEXUS_TEST_INPUTS.md | 183 ++
.../mcp/graphq-llm/NEXUS_UI_EXTENSION_GUIDE.md | 637 ++++++
.../mcp/graphq-llm/QUERY_TUTOR_EXAMPLES.md | 286 +++
.../ai-tools/mcp/graphq-llm/SETUP_NEXUS_FORK.md | 205 ++
.../ai-tools/mcp/graphq-llm/SETUP_RESLENS_FORK.md | 206 ++
ecosystem/ai-tools/mcp/graphq-llm/TEAM_SETUP.md | 1279 +++++++++++
.../mcp/graphq-llm/TEST_DOCKER_SERVICES.md | 504 +++++
ecosystem/ai-tools/mcp/graphq-llm/TEST_QUERIES.md | 283 +++
.../mcp/graphq-llm/check-docker-services.sh | 131 ++
.../ai-tools/mcp/graphq-llm/copy-repositories.sh | 131 ++
.../ai-tools/mcp/graphq-llm/docker-compose.dev.yml | 241 ++
.../ai-tools/mcp/graphq-llm/docker-compose.yml | 138 ++
.../mcp/graphq-llm/docs/GRAPHQL_SCHEMA_EXAMPLES.md | 182 ++
.../ai-tools/mcp/graphq-llm/docs/GRAPHQL_SETUP.md | 305 +++
.../ai-tools/mcp/graphq-llm/docs/HTTP_SERVER.md | 56 +
.../ai-tools/mcp/graphq-llm/docs/KV_SERVICE.md | 20 +
ecosystem/ai-tools/mcp/graphq-llm/docs/README.md | 373 ++++
.../community-guides/apollo/cache-configuration.md | 1227 +++++++++++
.../docs/community-guides/apollo/mutations.md | 1554 +++++++++++++
.../docs/community-guides/apollo/queries.md | 2018 +++++++++++++++++
.../community-guides/hasura/mutations-overview.md | 69 +
.../community-guides/hasura/mutations-postgres.md | 45 +
.../community-guides/hasura/queries-overview.md | 73 +
.../community-guides/hasura/queries-postgres.md | 74 +
.../community-guides/hasura/schema-overview.md | 82 +
.../community-guides/hasura/schema-postgres.md | 45 +
.../community-guides/relay/graphql-mutations.md | 463 ++++
.../community-guides/relay/rendering-queries.md | 302 +++
.../docs/graphql-official/learn/authorization.md | 93 +
.../docs/graphql-official/learn/best-practices.md | 62 +
.../docs/graphql-official/learn/caching.md | 58 +
.../docs/graphql-official/learn/debug-errors.md | 141 ++
.../docs/graphql-official/learn/execution.md | 173 ++
.../docs/graphql-official/learn/federation.md | 271 +++
.../docs/graphql-official/learn/file-uploads.md | 85 +
.../learn/global-object-identification.md | 365 +++
.../docs/graphql-official/learn/index.md | 105 +
.../docs/graphql-official/learn/introspection.md | 179 ++
.../docs/graphql-official/learn/mutations.md | 163 ++
.../docs/graphql-official/learn/pagination.md | 174 ++
.../docs/graphql-official/learn/performance.md | 87 +
.../docs/graphql-official/learn/queries.md | 350 +++
.../docs/graphql-official/learn/response.md | 123 ++
.../docs/graphql-official/learn/schema-design.md | 19 +
.../docs/graphql-official/learn/schema.md | 569 +++++
.../docs/graphql-official/learn/security.md | 202 ++
.../graphql-official/learn/serving-over-http.md | 139 ++
.../docs/graphql-official/learn/subscriptions.md | 102 +
.../graphql-official/learn/thinking-in-graphs.md | 75 +
.../docs/graphql-official/learn/validation.md | 157 ++
.../docs/graphql-spec/Section 2 -- Language.md | 1553 +++++++++++++
.../docs/graphql-spec/Section 3 -- Type System.md | 2323 ++++++++++++++++++++
.../docs/graphql-spec/Section 5 -- Validation.md | 2219 +++++++++++++++++++
.../docs/graphql-spec/Section 6 -- Execution.md | 941 ++++++++
.../docs/graphql-spec/Section 7 -- Response.md | 413 ++++
.../ai-tools/mcp/graphq-llm/docs/nft_market.md | 138 ++
ecosystem/ai-tools/mcp/graphq-llm/docs/research.md | 50 +
.../mcp/graphq-llm/docs/resilientdb-schema.graphql | 45 +
.../mcp/graphq-llm/docs/resilientdb-schema.md | 222 ++
.../ai-tools/mcp/graphq-llm/healthcheck-all.sh | 19 +
ecosystem/ai-tools/mcp/graphq-llm/ingest-docs.ts | 165 ++
.../ai-tools/mcp/graphq-llm/ingest-graphql-docs.ts | 146 ++
ecosystem/ai-tools/mcp/graphq-llm/init-postgres.sh | 29 +
.../mcp/graphq-llm/install-all-dependencies.sh | 87 +
ecosystem/ai-tools/mcp/graphq-llm/package.json | 53 +
ecosystem/ai-tools/mcp/graphq-llm/setup-graphql.sh | 93 +
.../ai-tools/mcp/graphq-llm/setup-nexus-fork.sh | 188 ++
ecosystem/ai-tools/mcp/graphq-llm/setup-nexus.sh | 31 +
.../ai-tools/mcp/graphq-llm/setup-reslens-fork.sh | 144 ++
.../ai-tools/mcp/graphq-llm/src/api/http-server.ts | 278 +++
.../mcp/graphq-llm/src/config/environment.ts | 68 +
.../ai-tools/mcp/graphq-llm/src/config/llm.ts | 60 +
ecosystem/ai-tools/mcp/graphq-llm/src/index.ts | 125 ++
.../mcp/graphq-llm/src/llm/explanation-service.ts | 584 +++++
.../ai-tools/mcp/graphq-llm/src/llm/llm-client.ts | 580 +++++
.../mcp/graphq-llm/src/llm/optimization-service.ts | 319 +++
.../ai-tools/mcp/graphq-llm/src/llm/prompts.ts | 222 ++
.../ai-tools/mcp/graphq-llm/src/mcp/server.ts | 741 +++++++
.../mcp/graphq-llm/src/nexus/integration.ts | 484 ++++
.../mcp/graphq-llm/src/pipeline/data-pipeline.ts | 193 ++
.../mcp/graphq-llm/src/rag/chunking-service.ts | 265 +++
.../mcp/graphq-llm/src/rag/context-formatter.ts | 242 ++
.../mcp/graphq-llm/src/rag/document-loader.ts | 187 ++
.../mcp/graphq-llm/src/rag/embedding-service.ts | 363 +++
.../mcp/graphq-llm/src/rag/ingestion-pipeline.ts | 359 +++
.../graphq-llm/src/rag/resilientdb-vector-store.ts | 741 +++++++
.../mcp/graphq-llm/src/rag/retrieval-service.ts | 242 ++
.../mcp/graphq-llm/src/resilientdb/client.ts | 250 +++
.../mcp/graphq-llm/src/resilientdb/http-wrapper.ts | 179 ++
.../ai-tools/mcp/graphq-llm/src/reslens/client.ts | 256 +++
.../src/services/efficiency-estimator.ts | 412 ++++
.../graphq-llm/src/services/live-stats-service.ts | 320 +++
.../mcp/graphq-llm/src/services/query-analyzer.ts | 282 +++
.../ai-tools/mcp/graphq-llm/src/types/index.ts | 86 +
.../ai-tools/mcp/graphq-llm/src/utils/cache.ts | 90 +
.../ai-tools/mcp/graphq-llm/supervisord-all.conf | 38 +
.../ai-tools/mcp/graphq-llm/test-mcp-protocol.ts | 396 ++++
ecosystem/ai-tools/mcp/graphq-llm/test-nexus.ts | 110 +
.../ai-tools/mcp/graphq-llm/test-rag-accuracy.ts | 431 ++++
.../ai-tools/mcp/graphq-llm/test-rag-queries.ts | 420 ++++
ecosystem/ai-tools/mcp/graphq-llm/test-rag.ts | 517 +++++
.../mcp/graphq-llm/test-specific-questions.ts | 68 +
ecosystem/ai-tools/mcp/graphq-llm/tsconfig.json | 27 +
110 files changed, 33983 insertions(+)
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/.dockerignore b/ecosystem/ai-tools/mcp/graphq-llm/.dockerignore
new file mode 100644
index 00000000..09ca740d
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/.dockerignore
@@ -0,0 +1,64 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Documentation (not needed in container)
+*.md
+# But allow docs/ for ingestion
+!docs/
+
+# Test files
+**/*.test.ts
+**/*.spec.ts
+test-*.ts
+test-*.sh
+
+# Scripts (not needed in production container)
+scripts/
+*.sh
+# But allow these specific scripts for database container
+!healthcheck.sh
+!healthcheck-all.sh
+!healthcheck-unified.sh
+!init-postgres.sh
+!setup-graphql.sh
+
+# Docker files
+Dockerfile*
+docker-compose*.yml
+.dockerignore
+
+# Logs
+logs/
+*.log
+
+# Misc
+coverage/
+.nyc_output/
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/.env.example b/ecosystem/ai-tools/mcp/graphq-llm/.env.example
new file mode 100644
index 00000000..dd306a51
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/.env.example
@@ -0,0 +1,52 @@
+# GraphQ-LLM Environment Configuration
+# Copy this file to .env and fill in your values
+
+# ============================================
+# ResilientDB Configuration (Required)
+# ============================================
+RESILIENTDB_GRAPHQL_URL=http://localhost:5000/graphql
+RESILIENTDB_API_KEY=
+
+# ============================================
+# ResLens Configuration (Optional - for Live Mode)
+# ============================================
+# Enable Live Mode for real-time stats accessible by LLM
+RESLENS_API_URL=
+RESLENS_API_KEY=
+RESLENS_LIVE_MODE=false
+RESLENS_POLL_INTERVAL=5000
+
+# ============================================
+# Nexus Configuration (Optional)
+# ============================================
+NEXUS_API_URL=
+NEXUS_API_KEY=
+
+# ============================================
+# LLM Configuration (Required for AI features)
+# ============================================
+# LLM Provider: 'deepseek', 'openai', or 'anthropic'
+LLM_PROVIDER=deepseek
+LLM_API_KEY=
+LLM_MODEL=deepseek-chat
+# Enable Live Stats access for LLM (requires ResLens)
+LLM_ENABLE_LIVE_STATS=false
+
+# ============================================
+# Embedding Configuration (Optional - Hugging Face)
+# ============================================
+# Hugging Face works without API key (public access, rate limited)
+# Get free token from https://huggingface.co/settings/tokens for higher limits
+HUGGINGFACE_API_KEY=
+
+# ============================================
+# MCP Server Configuration
+# ============================================
+MCP_SERVER_PORT=3001
+MCP_SERVER_HOST=0.0.0.0
+
+# ============================================
+# Logging & Environment
+# ============================================
+LOG_LEVEL=info
+NODE_ENV=development
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/.eslintrc.json b/ecosystem/ai-tools/mcp/graphq-llm/.eslintrc.json
new file mode 100644
index 00000000..8ef99380
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/.eslintrc.json
@@ -0,0 +1,21 @@
+{
+ "parser": "@typescript-eslint/parser",
+ "extends": [
+ "eslint:recommended",
+ "plugin:@typescript-eslint/recommended"
+ ],
+ "parserOptions": {
+ "ecmaVersion": 2022,
+ "sourceType": "module"
+ },
+ "rules": {
+ "@typescript-eslint/no-explicit-any": "warn",
+ "@typescript-eslint/explicit-function-return-type": "off",
+ "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }]
+ },
+ "env": {
+ "node": true,
+ "es2022": true
+ }
+}
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/.gitignore b/ecosystem/ai-tools/mcp/graphq-llm/.gitignore
new file mode 100644
index 00000000..36598abe
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/.gitignore
@@ -0,0 +1,42 @@
+# Dependencies
+node_modules/
+package-lock.json
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# External repositories (cloned locally for Docker builds)
+nexus/
+ResLens/
+ResLens-Middleware/
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+coverage/
+.nyc_output/
+
+# Temporary files
+tmp/
+temp/
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile b/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile
new file mode 100644
index 00000000..5bbb3494
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile
@@ -0,0 +1,54 @@
+# Dockerfile for GraphQ-LLM Backend
+# Multi-stage build for optimized production image
+
+# Stage 1: Build
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source code
+COPY src/ ./src/
+
+# Build TypeScript
+RUN npm run build
+
+# Stage 2: Production
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install production dependencies only
+RUN npm ci --only=production
+
+# Copy built files from builder
+COPY --from=builder /app/dist ./dist
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+ adduser -S nodejs -u 1001
+
+# Change ownership
+RUN chown -R nodejs:nodejs /app
+
+USER nodejs
+
+# Expose port (adjust if needed)
+EXPOSE 3001
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+ CMD node -e "require('http').get('http://localhost:3001/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})" || exit 1
+
+# Start the application
+CMD ["npm", "start"]
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile.all-in-one b/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile.all-in-one
new file mode 100644
index 00000000..57c84ffe
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile.all-in-one
@@ -0,0 +1,97 @@
+# All-in-One Dockerfile: ResilientDB + PostgreSQL + GraphQ-LLM Backend
+# Multi-stage build: Uses ResilientDB image and adds PostgreSQL + Node.js
+
+ARG ARCH=arm64
+
+# Stage 1: Get ResilientDB binaries
+FROM expolab/resdb:${ARCH} AS resilientdb-stage
+# Just to have the image available
+
+# Stage 2: Base with PostgreSQL and Node.js
+FROM ubuntu:22.04 AS base
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install base dependencies
+RUN apt-get update && apt-get install -y \
+ curl \
+ wget \
+ git \
+ build-essential \
+ python3 \
+ make \
+ g++ \
+ supervisor \
+ ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 20
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+ apt-get install -y nodejs && \
+ rm -rf /var/lib/apt/lists/*
+
+# Install PostgreSQL 14
+RUN apt-get update && apt-get install -y \
+ postgresql-14 \
+ postgresql-contrib-14 \
+ postgresql-server-dev-14 \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install pgvector extension
+RUN git clone --branch v0.5.1 https://github.com/pgvector/pgvector.git /tmp/pgvector && \
+ cd /tmp/pgvector && \
+ make && \
+ make install && \
+ cd / && \
+ rm -rf /tmp/pgvector && \
+ apt-get purge -y git build-essential postgresql-server-dev-14 && \
+ apt-get autoremove -y && \
+ rm -rf /var/lib/apt/lists/*
+
+# Copy ResilientDB binaries from the image (if we can access them)
+# For now, we'll use a volume mount or run ResilientDB in a sidecar
+# Actually, let's use docker-compose to run ResilientDB separately but in the same network
+# OR: Use the ResilientDB HTTP wrapper approach
+
+# Create directories
+RUN mkdir -p /var/lib/postgresql/data \
+ && mkdir -p /app/graphq-llm \
+ && mkdir -p /data \
+ && chown -R postgres:postgres /var/lib/postgresql/data
+
+# Copy GraphQ-LLM application files
+WORKDIR /app/graphq-llm
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Install Node.js dependencies
+RUN npm ci
+
+# Copy source code and build
+COPY src/ ./src/
+RUN npm run build
+
+# Copy supervisor configuration
+COPY supervisord-all.conf /etc/supervisor/conf.d/supervisord.conf
+
+# Copy scripts
+COPY healthcheck-all.sh /app/healthcheck-all.sh
+COPY init-postgres.sh /app/init-postgres.sh
+RUN chmod +x /app/healthcheck-all.sh /app/init-postgres.sh
+
+# Copy docs
+COPY docs/ /app/graphq-llm/docs/
+
+# Note: ResilientDB will run in a separate container but same network
+# We'll use docker-compose to link them, or use a sidecar pattern
+# For true all-in-one, we'd need to install ResilientDB from source (complex)
+
+# Expose ports
+EXPOSE 5432 3001
+
+# Health check (only PostgreSQL and GraphQ-LLM, ResilientDB is separate)
+HEALTHCHECK --interval=30s --timeout=10s --retries=5 --start-period=120s \
+ CMD /bin/bash -c "pg_isready -U nexus && curl -f http://localhost:3001/health || exit 1"
+
+# Start supervisor
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile.nexus b/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile.nexus
new file mode 100644
index 00000000..2674518c
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/Dockerfile.nexus
@@ -0,0 +1,55 @@
+# Dockerfile for Nexus (Next.js Application)
+# This builds the Nexus application for production deployment
+
+FROM node:20-alpine AS base
+
+# Install dependencies only when needed
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+# Copy package files
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Set environment variables for build
+ENV NEXT_TELEMETRY_DISABLED=1
+
+# Build Next.js application
+RUN npm run build
+
+# Production image
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+# Copy necessary files from builder
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+
+# Copy other necessary files
+COPY --from=builder /app/next.config.* ./
+COPY --from=builder /app/tsconfig.json ./
+
+USER nextjs
+
+EXPOSE 3000
+
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+# Start Next.js in production mode
+CMD ["npm", "start"]
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/NEXUS_TEST_INPUTS.md b/ecosystem/ai-tools/mcp/graphq-llm/NEXUS_TEST_INPUTS.md
new file mode 100644
index 00000000..51054701
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/NEXUS_TEST_INPUTS.md
@@ -0,0 +1,183 @@
+# ๐งช Nexus Test Inputs - Mix of Queries and Questions
+
+Use these inputs to test the GraphQL Tutor in Nexus. Copy and paste them into the query editor.
+
+---
+
+## ๐ GraphQL Queries (10 queries)
+
+### **1. Simple Transaction Query**
+```graphql
+{ getTransaction(id: "123") { asset } }
+```
+
+### **2. Complete Transaction with All Fields**
+```graphql
+{ getTransaction(id: "abc123") { id version amount uri type publicKey signerPublicKey operation metadata asset } }
+```
+
+### **3. Transaction with Selected Fields**
+```graphql
+{ getTransaction(id: "txn_001") { id operation amount asset } }
+```
+
+### **4. Transaction Metadata Query**
+```graphql
+{ getTransaction(id: "metadata_test") { id version metadata operation } }
+```
+
+### **5. Transaction with Named Query**
+```graphql
+query GetTransaction { getTransaction(id: "test123") { id asset amount } }
+```
+
+### **6. Minimal Transaction Query**
+```graphql
+{ getTransaction(id: "minimal") { id operation } }
+```
+
+### **7. Transaction with Public Keys**
+```graphql
+{ getTransaction(id: "key_test") { id publicKey signerPublicKey operation type } }
+```
+
+### **8. Transaction Amount and URI**
+```graphql
+{ getTransaction(id: "amount_uri") { id amount uri version } }
+```
+
+### **9. Complete Transaction Query**
+```graphql
+query GetFullTransaction { getTransaction(id: "comprehensive") { id version amount uri type publicKey signerPublicKey operation metadata asset } }
+```
+
+### **10. Transaction with Aliases**
+```graphql
+query GetTransactionDetails { transaction: getTransaction(id: "alias_test") { transactionId: id transactionType: type transactionOperation: operation transactionAmount: amount assetData: asset } }
+```
+
+---
+
+## โ General Questions & Doubts (15 questions)
+
+### **GraphQL Basics:**
+1. **What is GraphQL?**
+2. **How do I write a GraphQL query?**
+3. **What is the difference between query and mutation?**
+4. **How do I use variables in GraphQL?**
+5. **What are GraphQL fragments?**
+
+### **ResilientDB Specific:**
+6. **What is ResilientDB?**
+7. **How do I retrieve a transaction by ID?**
+8. **What fields are available in the Query type?**
+9. **How do I create a transaction using GraphQL?**
+10. **What is the PrepareAsset input type?**
+
+### **GraphQL Advanced Topics:**
+11. **How do I filter transactions?**
+12. **What mutations are available?**
+13. **How does GraphQL pagination work?**
+14. **What is GraphQL introspection?**
+15. **How do I handle errors in GraphQL?**
+
+---
+
+## ๐ฏ Recommended Testing Order
+
+### **Phase 1: Basic Queries (Start Here)**
+1. Start with **Query #1** (simplest)
+2. Try **Question #1**: "What is GraphQL?"
+3. Try **Query #3** (selected fields)
+4. Try **Question #2**: "How do I write a GraphQL query?"
+
+### **Phase 2: Intermediate Testing**
+5. Try **Query #5** (named query)
+6. Try **Question #7**: "How do I retrieve a transaction by ID?"
+7. Try **Query #2** (complete transaction)
+8. Try **Question #9**: "How do I create a transaction using GraphQL?"
+
+### **Phase 3: Advanced Testing**
+9. Try **Query #9** (comprehensive)
+10. Try **Query #10** (aliases)
+11. Try **Question #11**: "How do I filter transactions?"
+12. Try **Question #13**: "How does GraphQL pagination work?"
+
+### **Phase 4: Edge Cases**
+13. Try **Question #6**: "What is ResilientDB?"
+14. Try **Query #6** (minimal)
+15. Try **Question #15**: "How do I handle errors in GraphQL?"
+
+---
+
+## ๐ What to Check for Each Input
+
+### **For GraphQL Queries:**
+- โ
**Explanation:** Should explain what the query does
+- โ
**Complexity:** Should show complexity level (low/medium/high)
+- โ
**Documentation Context:** Should reference relevant docs
+- โ
**Optimization Suggestions:** Should provide actionable recommendations
+- โ
**Efficiency Metrics:** Should show estimated performance (score, time, resources)
+
+### **For General Questions:**
+- โ
**Answer Quality:** Should provide clear, helpful answers
+- โ
**Documentation Usage:** Should use RAG to retrieve relevant docs
+- โ
**Context Awareness:** Should understand the question
+- โ
**Examples:** Should include examples when helpful
+- โ
**Completeness:** Should answer the question fully
+
+---
+
+## ๐ก Testing Tips
+
+1. **Mix It Up:** Alternate between queries and questions
+2. **Compare Results:** Try similar queries/questions to see consistency
+3. **Check All Tabs:** Review Explanation, Optimization, and Efficiency tabs
+4. **Verify Documentation:** Ensure explanations reference correct docs
+5. **Test Edge Cases:** Try invalid queries or unclear questions
+6. **Check Response Time:** Note how long each analysis takes
+
+---
+
+## ๐ Expected Behaviors
+
+### **Simple Queries (1, 3, 6):**
+- Complexity: **Low**
+- Efficiency Score: **90-100**
+- Should suggest: Field selection optimization (if many fields)
+
+### **Complete Queries (2, 9):**
+- Complexity: **Medium/High**
+- Efficiency Score: **70-90**
+- Should suggest: Select only needed fields
+
+### **General Questions:**
+- Should retrieve 3-5 relevant documentation chunks
+- Should provide comprehensive answers
+- Should include examples when relevant
+- Should reference ResilientDB/GraphQL documentation
+
+---
+
+## ๐ Quick Copy-Paste List
+
+**Copy these one by one into Nexus:**
+
+**Queries:**
+1. `{ getTransaction(id: "123") { asset } }`
+2. `{ getTransaction(id: "abc123") { id version amount uri type publicKey signerPublicKey operation metadata asset } }`
+3. `{ getTransaction(id: "txn_001") { id operation amount asset } }`
+4. `{ getTransaction(id: "metadata_test") { id version metadata operation } }`
+5. `query GetTransaction { getTransaction(id: "test123") { id asset amount } }`
+
+**Questions:**
+1. What is GraphQL?
+2. How do I write a GraphQL query?
+3. What is ResilientDB?
+4. How do I retrieve a transaction by ID?
+5. How do I create a transaction using GraphQL?
+
+---
+
+**Happy Testing! ๐**
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/NEXUS_UI_EXTENSION_GUIDE.md b/ecosystem/ai-tools/mcp/graphq-llm/NEXUS_UI_EXTENSION_GUIDE.md
new file mode 100644
index 00000000..675bc740
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/NEXUS_UI_EXTENSION_GUIDE.md
@@ -0,0 +1,637 @@
+# ๐ Nexus UI Extension Guide - Complete Code
+
+This guide contains all the code needed to add the GraphQL Tutor UI to Nexus. Copy these files exactly as shown.
+
+---
+
+## ๐ File Structure
+
+```
+nexus/
+โโโ src/
+โ โโโ app/
+โ โ โโโ api/
+โ โ โ โโโ graphql-tutor/
+โ โ โ โโโ analyze/
+โ โ โ โโโ route.ts โ Create this
+โ โ โโโ graphql-tutor/
+โ โ โ โโโ page.tsx โ Create this
+โ โ โ โโโ components/
+โ โ โ โโโ tutor-panel.tsx โ Create this
+โ โ โ โโโ explanation-panel.tsx โ Create this
+โ โ โ โโโ optimization-panel.tsx โ Create this
+โ โ โ โโโ efficiency-display.tsx โ Create this
+โ โ โโโ page.tsx โ Modify this (add navigation link)
+```
+
+---
+
+## 1. API Route: `src/app/api/graphql-tutor/analyze/route.ts`
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+
+/**
+ * GraphQ-LLM Analysis API
+ * Proxies requests to GraphQ-LLM backend for full query analysis
+ */
+export async function POST(req: NextRequest) {
+ try {
+ const { query } = await req.json();
+
+ if (!query || typeof query !== "string") {
+ return NextResponse.json(
+ { error: "Query is required" },
+ { status: 400 }
+ );
+ }
+
+ // GraphQ-LLM backend URL (from environment or default)
+ const graphqLlmUrl = process.env.GRAPHQ_LLM_API_URL ||
+ process.env.NEXT_PUBLIC_GRAPHQ_LLM_API_URL ||
+ "http://localhost:3001";
+
+ try {
+ // Call GraphQ-LLM explanation service
+ const explainResponse = await fetch(`${graphqLlmUrl}/api/explanations/explain`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ query, detailed: true }),
+ });
+
+ // Call GraphQ-LLM optimization service
+ const optimizeResponse = await fetch(`${graphqLlmUrl}/api/optimizations/optimize`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ query, includeSimilarQueries: true }),
+ });
+
+ // Call GraphQ-LLM efficiency service
+ const efficiencyResponse = await fetch(`${graphqLlmUrl}/api/efficiency/estimate`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ query, useLiveStats: false }),
+ });
+
+ // Parse responses
+ const explanationData = explainResponse.ok ? await explainResponse.json() : null;
+ const optimizationData = optimizeResponse.ok ? await optimizeResponse.json() : null;
+ const efficiencyData = efficiencyResponse.ok ? await efficiencyResponse.json() : null;
+
+ // Format explanation response for UI
+ const explanation = explanationData
+ ? {
+ explanation: explanationData.explanation || "No explanation available",
+ complexity: explanationData.complexity || "medium",
+ recommendations: explanationData.recommendations || [],
+ }
+ : {
+ explanation: "Explanation service unavailable. Please ensure GraphQ-LLM backend is running.",
+ complexity: "unknown",
+ recommendations: [],
+ };
+
+ // Format optimizations response for UI
+ const optimizations = optimizationData?.suggestions
+ ? optimizationData.suggestions.map((s: any) => ({
+ query: s.optimizedQuery || query,
+ explanation: s.reason || s.suggestion || "Optimization suggestion",
+ confidence: 0.8,
+ }))
+ : [];
+
+ // Format efficiency response for UI
+ const efficiency = efficiencyData
+ ? {
+ score: efficiencyData.efficiencyScore || 0,
+ estimatedTime: efficiencyData.estimatedExecutionTime
+ ? `${efficiencyData.estimatedExecutionTime}ms`
+ : "Unknown",
+ resourceUsage: efficiencyData.estimatedResourceUsage
+ ? `CPU: ${efficiencyData.estimatedResourceUsage.cpu || "N/A"}%, Memory: ${efficiencyData.estimatedResourceUsage.memory || "N/A"}MB`
+ : "Unknown",
+ recommendations: efficiencyData.recommendations || [],
+ complexity: efficiencyData.complexity,
+ similarQueries: efficiencyData.similarQueries,
+ }
+ : {
+ score: 0,
+ estimatedTime: "Unknown",
+ resourceUsage: "Unknown",
+ recommendations: [],
+ complexity: "unknown",
+ };
+
+ return NextResponse.json({
+ explanation,
+ optimizations,
+ efficiency,
+ });
+ } catch (fetchError) {
+ // Fallback to mock data if GraphQ-LLM backend is not available
+ console.warn("GraphQ-LLM backend not available, using fallback:", fetchError);
+
+ return NextResponse.json({
+ explanation: {
+ explanation: `This query retrieves transaction data from ResilientDB. The query structure suggests it's fetching a single transaction by ID.`,
+ complexity: "low",
+ recommendations: [
+ "Consider adding pagination for large result sets",
+ "Use specific field selections to reduce payload size",
+ ],
+ },
+ optimizations: [
+ {
+ query: query,
+ explanation: "Query is already well-optimized for single transaction retrieval.",
+ confidence: 0.85,
+ },
+ ],
+ efficiency: {
+ score: 92,
+ estimatedTime: "< 10ms",
+ resourceUsage: "Low - Single transaction lookup",
+ recommendations: [
+ "Query is efficient for single transaction retrieval",
+ ],
+ },
+ });
+ }
+ } catch (error) {
+ console.error("Error analyzing query:", error);
+ return NextResponse.json(
+ { error: "Failed to analyze query" },
+ { status: 500 }
+ );
+ }
+}
+```
+
+---
+
+## 2. Main Page: `src/app/graphql-tutor/page.tsx`
+
+```typescript
+"use client";
+
+import { useState } from "react";
+import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from "@/components/ui/resizable";
+import { Card, CardHeader, CardTitle, CardDescription, CardContent } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { TutorPanel } from "./components/tutor-panel";
+import { Loader2 } from "lucide-react";
+
+export default function GraphQLTutorPage() {
+ const [query, setQuery] = useState("");
+ const [analysis, setAnalysis] = useState<any>(null);
+ const [loading, setLoading] = useState(false);
+
+ const handleAnalyze = async () => {
+ if (!query.trim()) return;
+
+ setLoading(true);
+ try {
+ const response = await fetch("/api/graphql-tutor/analyze", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ query }),
+ });
+
+ const data = await response.json();
+ setAnalysis(data);
+ } catch (error) {
+ console.error("Error analyzing query:", error);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ return (
+ <div className="container mx-auto p-6 h-screen flex flex-col">
+ <div className="mb-4">
+ <h1 className="text-3xl font-bold">GraphQL Query Tutor</h1>
+ <p className="text-muted-foreground">
+ Get AI-powered explanations, optimizations, and efficiency analysis for your GraphQL queries
+ </p>
+ </div>
+
+ <ResizablePanelGroup direction="horizontal" className="flex-1">
+ <ResizablePanel defaultSize={50} minSize={30}>
+ <Card className="h-full flex flex-col">
+ <CardHeader>
+ <CardTitle>GraphQL Query Editor</CardTitle>
+ <CardDescription>
+ Write and analyze your ResilientDB GraphQL queries
+ </CardDescription>
+ </CardHeader>
+ <CardContent className="flex-1 flex flex-col">
+ <textarea
+ value={query}
+ onChange={(e) => setQuery(e.target.value)}
+ placeholder='Enter your GraphQL query, e.g., { getTransaction(id: "123") { asset } }'
+ className="flex-1 w-full p-4 border rounded-md font-mono text-sm resize-none"
+ />
+ <Button
+ onClick={handleAnalyze}
+ disabled={loading || !query.trim()}
+ className="mt-4"
+ >
+ {loading ? (
+ <>
+ <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+ Analyzing...
+ </>
+ ) : (
+ "Analyze Query"
+ )}
+ </Button>
+ </CardContent>
+ </Card>
+ </ResizablePanel>
+
+ <ResizableHandle />
+
+ <ResizablePanel defaultSize={50} minSize={30}>
+ <TutorPanel analysis={analysis} loading={loading} />
+ </ResizablePanel>
+ </ResizablePanelGroup>
+ </div>
+ );
+}
+```
+
+---
+
+## 3. Tutor Panel: `src/app/graphql-tutor/components/tutor-panel.tsx`
+
+```typescript
+"use client";
+
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { ExplanationPanel } from "./explanation-panel";
+import { OptimizationPanel } from "./optimization-panel";
+import { EfficiencyDisplay } from "./efficiency-display";
+import { Loader2 } from "lucide-react";
+
+interface TutorPanelProps {
+ analysis: any;
+ loading: boolean;
+}
+
+export function TutorPanel({ analysis, loading }: TutorPanelProps) {
+ if (loading) {
+ return (
+ <Card className="h-full flex items-center justify-center">
+ <Loader2 className="h-8 w-8 animate-spin" />
+ </Card>
+ );
+ }
+
+ if (!analysis) {
+ return (
+ <Card className="h-full flex items-center justify-center">
+ <p className="text-muted-foreground">
+ Enter a query and click "Analyze Query" to get started
+ </p>
+ </Card>
+ );
+ }
+
+ return (
+ <Card className="h-full flex flex-col">
+ <CardHeader>
+ <CardTitle>AI Tutor</CardTitle>
+ <p className="text-sm text-muted-foreground">
+ Get explanations, optimizations, and efficiency analysis
+ </p>
+ </CardHeader>
+ <CardContent className="flex-1 overflow-auto">
+ <Tabs defaultValue="explanation" className="w-full">
+ <TabsList className="grid w-full grid-cols-3">
+ <TabsTrigger value="explanation">Explanation</TabsTrigger>
+ <TabsTrigger value="optimization">Optimization</TabsTrigger>
+ <TabsTrigger value="efficiency">Efficiency</TabsTrigger>
+ </TabsList>
+ <TabsContent value="explanation" className="mt-4">
+ <ExplanationPanel explanation={analysis.explanation} />
+ </TabsContent>
+ <TabsContent value="optimization" className="mt-4">
+ <OptimizationPanel optimizations={analysis.optimizations} />
+ </TabsContent>
+ <TabsContent value="efficiency" className="mt-4">
+ <EfficiencyDisplay efficiency={analysis.efficiency} />
+ </TabsContent>
+ </Tabs>
+ </CardContent>
+ </Card>
+ );
+}
+```
+
+---
+
+## 4. Explanation Panel: `src/app/graphql-tutor/components/explanation-panel.tsx`
+
+```typescript
+"use client";
+
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+
+interface ExplanationPanelProps {
+ explanation: any;
+}
+
+export function ExplanationPanel({ explanation }: ExplanationPanelProps) {
+ if (!explanation) {
+ return <p className="text-muted-foreground">No explanation available</p>;
+ }
+
+ return (
+ <div className="space-y-4">
+ <div>
+ <h3 className="text-lg font-semibold mb-2">Query Explanation</h3>
+ <p className="text-sm text-muted-foreground mb-4">What this query does</p>
+ <div className="prose prose-sm max-w-none">
+ <p className="whitespace-pre-wrap">{explanation.explanation}</p>
+ </div>
+ </div>
+
+ {explanation.complexity && (
+ <div>
+ <h4 className="text-md font-semibold mb-2">Complexity</h4>
+ <Badge variant={
+ explanation.complexity === "low" ? "default" :
+ explanation.complexity === "medium" ? "secondary" : "destructive"
+ }>
+ {explanation.complexity}
+ </Badge>
+ </div>
+ )}
+
+ {explanation.recommendations && explanation.recommendations.length > 0 && (
+ <div>
+ <h4 className="text-md font-semibold mb-2">Recommendations</h4>
+ <ul className="list-disc list-inside space-y-1">
+ {explanation.recommendations.map((rec: string, idx: number) => (
+ <li key={idx} className="text-sm">{rec}</li>
+ ))}
+ </ul>
+ </div>
+ )}
+ </div>
+ );
+}
+```
+
+---
+
+## 5. Optimization Panel: `src/app/graphql-tutor/components/optimization-panel.tsx`
+
+```typescript
+"use client";
+
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+
+interface OptimizationPanelProps {
+ optimizations: any[];
+}
+
+export function OptimizationPanel({ optimizations }: OptimizationPanelProps) {
+ if (!optimizations || optimizations.length === 0) {
+ return <p className="text-muted-foreground">No optimization suggestions available</p>;
+ }
+
+ return (
+ <div className="space-y-4">
+ <h3 className="text-lg font-semibold">Optimization Suggestions</h3>
+ {optimizations.map((opt, idx) => (
+ <Card key={idx}>
+ <CardHeader>
+ <div className="flex items-center justify-between">
+ <CardTitle className="text-sm">Suggestion {idx + 1}</CardTitle>
+ {opt.confidence && (
+ <Badge variant="outline">
+ {Math.round(opt.confidence * 100)}% confidence
+ </Badge>
+ )}
+ </div>
+ </CardHeader>
+ <CardContent>
+ <p className="text-sm mb-2">{opt.explanation}</p>
+ {opt.query && (
+ <div className="mt-2">
+ <p className="text-xs text-muted-foreground mb-1">Optimized Query:</p>
+ <code className="text-xs bg-muted p-2 rounded block">
+ {opt.query}
+ </code>
+ </div>
+ )}
+ </CardContent>
+ </Card>
+ ))}
+ </div>
+ );
+}
+```
+
+---
+
+## 6. Efficiency Display: `src/app/graphql-tutor/components/efficiency-display.tsx`
+
+```typescript
+"use client";
+
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
+import { Progress } from "@/components/ui/progress";
+import { Badge } from "@/components/ui/badge";
+
+interface EfficiencyDisplayProps {
+ efficiency: any;
+}
+
+export function EfficiencyDisplay({ efficiency }: EfficiencyDisplayProps) {
+ if (!efficiency) {
+ return <p className="text-muted-foreground">No efficiency data available</p>;
+ }
+
+ const score = efficiency.score || 0;
+ const scoreColor = score >= 80 ? "text-green-600" : score >= 60 ? "text-yellow-600" : "text-red-600";
+
+ return (
+ <div className="space-y-4">
+ <div>
+ <h3 className="text-lg font-semibold mb-2">Efficiency Score</h3>
+ <div className="space-y-2">
+ <div className="flex items-center justify-between">
+ <span className="text-sm">Overall Efficiency</span>
+ <span className={`text-2xl font-bold ${scoreColor}`}>{score}/100</span>
+ </div>
+ <Progress value={score} className="h-2" />
+ </div>
+ </div>
+
+ <div className="grid grid-cols-2 gap-4">
+ <Card>
+ <CardHeader>
+ <CardTitle className="text-sm">Estimated Time</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <p className="text-2xl font-bold">{efficiency.estimatedTime || "Unknown"}</p>
+ </CardContent>
+ </Card>
+
+ <Card>
+ <CardHeader>
+ <CardTitle className="text-sm">Resource Usage</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <p className="text-sm">{efficiency.resourceUsage || "Unknown"}</p>
+ </CardContent>
+ </Card>
+ </div>
+
+ {efficiency.complexity && (
+ <div>
+ <h4 className="text-md font-semibold mb-2">Complexity</h4>
+ <Badge variant={
+ efficiency.complexity === "low" ? "default" :
+ efficiency.complexity === "medium" ? "secondary" : "destructive"
+ }>
+ {efficiency.complexity}
+ </Badge>
+ </div>
+ )}
+
+ {efficiency.recommendations && efficiency.recommendations.length > 0 && (
+ <div>
+ <h4 className="text-md font-semibold mb-2">Recommendations</h4>
+ <ul className="list-disc list-inside space-y-1">
+ {efficiency.recommendations.map((rec: string, idx: number) => (
+ <li key={idx} className="text-sm">{rec}</li>
+ ))}
+ </ul>
+ </div>
+ )}
+ </div>
+ );
+}
+```
+
+---
+
+## 7. Update Home Page: `src/app/page.tsx`
+
+Add a navigation link to the GraphQL Tutor. Find your navigation section and add:
+
+```typescript
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+
+// In your navigation or main content area:
+<Link href="/graphql-tutor">
+ <Button variant="outline">GraphQL Tutor</Button>
+</Link>
+```
+
+---
+
+## 8. Environment Variables
+
+Add to Nexus `.env` file:
+
+```env
+# GraphQ-LLM Backend URL
+GRAPHQ_LLM_API_URL=http://localhost:3001
+# Or use NEXT_PUBLIC_ prefix for client-side access:
+NEXT_PUBLIC_GRAPHQ_LLM_API_URL=http://localhost:3001
+```
+
+---
+
+## 9. Required Dependencies
+
+Ensure these are installed in Nexus:
+
+```bash
+cd /path/to/nexus
+npm install lucide-react
+
+# If using shadcn/ui (recommended):
+# These should already be installed, but verify:
+npm install @radix-ui/react-tabs
+npm install @radix-ui/react-progress
+```
+
+---
+
+## 10. Verification
+
+After creating all files:
+
+1. **Restart Nexus:**
+ ```bash
+ # Stop current server (Ctrl+C)
+ npm run dev
+ ```
+
+2. **Test the API route:**
+ ```bash
+ curl -X POST http://localhost:3000/api/graphql-tutor/analyze \
+ -H "Content-Type: application/json" \
+ -d '{"query":"{ getTransaction(id: \"123\") { asset } }"}'
+ ```
+
+3. **Test the UI:**
+ - Open `http://localhost:3000/graphql-tutor`
+ - Enter a query
+ - Click "Analyze Query"
+ - Verify you see explanation, optimization, and efficiency tabs
+
+---
+
+## ๐ Troubleshooting
+
+### **Issue: Components not found**
+
+**Solution:** Ensure all component files are created in the correct directories:
+- `src/app/graphql-tutor/components/tutor-panel.tsx`
+- `src/app/graphql-tutor/components/explanation-panel.tsx`
+- `src/app/graphql-tutor/components/optimization-panel.tsx`
+- `src/app/graphql-tutor/components/efficiency-display.tsx`
+
+### **Issue: UI components not rendering**
+
+**Solution:**
+- Check that shadcn/ui components are installed
+- Verify imports match your component library structure
+- Check browser console for errors
+
+### **Issue: API route returns 500 error**
+
+**Solution:**
+- Verify GraphQ-LLM backend is running: `curl http://localhost:3001/health`
+- Check `GRAPHQ_LLM_API_URL` in Nexus `.env`
+- Check Nexus server logs for errors
+
+---
+
+## โ
Checklist
+
+After setup, verify:
+
+- [ ] All 6 files created in correct locations
+- [ ] Navigation link added to home page
+- [ ] Environment variable `GRAPHQ_LLM_API_URL` set
+- [ ] Dependencies installed (`lucide-react`, shadcn/ui components)
+- [ ] Nexus restarted
+- [ ] API route responds: `curl http://localhost:3000/api/graphql-tutor/analyze`
+- [ ] UI page accessible: `http://localhost:3000/graphql-tutor`
+- [ ] Query analysis works in UI
+
+---
+
+**That's it! Your Nexus UI now has the GraphQL Tutor integration! ๐**
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/QUERY_TUTOR_EXAMPLES.md b/ecosystem/ai-tools/mcp/graphq-llm/QUERY_TUTOR_EXAMPLES.md
new file mode 100644
index 00000000..efb1c1d5
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/QUERY_TUTOR_EXAMPLES.md
@@ -0,0 +1,286 @@
+# ๐ Example Prompts for GraphQL Query Tutor
+
+Use these example prompts to test the GraphQL Query Tutor in Nexus. Copy and paste them into the query editor.
+
+---
+
+## ๐ GraphQL Query Examples (For Analysis)
+
+### **Basic Queries**
+
+#### 1. Simple Transaction Query
+```graphql
+{
+ getTransaction(id: "123") {
+ id
+ asset
+ }
+}
+```
+
+#### 2. Minimal Query
+```graphql
+{
+ getTransaction(id: "test") {
+ id
+ }
+}
+```
+
+#### 3. Transaction with Selected Fields
+```graphql
+{
+ getTransaction(id: "txn_001") {
+ id
+ operation
+ amount
+ asset
+ }
+}
+```
+
+### **Complete Queries**
+
+#### 4. Full Transaction Details
+```graphql
+{
+ getTransaction(id: "abc123") {
+ id
+ version
+ amount
+ uri
+ type
+ publicKey
+ signerPublicKey
+ operation
+ metadata
+ asset
+ }
+}
+```
+
+#### 5. Named Query
+```graphql
+query GetTransaction {
+ getTransaction(id: "test123") {
+ id
+ asset
+ amount
+ }
+}
+```
+
+#### 6. Query with Aliases
+```graphql
+query GetTransactionDetails {
+ transaction: getTransaction(id: "alias_test") {
+ transactionId: id
+ transactionType: type
+ transactionOperation: operation
+ transactionAmount: amount
+ assetData: asset
+ }
+}
+```
+
+### **Mutation Examples**
+
+#### 7. Create Transaction Mutation
+```graphql
+mutation CreateAsset {
+ postTransaction(
+ data: {
+ operation: "CREATE"
+ amount: 100
+ signerPublicKey: "public_key_string"
+ signerPrivateKey: "private_key_string"
+ recipientPublicKey: "recipient_public_key"
+ asset: {
+ "data": {
+ "name": "My Asset",
+ "description": "Asset description"
+ }
+ }
+ }
+ ) {
+ id
+ }
+}
+```
+
+#### 8. Simple Mutation
+```graphql
+mutation {
+ postTransaction(
+ data: {
+ operation: "CREATE"
+ amount: 1
+ signerPublicKey: "key1"
+ signerPrivateKey: "key2"
+ recipientPublicKey: "key3"
+ asset: { "data": { "test": "value" } }
+ }
+ ) {
+ id
+ }
+}
+```
+
+---
+
+## โ Question-Based Prompts (For RAG)
+
+### **GraphQL Basics**
+
+1. **What is GraphQL?**
+2. **How do I write a GraphQL query?**
+3. **What is the difference between query and mutation?**
+4. **How do I use variables in GraphQL queries?**
+5. **What are GraphQL fragments and how do I use them?**
+6. **How does GraphQL introspection work?**
+7. **What are GraphQL directives?**
+
+### **ResilientDB Specific**
+
+8. **What is ResilientDB?**
+9. **How do I retrieve a transaction by ID in GraphQL?**
+10. **What fields are available in the getTransaction query?**
+11. **How do I create a transaction using GraphQL?**
+12. **What is the PrepareAsset input type?**
+13. **What operations are available in ResilientDB?**
+14. **How do I transfer an asset using GraphQL?**
+
+### **Query Optimization**
+
+15. **How can I optimize my GraphQL queries for better performance?**
+16. **What fields should I select to improve query efficiency?**
+17. **How do I reduce the complexity of my GraphQL queries?**
+18. **What are best practices for writing GraphQL queries?**
+
+### **Advanced Topics**
+
+19. **How do I filter transactions in GraphQL?**
+20. **How does GraphQL pagination work?**
+21. **How do I handle errors in GraphQL queries?**
+22. **What is the JSONScalar type in GraphQL?**
+23. **How do I query nested data in GraphQL?**
+
+### **Schema Exploration**
+
+24. **What types and fields are available in the GraphQL schema?**
+25. **What mutations are available in the GraphQL schema?**
+26. **How do I explore the GraphQL schema?**
+27. **What is the structure of a RetrieveTransaction type?**
+
+---
+
+## ๐ฏ Recommended Testing Order
+
+### **Phase 1: Start Simple**
+1. Try **Query #1** (simple transaction query)
+2. Ask **Question #1**: "What is GraphQL?"
+3. Try **Query #2** (minimal query)
+4. Ask **Question #9**: "How do I retrieve a transaction by ID in GraphQL?"
+
+### **Phase 2: Intermediate**
+5. Try **Query #4** (full transaction details)
+6. Ask **Question #15**: "How can I optimize my GraphQL queries?"
+7. Try **Query #5** (named query)
+8. Ask **Question #11**: "How do I create a transaction using GraphQL?"
+
+### **Phase 3: Advanced**
+9. Try **Query #6** (aliases)
+10. Try **Mutation #7** (create transaction)
+11. Ask **Question #20**: "How does GraphQL pagination work?"
+12. Ask **Question #24**: "What types and fields are available in the GraphQL schema?"
+
+### **Phase 4: Edge Cases**
+13. Try **Query #3** (selected fields - test optimization suggestions)
+14. Ask **Question #22**: "What is the JSONScalar type in GraphQL?"
+15. Try **Mutation #8** (simple mutation)
+
+---
+
+## ๐ Quick Copy-Paste List
+
+### **Queries (Copy these into the query editor):**
+
+1. `{ getTransaction(id: "123") { id asset } }`
+2. `{ getTransaction(id: "test") { id } }`
+3. `{ getTransaction(id: "txn_001") { id operation amount asset } }`
+4. `{ getTransaction(id: "abc123") { id version amount uri type publicKey signerPublicKey operation metadata asset } }`
+5. `query GetTransaction { getTransaction(id: "test123") { id asset amount } }`
+6. `query GetTransactionDetails { transaction: getTransaction(id: "alias_test") { transactionId: id transactionType: type transactionOperation: operation transactionAmount: amount assetData: asset } }`
+7. `mutation CreateAsset { postTransaction(data: { operation: "CREATE" amount: 100 signerPublicKey: "key1" signerPrivateKey: "key2" recipientPublicKey: "key3" asset: { "data": { "name": "Test" } } }) { id } }`
+
+### **Questions (Copy these into the query editor):**
+
+1. What is GraphQL?
+2. How do I write a GraphQL query?
+3. What is the difference between query and mutation?
+4. How do I retrieve a transaction by ID in GraphQL?
+5. How do I create a transaction using GraphQL?
+6. How can I optimize my GraphQL queries for better performance?
+7. What fields are available in the getTransaction query?
+8. What is ResilientDB?
+9. How does GraphQL pagination work?
+10. What is the JSONScalar type in GraphQL?
+
+---
+
+## ๐ก What to Check
+
+### **For GraphQL Queries:**
+- โ
**Explanation Tab:** Should explain what the query does, its purpose, and how it works
+- โ
**Optimization Tab:** Should provide suggestions for improving the query (field selection, complexity reduction, etc.)
+- โ
**Efficiency Tab:** Should show:
+ - Efficiency Score (0-100)
+ - Estimated Execution Time
+ - Resource Usage (CPU, Memory, Network)
+ - Complexity Level (Low/Medium/High)
+
+### **For Questions:**
+- โ
**Explanation Tab:** Should provide a clear, comprehensive answer using RAG-retrieved documentation
+- โ
**Documentation References:** Should cite relevant GraphQL/ResilientDB documentation
+- โ
**Examples:** Should include code examples when relevant
+- โ
**Completeness:** Should fully answer the question
+
+---
+
+## ๐ Expected Results
+
+### **Simple Queries (1, 2, 3):**
+- **Complexity:** Low
+- **Efficiency Score:** 90-100
+- **Optimization Suggestions:** May suggest removing unused fields or using field aliases
+
+### **Complete Queries (4):**
+- **Complexity:** Medium/High
+- **Efficiency Score:** 70-90
+- **Optimization Suggestions:** Should suggest selecting only needed fields
+
+### **Mutations (7, 8):**
+- **Complexity:** Medium
+- **Efficiency Score:** 80-95
+- **Optimization Suggestions:** May suggest validating input data or optimizing asset structure
+
+### **Questions:**
+- Should retrieve 3-5 relevant documentation chunks
+- Should provide comprehensive, well-structured answers
+- Should include examples when helpful
+- Should reference ResilientDB/GraphQL documentation
+
+---
+
+## ๐ Pro Tips
+
+1. **Mix Queries and Questions:** Alternate between actual GraphQL queries and natural language questions
+2. **Check All Tabs:** Review Explanation, Optimization, and Efficiency tabs for each input
+3. **Compare Similar Queries:** Try variations of the same query to see how suggestions differ
+4. **Test Edge Cases:** Try invalid queries or very complex queries to see error handling
+5. **Verify Documentation:** Ensure explanations reference the correct documentation chunks
+
+---
+
+**Happy Testing! ๐**
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/SETUP_NEXUS_FORK.md b/ecosystem/ai-tools/mcp/graphq-llm/SETUP_NEXUS_FORK.md
new file mode 100644
index 00000000..ec59349c
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/SETUP_NEXUS_FORK.md
@@ -0,0 +1,205 @@
+# Setting Up Your Nexus Fork - Quick Guide
+
+## Current Status โ
+
+You already have:
+- โ
Separate `nexus` repository at `/Users/sophiequynn/nexus`
+- โ
GraphQ-LLM integration files added
+- โ
Modified files ready to commit
+
+**Current remote:** `https://github.com/ResilientApp/nexus.git` (original)
+
+**What you need to do:** Fork on GitHub, change remote, commit & push
+
+---
+
+## Step 1: Fork Nexus on GitHub
+
+1. Go to: https://github.com/ResilientApp/nexus
+2. Click **"Fork"** button (top-right)
+3. Select your GitHub account
+4. Wait for fork to complete
+5. **Copy your fork URL** - it will be:
+ ```
+ https://github.com/YOUR_USERNAME/nexus.git
+ ```
+
+---
+
+## Step 2: Update Remote to Your Fork
+
+```bash
+cd /Users/sophiequynn/nexus
+
+# Add your fork as a new remote (or rename origin)
+git remote rename origin upstream
+git remote add origin https://github.com/YOUR_USERNAME/nexus.git
+
+# Verify remotes
+git remote -v
+```
+
+**Expected output:**
+```
+origin https://github.com/YOUR_USERNAME/nexus.git (fetch)
+origin https://github.com/YOUR_USERNAME/nexus.git (push)
+upstream https://github.com/ResilientApp/nexus.git (fetch)
+upstream https://github.com/ResilientApp/nexus.git (push)
+```
+
+---
+
+## Step 3: Commit Your Changes
+
+```bash
+cd /Users/sophiequynn/nexus
+
+# Stage all changes
+git add .
+
+# Check what will be committed
+git status
+
+# Commit with descriptive message
+git commit -m "Add GraphQ-LLM integration: GraphQL Tutor UI and API routes
+
+- Add GraphQL Tutor UI page and components
+- Add API route for query analysis
+- Update main page navigation
+- Add required dependencies
+- Add UI components (progress bar)"
+```
+
+---
+
+## Step 4: Push to Your Fork
+
+```bash
+cd /Users/sophiequynn/nexus
+
+# Push to your fork
+git push -u origin main
+
+# If you get an error about upstream, use:
+# git push -u origin main --force
+# (Only use --force if you're sure you want to overwrite your fork)
+```
+
+---
+
+## Step 5: Update TEAM_SETUP.md
+
+Update the Nexus URL in `graphq-llm/TEAM_SETUP.md`:
+
+1. Find this section (around line 14-17):
+ ```markdown
+ 2. **Nexus** (separate repository - must be cloned)
+ - **URL:** https://github.com/ResilientApp/nexus.git
+ - **Purpose:** Next.js frontend application
+ - **Note:** Requires modifications (see Step 7.6)
+ ```
+
+2. Replace with:
+ ```markdown
+ 2. **Nexus** (separate repository - must be cloned)
+ - **URL:** https://github.com/YOUR_USERNAME/nexus.git
+ - **Purpose:** Next.js frontend application
+ - **Note:** This fork includes GraphQ-LLM integration (see Step 7.6 for details)
+ ```
+
+3. Also update Step 7.1 (around line 637):
+ ```markdown
+ git clone https://github.com/YOUR_USERNAME/nexus.git
+ ```
+
+---
+
+## Step 6: Commit TEAM_SETUP.md Update
+
+```bash
+cd /Users/sophiequynn/graphq-llm
+
+# Update TEAM_SETUP.md with your fork URL
+# (Do this manually or use the script below)
+
+# Commit and push
+git add TEAM_SETUP.md
+git commit -m "Update TEAM_SETUP.md to reference forked Nexus repository"
+git push
+```
+
+---
+
+## Quick Script (All Steps Combined)
+
+Save this as a script and run it (replace `YOUR_USERNAME`):
+
+```bash
+#!/bin/bash
+
+# Configuration
+GITHUB_USERNAME="YOUR_USERNAME" # Change this!
+NEXUS_DIR="/Users/sophiequynn/nexus"
+GRAPHQ_LLM_DIR="/Users/sophiequynn/graphq-llm"
+
+echo "๐ง Setting up Nexus fork..."
+
+cd "$NEXUS_DIR"
+
+# Step 1: Update remotes
+echo "๐ก Updating git remotes..."
+git remote rename origin upstream 2>/dev/null || echo "Remote already renamed or doesn't exist"
+git remote add origin "https://github.com/${GITHUB_USERNAME}/nexus.git" 2>/dev/null || git remote set-url origin "https://github.com/${GITHUB_USERNAME}/nexus.git"
+git remote -v
+
+# Step 2: Commit changes
+echo "๐ Committing GraphQ-LLM integration..."
+git add .
+git commit -m "Add GraphQ-LLM integration: GraphQL Tutor UI and API routes" || echo "No changes to commit or already committed"
+
+# Step 3: Push to fork
+echo "๐ Pushing to fork..."
+git push -u origin main || echo "Push failed - check if fork exists on GitHub"
+
+echo ""
+echo "โ
Nexus fork setup complete!"
+echo ""
+echo "Next steps:"
+echo "1. Verify fork at: https://github.com/${GITHUB_USERNAME}/nexus"
+echo "2. Update TEAM_SETUP.md with your fork URL"
+echo "3. Commit TEAM_SETUP.md update to graphq-llm repo"
+```
+
+---
+
+## Verification Checklist
+
+After completing all steps:
+
+- [ ] Fork exists at `https://github.com/YOUR_USERNAME/nexus`
+- [ ] All GraphQ-LLM files are in the fork
+- [ ] Changes are pushed to your fork
+- [ ] `git remote -v` shows your fork as `origin`
+- [ ] TEAM_SETUP.md references your fork URL
+- [ ] TEAM_SETUP.md changes are committed to graphq-llm
+
+---
+
+## Future Updates
+
+To pull updates from the original Nexus repository:
+
+```bash
+cd /Users/sophiequynn/nexus
+
+# Fetch updates from original repo
+git fetch upstream
+
+# Merge updates
+git merge upstream/main
+
+# Push to your fork
+git push origin main
+```
+
+This keeps your fork up-to-date while preserving your GraphQ-LLM integration.
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/SETUP_RESLENS_FORK.md b/ecosystem/ai-tools/mcp/graphq-llm/SETUP_RESLENS_FORK.md
new file mode 100644
index 00000000..3c12708b
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/SETUP_RESLENS_FORK.md
@@ -0,0 +1,206 @@
+# Setting Up Your ResLens Forks
+
+## Overview
+
+ResLens consists of two separate repositories that should be forked and maintained separately:
+1. **ResLens Frontend** - React/Vite dashboard UI
+2. **ResLens Middleware** - Node.js Express API server
+
+This guide will help you set up forks of both repositories, similar to how Nexus was set up.
+
+---
+
+## Step 1: Fork ResLens Repositories on GitHub
+
+### 1.1: Fork ResLens Frontend
+
+1. Go to: https://github.com/Bismanpal-Singh/MemLens
+2. Click the **"Fork"** button (top-right)
+3. Select your GitHub account
+4. Wait for fork to complete
+5. **Copy your fork URL** - it will be:
+ ```
+ https://github.com/YOUR_USERNAME/MemLens.git
+ ```
+
+### 1.2: Fork ResLens Middleware
+
+1. Go to: https://github.com/harish876/MemLens-middleware
+2. Click the **"Fork"** button (top-right)
+3. Select your GitHub account
+4. Wait for fork to complete
+5. **Copy your fork URL** - it will be:
+ ```
+ https://github.com/YOUR_USERNAME/MemLens-middleware.git
+ ```
+
+---
+
+## Step 2: Clone Your Forks (Separate from graphq-llm)
+
+```bash
+# Navigate to your workspace (outside graphq-llm)
+cd /Users/sophiequynn
+
+# Clone ResLens Frontend fork
+git clone https://github.com/YOUR_USERNAME/MemLens.git ResLens
+cd ResLens
+
+# Add the original repository as upstream
+git remote add upstream https://github.com/Bismanpal-Singh/MemLens.git
+
+# Verify remotes
+git remote -v
+
+# Go back and clone ResLens Middleware fork
+cd ..
+git clone https://github.com/YOUR_USERNAME/MemLens-middleware.git ResLens-Middleware
+cd ResLens-Middleware
+
+# Add the original repository as upstream
+git remote add upstream https://github.com/harish876/MemLens-middleware.git
+
+# Verify remotes
+git remote -v
+```
+
+---
+
+## Step 3: Update Docker Compose Configuration
+
+Update `docker-compose.dev.yml` to use your forks. You have two options:
+
+### Option A: Update Paths Directly
+
+Change the build contexts to point to your forks:
+
+```yaml
+reslens-middleware:
+ build:
+ context: /Users/YOUR_USERNAME/ResLens-Middleware/middleware
+ dockerfile: Dockerfile
+
+reslens-frontend:
+ build:
+ context: /Users/YOUR_USERNAME/ResLens
+ dockerfile: Dockerfile
+```
+
+### Option B: Use Environment Variables (Recommended)
+
+Update `docker-compose.dev.yml` to use environment variables for paths:
+
+```yaml
+reslens-middleware:
+ build:
+ context: ${RESLENS_MIDDLEWARE_PATH:-./ResLens-Middleware/middleware}
+
+reslens-frontend:
+ build:
+ context: ${RESLENS_FRONTEND_PATH:-./ResLens}
+```
+
+Then set in `.env`:
+```env
+RESLENS_MIDDLEWARE_PATH=/Users/YOUR_USERNAME/ResLens-Middleware/middleware
+RESLENS_FRONTEND_PATH=/Users/YOUR_USERNAME/ResLens
+```
+
+---
+
+## Step 4: Add ResLens Directories to .gitignore
+
+Add to `.gitignore`:
+
+```gitignore
+# External repositories (cloned locally for Docker builds)
+nexus/
+ResLens/
+ResLens-Middleware/
+```
+
+---
+
+## Step 5: Remove ResLens from Git Tracking
+
+```bash
+cd /Users/sophiequynn/graphq-llm
+
+# Remove from git tracking (keeps local files)
+git rm -r --cached ResLens ResLens-Middleware
+
+# Commit the change
+git add .gitignore
+git commit -m "Remove ResLens directories from git tracking (now using separate forks)"
+git push
+```
+
+---
+
+## Step 6: Update Documentation
+
+Update `TEAM_SETUP.md` to reference your forks:
+
+1. Add to Quick Reference section:
+ ```markdown
+ 4. **ResLens Frontend** (separate repository - optional)
+ - **URL:** https://github.com/YOUR_USERNAME/MemLens.git
+ - **Purpose:** Performance monitoring dashboard UI
+
+ 5. **ResLens Middleware** (separate repository - optional)
+ - **URL:** https://github.com/YOUR_USERNAME/MemLens-middleware.git
+ - **Purpose:** Performance monitoring API server
+ ```
+
+2. Update Step 5.2 in `TEAM_SETUP.md` to include clone instructions for your forks.
+
+---
+
+## Step 7: Verify Setup
+
+```bash
+# Check ResLens Frontend
+cd /Users/YOUR_USERNAME/ResLens
+git remote -v # Should show your fork as origin
+
+# Check ResLens Middleware
+cd /Users/YOUR_USERNAME/ResLens-Middleware
+git remote -v # Should show your fork as origin
+
+# Verify graphq-llm ignores ResLens
+cd /Users/YOUR_USERNAME/graphq-llm
+git status # Should not show ResLens directories
+```
+
+---
+
+## Future Updates
+
+To pull updates from the original repositories:
+
+```bash
+# ResLens Frontend
+cd /Users/YOUR_USERNAME/ResLens
+git fetch upstream
+git merge upstream/main
+git push origin main
+
+# ResLens Middleware
+cd /Users/YOUR_USERNAME/ResLens-Middleware
+git fetch upstream
+git merge upstream/main
+git push origin main
+```
+
+---
+
+## Summary
+
+After completing these steps:
+- โ
Both ResLens repositories are forked on GitHub
+- โ
Forks are cloned separately (outside graphq-llm)
+- โ
Docker Compose can build from fork paths
+- โ
ResLens directories are removed from graphq-llm git tracking
+- โ
Documentation references your forks
+- โ
You can pull upstream updates independently
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/TEAM_SETUP.md b/ecosystem/ai-tools/mcp/graphq-llm/TEAM_SETUP.md
new file mode 100644
index 00000000..92abd05f
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/TEAM_SETUP.md
@@ -0,0 +1,1279 @@
+# ๐ Complete Team Setup Guide - GraphQ-LLM with Nexus Integration
+
+**Purpose:** This guide will help you replicate the exact working setup from scratch. Follow each step in order to reach the current state of the project.
+
+---
+
+## ๐ Quick Reference - Repository Links
+
+### **Repositories to Clone:**
+1. **GraphQ-LLM** (this repository)
+ - Replace `<repository-url>` with your actual GraphQ-LLM repository URL
+ - Contains: Main application code, Docker configs, documentation
+
+2. **Nexus** (separate repository - must be cloned)
+ - **URL:** https://github.com/sophiequynn/nexus.git
+ - **Purpose:** Next.js frontend application
+ - **Note:** This fork includes GraphQ-LLM integration (see Step 7.6 for details.)
+
+3. **ResilientDB** (reference only - using Docker image)
+ - **URL:** https://github.com/apache/incubator-resilientdb
+ - **Note:** We use the Docker image `expolab/resdb`, not cloning the repo.
+
+4. **ResLens Frontend** (separate repository - optional)
+ - **URL:** https://github.com/sophiequynn/incubator-resilientdb-ResLens.git
+ - **Purpose:** Performance monitoring dashboard UI
+ - **Note:** Forked from Apache ResLens project
+
+5. **ResLens Middleware** (separate repository - optional)
+ - **URL:** https://github.com/sophiequynn/incubator-resilientdb-ResLens-Middleware.git
+ - **Purpose:** Performance monitoring API server
+ - **Note:** Forked from Apache ResLens project
+
+### **Key Documentation Files (in GraphQ-LLM repository):**
+- `NEXUS_UI_EXTENSION_GUIDE.md` - Complete code for Nexus integration (Step 7.6)
+- `TEST_QUERIES.md` - Example queries for testing
+- `FINAL_PHASES_AND_STEPS.md` - Project status and progress
+- `WHY_INTEGRATE_RESLENS_NEXUS.md` - Integration rationale
+- `TEST_DOCKER_SERVICES.md` - Comprehensive testing guide for all Docker services
+
+---
+
+## ๐ Prerequisites Checklist
+
+Before starting, ensure you have:
+
+- [ ] **Docker** and **Docker Compose** installed
+- [ ] **Git** installed
+- [ ] **Node.js 18+** installed (for local development)
+- [ ] **PostgreSQL** with pgvector (we'll set this up with Docker)
+
+---
+
+## ๐ Required API Keys
+
+Before starting, gather these API keys (some are optional but recommended):
+
+### **Required:**
+- **Gemini API Key** (for LLM - currently using `gemini-2.5-flash-lite`)
+ - Get it from: https://makersuite.google.com/app/apikey
+ - Create a new API key and copy it
+
+### **Optional but Recommended:**
+- **Hugging Face API Key** (for faster model downloads)
+ - Get it from: https://huggingface.co/settings/tokens
+ - Create a new token with read access
+
+### **Optional (for Nexus features):**
+- **DeepSeek API Key** - https://www.deepseek.com/ โ Sign up โ Get API key
+- **LlamaCloud API Key** - https://cloud.llamaindex.ai/ โ Sign up โ Get API key
+- **Supabase** (if using cloud PostgreSQL) - https://supabase.com โ Create project
+
+---
+
+## ๐ฏ Step-by-Step Setup (Follow in Order)
+
+### **Step 1: Clone GraphQ-LLM Repository**
+
+```bash
+# Clone the GraphQ-LLM repository
+# Replace <repository-url> with your actual repository URL
+git clone <repository-url>
+cd graphq-llm
+```
+
+**Repository:** Replace `<repository-url>` with your GraphQ-LLM repository URL.
+
+**Verify:** You should see files like `package.json`, `src/`, `docs/`, `docker-compose.dev.yml`, etc.
+
+---
+
+### **Step 2: Install Dependencies**
+
+```bash
+# Install all Node.js dependencies
+npm install
+```
+
+**Expected output:** All packages will be installed, including:
+- `@xenova/transformers` (for local LLM and embeddings)
+- `@huggingface/inference` (for Hugging Face API)
+- `@modelcontextprotocol/sdk` (for MCP server)
+- All other dependencies
+
+**Time:** 2-5 minutes
+
+---
+
+### **Step 3: Create Environment File**
+
+Create a `.env` file in the `graphq-llm` directory:
+
+```bash
+cd /path/to/graphq-llm
+touch .env
+```
+
+Copy this exact configuration into `.env`:
+
+```env
+# GraphQ-LLM Environment Variables
+
+# ResilientDB Configuration
+# For local development (ResilientDB running on host):
+RESILIENTDB_GRAPHQL_URL=http://localhost:5001/graphql
+# For Docker (ResilientDB in container):
+# RESILIENTDB_GRAPHQL_URL=http://resilientdb:5001/graphql
+# Note: GraphQL server runs on port 5001 (KV service is on port 18000)
+
+# Nexus Configuration
+NEXUS_API_URL=http://localhost:3000
+NEXUS_API_KEY=
+
+# ResLens Configuration (Live Mode - optional)
+RESLENS_LIVE_MODE=false
+RESLENS_POLL_INTERVAL=5000
+
+# HTTP API Server Configuration (for GraphQ-LLM Backend)
+# This is the HTTP API server that Nexus connects to (not the MCP server)
+MCP_SERVER_PORT=3001
+MCP_SERVER_HOST=localhost
+# Note: MCP_SERVER_PORT is used by the HTTP API backend service
+# The MCP server itself uses stdio transport and runs as a separate service
+
+# LLM Configuration
+# Using Gemini (recommended) or local LLM
+LLM_PROVIDER=gemini
+LLM_API_KEY=your_gemini_api_key_here
+LLM_MODEL=gemini-2.5-flash-lite
+LLM_ENABLE_LIVE_STATS=false
+
+# Alternative: Using local LLM (no API key needed, but lower quality)
+# LLM_PROVIDER=local
+# LLM_API_KEY=
+# LLM_MODEL=Xenova/gpt2
+
+# Embedding Configuration
+# Using local embeddings (Xenova/all-MiniLM-L6-v2) - no API key needed
+EMBEDDINGS_PROVIDER=local
+# Optional: Hugging Face API key for faster model downloads
+HUGGINGFACE_API_KEY=your_huggingface_key_here
+
+# Logging
+LOG_LEVEL=info
+```
+
+**Important:**
+- Replace `your_gemini_api_key_here` with your actual Gemini API key (required for LLM)
+- Replace `your_huggingface_key_here` with your actual Hugging Face API key (optional but recommended for faster model downloads)
+
+---
+
+### **Step 4: Set Up ResilientDB and GraphQL Server**
+
+**What is the GraphQL Server?**
+- ResilientDB has two services:
+ 1. **KV Service** (port 18000) - Key-value storage
+ 2. **GraphQL Server** (port 5001) - GraphQL API for querying/storing data
+- The GraphQL server is **required** for storing and retrieving document chunks
+- It's a Python Flask application that provides GraphQL mutations and queries
+
+**โ ๏ธ Important:** You do NOT need to clone the separate GraphQL repository (`https://github.com/apache/incubator-resilientdb-graphql`). The GraphQL server code is already included in the ResilientDB Docker image (`expolab/resdb`), and the `setup-graphql.sh` script automatically sets it up. The separate repository is only for reference or manual setup outside Docker.
+
+#### **Option A: Using Docker (Recommended)**
+
+```bash
+# Start ResilientDB using Docker Compose
+docker-compose -f docker-compose.dev.yml up -d resilientdb
+
+# Wait for ResilientDB to be healthy (60-120 seconds)
+# The setup-graphql.sh script runs automatically in the container
+# Check status
+docker-compose -f docker-compose.dev.yml ps
+
+# Verify ResilientDB KV service is running
+curl http://localhost:18000/v1/transactions/test
+
+# Verify GraphQL server is running (IMPORTANT - this must work!)
+curl -X POST http://localhost:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+```
+
+**Expected:**
+- KV service should return a response (may be an error, but connection works)
+- GraphQL server should return `{"data":{"__typename":"Query"}}` or similar
+
+**If GraphQL server is not running:**
+```bash
+# Check container logs
+docker-compose -f docker-compose.dev.yml logs resilientdb
+
+# The setup-graphql.sh script should run automatically
+# If it fails, you may need to set up ResilientDB manually (see Option B)
+```
+
+#### **Option B: Manual Setup (If Docker doesn't work)**
+
+If Docker setup fails or you want to set up manually:
+
+1. **Set up ResilientDB KV Service:**
+ - Follow ResilientDB documentation: https://github.com/apache/incubator-resilientdb
+ - Ensure KV service is running on port 18000
+
+2. **Set up GraphQL Server:**
+
+ **Option B.1: Using ResilientDB Main Repository (Recommended)**
+ ```bash
+ # Clone ResilientDB main repository
+ git clone https://github.com/apache/incubator-resilientdb.git
+ cd incubator-resilientdb/ecosystem/graphql
+
+ # Copy setup-graphql.sh from graphq-llm repository
+ # Or manually install dependencies:
+ pip install flask flask-cors ariadne base58 cryptography pysha3 \
+ cryptoconditions python-rapidjson strawberry-graphql
+
+ # Fix the tx_Dict typo (if present)
+ sed -i 's/tx_Dict/tx_dict/g' resdb_driver/transaction.py
+
+ # Start the GraphQL server
+ python3 app.py
+ # Server should start on port 5001
+ ```
+
+ **Option B.2: Using Standalone GraphQL Repository (Alternative)**
+ ```bash
+ # Clone the standalone GraphQL repository
+ git clone https://github.com/apache/incubator-resilientdb-graphql.git
+ cd incubator-resilientdb-graphql
+
+ # Follow the repository's README for setup
+ # Install dependencies as per repository instructions
+ # Start the server
+ python3 app.py
+ ```
+
+ **Note:** The standalone repository (Option B.2) is a separate implementation. The main ResilientDB repository (Option B.1) is recommended as it matches what's in the Docker image.
+
+3. **Verify GraphQL Server:**
+ ```bash
+ curl -X POST http://localhost:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+ ```
+
+4. **Update `.env`** to point to your ResilientDB:
+ ```env
+ RESILIENTDB_GRAPHQL_URL=http://localhost:5001/graphql
+ ```
+
+#### **Option C: Use Existing ResilientDB**
+
+If you already have ResilientDB with GraphQL server running:
+
+1. **Comment out the `resilientdb` service** in `docker-compose.dev.yml`
+2. **Update `.env`** to point to your existing ResilientDB:
+ ```env
+ RESILIENTDB_GRAPHQL_URL=http://localhost:5001/graphql
+ ```
+3. **Verify GraphQL server is accessible:**
+ ```bash
+ curl -X POST http://localhost:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+ ```
+
+---
+
+### **Step 5: Start GraphQ-LLM Backend (HTTP API Server)**
+
+The GraphQ-LLM backend runs as an HTTP API server that provides REST endpoints for Nexus integration. It runs separately from the MCP server.
+
+#### **Option A: Using Docker (Recommended)**
+
+```bash
+# Start the HTTP API backend service
+docker-compose -f docker-compose.dev.yml up -d graphq-llm-backend
+
+# Check logs (wait for "Server listening" message)
+docker-compose -f docker-compose.dev.yml logs -f graphq-llm-backend
+
+# In another terminal, verify backend is running
+curl http://localhost:3001/health
+```
+
+**Expected response:**
+```json
+{"status":"ok","service":"graphq-llm-api"}
+```
+
+**Note:**
+- First startup takes 30-60 seconds as it downloads the local LLM model (`Xenova/gpt2`)
+- This service runs the HTTP API on port 3001 for Nexus integration
+- The MCP server is a separate service (see Step 5.1)
+
+#### **Option B: Using Local Node.js**
+
+```bash
+# Set environment variables
+export LLM_PROVIDER=local
+export LLM_MODEL=Xenova/gpt2
+export EMBEDDINGS_PROVIDER=local
+export HUGGINGFACE_API_KEY=your_key_here # Optional
+
+# Start HTTP API server
+npm run http-api
+```
+
+The server will start on port 3001. Check logs for "Server listening" message.
+
+---
+
+### **Step 5.1: Start MCP Server (Optional - for MCP Client Integration)**
+
+The MCP (Model Context Protocol) Server provides secure two-way communication between ResilientDB and AI tools. It uses stdio transport for communication with MCP clients and runs as a **separate Docker service** from the HTTP API backend.
+
+**Important:** The MCP server and HTTP API backend are now separate services:
+- **HTTP API Backend** (Step 5): Runs on port 3001, provides REST endpoints for Nexus
+- **MCP Server** (Step 5.1): Uses stdio transport, runs as a separate container for MCP client integration
+
+#### **Option A: Using Docker (Recommended)**
+
+```bash
+# Start the MCP server service (separate from HTTP API backend)
+docker-compose -f docker-compose.dev.yml up -d graphq-llm-mcp-server
+
+# Check logs
+docker-compose -f docker-compose.dev.yml logs -f graphq-llm-mcp-server
+
+# Check status of all services
+docker-compose -f docker-compose.dev.yml ps
+```
+
+**Expected output:**
+```
+MCP Server started and listening on stdio
+Live Stats Service: Enabled/Disabled
+```
+
+**Note:**
+- The MCP server uses stdio transport (stdin/stdout), so it doesn't expose HTTP ports
+- It's designed to be spawned as a subprocess by MCP clients
+- The container keeps stdin/stdout open for communication
+- It shares the same environment variables as the backend service
+- Both services can run simultaneously (they're independent)
+
+#### **Option B: Using Local Node.js**
+
+```bash
+# Set environment variables (same as backend)
+export RESILIENTDB_GRAPHQL_URL=http://localhost:5001/graphql
+export LLM_PROVIDER=deepseek
+export LLM_API_KEY=your_key_here
+
+# Start MCP server
+npm run mcp-server
+```
+
+**Note:** MCP servers using stdio transport are typically invoked by MCP clients as child processes. Running it standalone allows you to test it directly. In Docker, it runs as a separate container that can be started/stopped independently.
+
+---
+
+### **Step 5.2: Start ResLens Services (Optional - for Performance Monitoring)**
+
+ResLens provides real-time performance monitoring and profiling for ResilientDB, including CPU and memory metrics, flame graphs, and call stack analysis. Both ResLens Middleware and Frontend are now dockerized and can be started with Docker Compose.
+
+**Important:** ResLens repositories must be cloned separately as forks (see Quick Reference section above). The Docker Compose configuration uses absolute paths to your fork directories.
+
+**Fork URLs:**
+- Frontend: https://github.com/sophiequynn/incubator-resilientdb-ResLens.git
+- Middleware: https://github.com/sophiequynn/incubator-resilientdb-ResLens-Middleware.git
+
+**Fork Modifications:** The forks include GraphQ-LLM-specific modifications:
+- **ResLens Frontend:** Dockerfile (multi-stage build), updated package.json (name, dependencies), additional routes (CpuPage, MemoryPage, QueryStats), updated components
+- **ResLens Middleware:** Dockerfile updates, queryStats routes and controller, improved .dockerignore
+
+**What is ResLens?**
+- **ResLens Middleware**: Node.js Express API server that aggregates performance data from ResilientDB
+- **ResLens Frontend**: React/Vite web application for visualizing performance metrics
+- **Purpose**: Monitor and optimize ResilientDB performance with real-time metrics
+
+**Architecture:**
+- **ResLens Middleware** (`ResLens-Middleware/middleware/Dockerfile`):
+ - Single-stage production build using Node.js 18 Alpine
+ - Production dependencies only
+ - Go installed for pprof tool (if needed)
+ - Health check endpoint on port 3003
+- **ResLens Frontend** (`ResLens/Dockerfile`):
+ - Multi-stage build: Node.js 20 Alpine โ Build Vite app โ Nginx Alpine
+ - Static files served via Nginx with SPA routing
+ - Gzip compression and static asset caching enabled
+ - Container port 80 mapped to host port 5173
+
+#### **Option A: Using Docker (Recommended)**
+
+**Prerequisites:**
+1. Clone the ResLens forks (see Quick Reference section above):
+ ```bash
+ # Clone ResLens Frontend fork
+ cd /path/to/workspace
+ git clone https://github.com/sophiequynn/incubator-resilientdb-ResLens.git ResLens
+
+ # Clone ResLens Middleware fork
+ git clone https://github.com/sophiequynn/incubator-resilientdb-ResLens-Middleware.git ResLens-Middleware
+ ```
+
+2. Update `docker-compose.dev.yml` paths if your forks are in a different location (default: `/Users/YOUR_USERNAME/ResLens` and `/Users/YOUR_USERNAME/ResLens-Middleware`).
+
+**Note:** The forks include all GraphQ-LLM modifications - no additional setup needed!
+
+```bash
+# Start ResLens Middleware (required for Frontend)
+docker-compose -f docker-compose.dev.yml up -d reslens-middleware
+
+# Wait for middleware to be healthy (30-60 seconds)
+sleep 30
+
+# Start ResLens Frontend (depends on Middleware)
+docker-compose -f docker-compose.dev.yml up -d reslens-frontend
+
+# Check status of all services
+docker-compose -f docker-compose.dev.yml ps
+
+# Check logs
+docker-compose -f docker-compose.dev.yml logs -f reslens-middleware reslens-frontend
+```
+
+**Expected output:**
+- ResLens Middleware: Running on port 3003
+- ResLens Frontend: Running on port 5173 (mapped from container port 80)
+
+**Verify ResLens is running:**
+```bash
+# Test Middleware health endpoint
+curl http://localhost:3003/api/v1/healthcheck
+
+# Test Frontend (should return HTML)
+curl http://localhost:5173
+
+# Check service status
+docker-compose -f docker-compose.dev.yml ps reslens-middleware reslens-frontend
+```
+
+**Expected responses:**
+- Middleware: `{"status":"UP"}` or similar JSON response
+- Frontend: HTML page content (should start with `<!DOCTYPE html>`)
+
+**Access ResLens UI:**
+- Open browser: `http://localhost:5173`
+- You should see the ResLens dashboard for performance monitoring
+
+#### **Option B: Build Images First (If Needed)**
+
+If the images don't exist yet, build them:
+
+```bash
+# Build ResLens Middleware image
+docker-compose -f docker-compose.dev.yml build reslens-middleware
+
+# Build ResLens Frontend image
+docker-compose -f docker-compose.dev.yml build reslens-frontend
+
+# Then start services (Option A above)
+docker-compose -f docker-compose.dev.yml up -d reslens-middleware reslens-frontend
+```
+
+**Note:**
+- First build may take 5-10 minutes as it installs dependencies
+- ResLens Frontend depends on ResLens Middleware - start middleware first
+- ResLens Middleware depends on ResilientDB - ensure ResilientDB is running (Step 4)
+- ResLens services are optional but recommended for performance monitoring
+
+#### **Configuration**
+
+ResLens services use these default configurations in `docker-compose.dev.yml`:
+
+- **ResLens Middleware:**
+ - Port: `3003`
+ - Connects to: `http://resilientdb:18000` (ResilientDB KV service)
+ - Health check: `http://localhost:3003/api/v1/healthcheck`
+
+ **Runtime Environment Variables** (can be set in docker-compose):
+ - `PORT`: Server port (default: 3003)
+ - `CPP_STATS_API_BASE_URL`: ResilientDB stats API (default: `http://resilientdb:18000`)
+ - `CPP_TRANSACTIONS_API_BASE_URL`: ResilientDB transactions API (default: `http://resilientdb:18000`)
+ - `PYROSCOPE_SERVER_URL`: Pyroscope server URL (optional)
+ - `PROMETHEUS_URL`: Prometheus server URL (optional)
+ - `NODE_EXPORTER_BASE_URL`: Node exporter URL (optional)
+ - `PROCESS_EXPORTER_BASE_URL`: Process exporter URL (optional)
+ - `EXPLORER_BASE_URL`: Explorer API URL (optional)
+
+- **ResLens Frontend:**
+ - Port: `5173` (host) โ `80` (container)
+ - Connects to: `http://reslens-middleware:3003/api/v1` (Middleware API)
+ - Health check: `http://localhost:5173`
+
+ **Build-time Environment Variables** (set during `docker build`):
+ - `VITE_MIDDLEWARE_BASE_URL`: URL to middleware API (default: `http://reslens-middleware:3003/api/v1`)
+ - `VITE_MIDDLEWARE_SECONDARY_BASE_URL`: Secondary middleware URL (optional)
+
+**Networking:**
+Both services are on the `graphq-llm-network` Docker network, allowing them to communicate with:
+- ResilientDB (via service name `resilientdb`)
+- GraphQ-LLM Backend (via service name `graphq-llm-backend`)
+- Each other (via service names `reslens-middleware` and `reslens-frontend`)
+
+**To customize:** Edit `docker-compose.dev.yml` environment variables for ResLens services.
+
+#### **Troubleshooting ResLens**
+
+**Issue: ResLens Middleware not starting**
+```bash
+# Check logs
+docker-compose -f docker-compose.dev.yml logs reslens-middleware
+
+# Verify ResilientDB is running
+docker-compose -f docker-compose.dev.yml ps resilientdb
+
+# Check if port 3003 is in use
+lsof -i:3003
+```
+
+**Issue: ResLens Frontend can't connect to Middleware**
+```bash
+# Verify middleware is running
+curl http://localhost:3003/api/v1/healthcheck
+
+# Check network connectivity
+docker-compose -f docker-compose.dev.yml exec reslens-frontend wget -O- http://reslens-middleware:3003/api/v1/healthcheck
+
+# Check middleware logs
+docker-compose -f docker-compose.dev.yml logs reslens-middleware
+```
+
+**Issue: Port conflicts (3003 or 5173 already in use)**
+```bash
+# Find process using port
+lsof -i:3003
+lsof -i:5173
+
+# Option 1: Kill the process
+kill -9 <PID>
+
+# Option 2: Change ports in docker-compose.dev.yml
+# Edit ports section:
+# ports:
+# - "3004:3003" # Change host port
+# - "5174:80" # Change host port
+```
+
+**Issue: Build failures**
+```bash
+# Clear build cache and rebuild
+docker-compose -f docker-compose.dev.yml build --no-cache reslens-middleware reslens-frontend
+
+# Check if package-lock.json exists (required for npm ci)
+ls ResLens-Middleware/middleware/package-lock.json
+ls ResLens/package-lock.json
+
+# If missing, generate them (run from project root)
+cd ResLens-Middleware/middleware && npm install && cd ../..
+cd ResLens && npm install && cd ..
+```
+
+#### **Viewing Logs and Managing Services**
+
+```bash
+# View logs for both services
+docker-compose -f docker-compose.dev.yml logs -f reslens-middleware reslens-frontend
+
+# View logs for individual services
+docker-compose -f docker-compose.dev.yml logs -f reslens-middleware
+docker-compose -f docker-compose.dev.yml logs -f reslens-frontend
+
+# Stop services
+docker-compose -f docker-compose.dev.yml stop reslens-middleware reslens-frontend
+
+# Remove services (keeps images)
+docker-compose -f docker-compose.dev.yml rm reslens-middleware reslens-frontend
+
+# Remove services and images
+docker-compose -f docker-compose.dev.yml down reslens-middleware reslens-frontend
+```
+
+#### **Development vs Production**
+
+**Development (Local):**
+- Run services locally with `npm run dev` / `npm start` in the respective directories
+- Hot reload enabled
+- Easier debugging with direct file access
+
+**Production (Docker):**
+- Optimized builds
+- Static file serving via Nginx for Frontend
+- Production dependencies only
+- Health checks enabled
+- Better resource management
+
+---
+
+### **Step 6: Ingest Documentation (REQUIRED)**
+
+**โ ๏ธ IMPORTANT:** Each teammate must run this on their own setup! This stores docs in your local ResilientDB.
+
+```bash
+# If using Docker
+docker-compose -f docker-compose.dev.yml exec graphq-llm-backend npm run ingest:graphql
+
+# If using local Node.js
+npm run ingest:graphql
+```
+
+**What this does:**
+- Loads all GraphQL documentation from `docs/` directory
+- Chunks documents into smaller pieces
+- Generates embeddings (using local model or Hugging Face)
+- Stores chunks in ResilientDB
+
+**Expected output:**
+```
+๐ GraphQL-only Ingestion
+โ
Loaded X docs from docs/graphql-official
+โ
Loaded X docs from docs/graphql-spec
+โ
Loaded X docs from docs/community-guides
+๐ Ingesting X GraphQL-specific documents...
+๐ Progress: 100/100 chunks (100%)
+โ
GraphQL ingestion complete!
+Documents processed: X/X
+Chunks stored: X
+```
+
+**Time:** 5-10 minutes (depending on system and embedding provider)
+
+**Verify:** Check logs for "Chunks stored: X" (should be 100+ chunks).
+
+---
+
+### **Step 7: Set Up Nexus (Separate Repository)**
+
+Nexus is a separate Next.js application that needs to be cloned and modified. Follow these steps:
+
+**Repository:** [https://github.com/sophiequynn/nexus](https://github.com/sophiequynn/nexus.git)
+
+#### **7.1: Clone Nexus Repository**
+
+```bash
+# Navigate to your workspace (outside graphq-llm)
+# You can clone it in the same parent directory as graphq-llm
+cd /path/to/workspace
+
+# Clone Nexus repository (fork with GraphQ-LLM integration)
+git clone https://github.com/sophiequynn/nexus.git
+cd nexus
+```
+
+**Repository Link:** [https://github.com/sophiequynn/nexus](https://github.com/sophiequynn/nexus.git)
+
+**Note:** This fork already includes all GraphQ-LLM integration files. No manual modifications needed!
+
+**Verify:** You should see a Next.js project structure with `package.json`, `src/`, `app/`, etc.
+
+**Note:** You do NOT need to clone the ResilientDB GraphQL repository separately. The GraphQL server is included in the ResilientDB Docker image and is set up automatically via `setup-graphql.sh` script.
+
+#### **7.2: Install Nexus Dependencies**
+
+```bash
+npm install
+```
+
+#### **7.3: Set Up PostgreSQL with pgvector**
+
+**Using Docker (Recommended):**
+
+```bash
+# Start PostgreSQL with pgvector
+docker run -d \
+ --name nexus-postgres \
+ -e POSTGRES_USER=nexus \
+ -e POSTGRES_PASSWORD=nexus \
+ -e POSTGRES_DB=nexus \
+ -p 5432:5432 \
+ pgvector/pgvector:pg14
+
+# Wait for PostgreSQL to be ready (10-20 seconds)
+sleep 15
+
+# Verify PostgreSQL is running
+docker ps | grep nexus-postgres
+```
+
+**Alternative: Using Supabase (Cloud)**
+
+1. Go to https://supabase.com
+2. Create a free account
+3. Create a new project
+4. Get your connection string from Project Settings โ Database
+
+#### **7.4: Configure Nexus Environment Variables**
+
+Create a `.env` file in the `nexus` directory:
+
+```bash
+cd /path/to/nexus
+touch .env
+```
+
+Add this configuration:
+
+```env
+# Nexus Environment Variables
+
+# Database Configuration
+# For Docker PostgreSQL:
+DATABASE_URL=postgres://nexus:nexus@localhost:5432/nexus
+# For Supabase:
+# DATABASE_URL=postgres://postgres:[YOUR-PASSWORD]@[YOUR-PROJECT].supabase.co:5432/postgres
+
+# Embedding Configuration
+EMBEDDING_DIM=384 # For sentence-transformers/all-MiniLM-L6-v2
+
+# API Keys (Optional but recommended for Nexus features)
+# Get Gemini API key: https://makersuite.google.com/app/apikey
+GEMINI_API_KEY=your_gemini_key_here
+# Get DeepSeek API key: https://www.deepseek.com/
+DEEPSEEK_API_KEY=your_deepseek_key_here
+# Get LlamaCloud API key: https://cloud.llamaindex.ai/
+LLAMA_CLOUD_API_KEY=your_llamacloud_key_here
+
+# Supabase Configuration (if using Supabase for vector store)
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your_supabase_anon_key
+
+# GraphQ-LLM Backend URL (REQUIRED for GraphQL Tutor)
+GRAPHQ_LLM_API_URL=http://localhost:3001
+# Or use NEXT_PUBLIC_ prefix for client-side access:
+NEXT_PUBLIC_GRAPHQ_LLM_API_URL=http://localhost:3001
+```
+
+**How to get API keys:**
+- **Gemini (Recommended):** https://makersuite.google.com/app/apikey โ Create API key โ Copy and paste
+- **DeepSeek:** https://www.deepseek.com/ โ Sign up โ Get API key
+- **LlamaCloud:** https://cloud.llamaindex.ai/ โ Sign up โ Get API key
+- **Supabase:** From your Supabase project dashboard (if using cloud PostgreSQL)
+
+**Note:**
+- Gemini API key is recommended for best LLM performance
+- Other API keys are optional - Nexus will work without them, but some features may be limited
+
+#### **7.5: Set Up Nexus Database Schema**
+
+```bash
+# If using Docker PostgreSQL, run migrations
+# (Check Nexus repository for migration commands)
+# Usually something like:
+npm run db:migrate
+# or
+npx prisma migrate dev
+```
+
+#### **7.6: Add GraphQ-LLM Integration to Nexus (REQUIRED)**
+
+**โ ๏ธ IMPORTANT:** This step adds the GraphQL Tutor UI and API routes to Nexus. This is a critical integration step.
+
+**๐ Reference Guide:**
+- **Location:** `NEXUS_UI_EXTENSION_GUIDE.md` in the GraphQ-LLM repository
+- **Path:** `/path/to/graphq-llm/NEXUS_UI_EXTENSION_GUIDE.md`
+- **Link:** See the file in your cloned GraphQ-LLM repository
+
+**What you need to do:**
+
+1. **Open the guide:**
+ ```bash
+ # From your workspace, open the guide
+ cat /path/to/graphq-llm/NEXUS_UI_EXTENSION_GUIDE.md
+ # Or open it in your editor
+ ```
+
+2. **Create the following files in Nexus:**
+
+ **a. API Route** (create directory first):
+ ```bash
+ mkdir -p src/app/api/graphql-tutor/analyze
+ ```
+ - **File:** `src/app/api/graphql-tutor/analyze/route.ts`
+ - **Code:** Copy from `NEXUS_UI_EXTENSION_GUIDE.md` Section 1
+
+ **b. Main Page** (create directory first):
+ ```bash
+ mkdir -p src/app/graphql-tutor/components
+ ```
+ - **File:** `src/app/graphql-tutor/page.tsx`
+ - **Code:** Copy from `NEXUS_UI_EXTENSION_GUIDE.md` Section 2
+
+ **c. Components** (create in the components directory):
+ - **File:** `src/app/graphql-tutor/components/tutor-panel.tsx`
+ - **Code:** Copy from `NEXUS_UI_EXTENSION_GUIDE.md` Section 3
+ - **File:** `src/app/graphql-tutor/components/explanation-panel.tsx`
+ - **Code:** Copy from `NEXUS_UI_EXTENSION_GUIDE.md` Section 4
+ - **File:** `src/app/graphql-tutor/components/optimization-panel.tsx`
+ - **Code:** Copy from `NEXUS_UI_EXTENSION_GUIDE.md` Section 5
+ - **File:** `src/app/graphql-tutor/components/efficiency-display.tsx`
+ - **Code:** Copy from `NEXUS_UI_EXTENSION_GUIDE.md` Section 6
+
+ **d. Update Home Page:**
+ - **File:** `src/app/page.tsx` (modify existing file)
+ - **Code:** Add navigation link from `NEXUS_UI_EXTENSION_GUIDE.md` Section 7
+
+3. **Install Required Dependencies:**
+ ```bash
+ cd /path/to/nexus
+ npm install lucide-react
+ ```
+
+**Step-by-Step Copy-Paste Method:**
+
+1. Navigate to your GraphQ-LLM repository:
+ ```bash
+ cd /path/to/graphq-llm
+ ```
+
+2. Open `NEXUS_UI_EXTENSION_GUIDE.md` in your editor or view it:
+ ```bash
+ cat NEXUS_UI_EXTENSION_GUIDE.md
+ # Or use: code NEXUS_UI_EXTENSION_GUIDE.md
+ ```
+
+3. For each section in the guide:
+ - Copy the code block
+ - Navigate to Nexus directory: `cd /path/to/nexus`
+ - Create the file in the specified location
+ - Paste the code
+ - Save the file
+
+4. Verify all files are created:
+ ```bash
+ cd /path/to/nexus
+ ls -la src/app/api/graphql-tutor/analyze/route.ts
+ ls -la src/app/graphql-tutor/page.tsx
+ ls -la src/app/graphql-tutor/components/tutor-panel.tsx
+ ls -la src/app/graphql-tutor/components/explanation-panel.tsx
+ ls -la src/app/graphql-tutor/components/optimization-panel.tsx
+ ls -la src/app/graphql-tutor/components/efficiency-display.tsx
+ ```
+
+**All files should exist after this step!**
+
+#### **7.7: Start Nexus**
+
+```bash
+# Start Nexus development server
+npm run dev
+```
+
+Nexus will start on `http://localhost:3000`.
+
+**Verify Nexus is running:**
+```bash
+curl http://localhost:3000/api/research/documents
+```
+
+---
+
+### **Step 8: Verify Everything Works**
+
+#### **8.1: Test GraphQ-LLM Backend**
+
+```bash
+# Test health endpoint
+curl http://localhost:3001/health
+
+# Test explanation endpoint
+curl -X POST http://localhost:3001/api/explanations/explain \
+ -H "Content-Type: application/json" \
+ -d '{"query":"{ getTransaction(id: \"123\") { asset } }"}'
+```
+
+**Expected:** Should return JSON with explanation including documentation context.
+
+#### **8.2: Test Nexus Integration**
+
+```bash
+# Test Nexus API route that proxies to GraphQ-LLM
+curl -X POST http://localhost:3000/api/graphql-tutor/analyze \
+ -H "Content-Type: application/json" \
+ -d '{"query":"{ getTransaction(id: \"123\") { asset } }"}'
+```
+
+**Expected:** Should return JSON with explanation, optimizations, and efficiency data.
+
+#### **8.3: Test Nexus UI**
+
+1. Open browser: `http://localhost:3000/graphql-tutor`
+2. Enter a GraphQL query: `{ getTransaction(id: "123") { asset } }`
+3. Click "Analyze Query"
+4. You should see:
+ - **Explanation tab:** Explanation with documentation context
+ - **Optimization tab:** Optimization suggestions
+ - **Efficiency tab:** Efficiency score and metrics
+
+**Test with these queries:** See `TEST_QUERIES.md` for 10 example queries.
+
+---
+
+## โ
Verification Checklist
+
+After completing all steps, verify:
+
+- [ ] GraphQ-LLM HTTP API responds: `curl http://localhost:3001/health`
+- [ ] (Optional) GraphQ-LLM MCP Server is running: `docker-compose -f docker-compose.dev.yml ps graphq-llm-mcp-server`
+- [ ] ResilientDB KV service is running: `curl http://localhost:18000/v1/transactions/test`
+- [ ] **ResilientDB GraphQL server is running** (REQUIRED): `curl -X POST http://localhost:5001/graphql -H "Content-Type: application/json" -d '{"query":"{ __typename }"}'`
+ - Should return: `{"data":{"__typename":"Query"}}` or similar
+ - If this fails, document ingestion and RAG will not work!
+- [ ] (Optional) ResLens Middleware is running: `curl http://localhost:3003/api/v1/healthcheck`
+ - Should return: `{"status":"UP"}` or similar JSON response
+- [ ] (Optional) ResLens Frontend is accessible: `curl http://localhost:5173` or open `http://localhost:5173` in browser
+- [ ] Documents ingested: Check logs for "Chunks stored: X" (should be 100+)
+- [ ] Nexus is running: `curl http://localhost:3000/api/research/documents`
+- [ ] Nexus UI accessible: Open `http://localhost:3000/graphql-tutor`
+- [ ] Explanation endpoint works: Test via Nexus UI or direct API call
+- [ ] RAG retrieval works: Explanations include documentation context from ResilientDB
+
+---
+
+## ๐ง Current Configuration Summary
+
+### **GraphQ-LLM Configuration:**
+- **LLM Provider:** `gemini` (using `gemini-2.5-flash-lite`)
+- **LLM API Key:** Required (get from https://makersuite.google.com/app/apikey)
+- **Embeddings Provider:** `local` (using `Xenova/all-MiniLM-L6-v2`)
+- **HTTP API Backend Port:** `3001` (for Nexus integration)
+- **MCP Server:** Separate service using stdio transport (no HTTP port)
+- **ResilientDB GraphQL URL:** `http://localhost:5001/graphql` (or `http://resilientdb:5001/graphql` in Docker)
+
+### **Docker Services:**
+- **ResilientDB:** Ports 18000 (KV service) and 5001 (GraphQL server)
+- **GraphQ-LLM Backend:** Port 3001 (HTTP API for Nexus)
+- **GraphQ-LLM MCP Server:** Separate service (stdio transport, no HTTP port)
+- **ResLens Middleware:** Port 3003 (performance monitoring API) - Optional
+- **ResLens Frontend:** Port 5173 (performance monitoring UI) - Optional
+
+### **Nexus Configuration:**
+- **Port:** `3000`
+- **Database:** PostgreSQL with pgvector (Docker or Supabase)
+- **GraphQ-LLM Backend:** `http://localhost:3001`
+
+### **Integration:**
+- GraphQ-LLM HTTP API: `http://localhost:3001` (for Nexus)
+- GraphQ-LLM MCP Server: Separate service (for MCP client integration)
+- Nexus API Route: `http://localhost:3000/api/graphql-tutor/analyze`
+- Nexus proxies requests to GraphQ-LLM HTTP API backend
+
+---
+
+## ๐ Troubleshooting
+
+### **Issue: GraphQ-LLM HTTP API not starting**
+
+**Check:**
+```bash
+# Check if port 3001 is in use
+lsof -i :3001
+
+# Check logs
+docker-compose -f docker-compose.dev.yml logs graphq-llm-backend
+# or if running locally
+tail -f /tmp/graphq-llm-http.log
+```
+
+**Solution:**
+- Kill process on port 3001: `pkill -f "npm run http-api"`
+- Restart the service
+
+### **Issue: Local LLM model not downloading**
+
+**Check:**
+```bash
+# Check Hugging Face cache
+ls -la ~/.cache/huggingface/
+
+# Clear cache and retry
+rm -rf ~/.cache/huggingface/
+```
+
+**Solution:**
+- Ensure `HUGGINGFACE_API_KEY` is set in `.env` (optional but helps with downloads)
+- Wait for model download (first time takes 5-10 minutes)
+- Check internet connection
+
+### **Issue: Nexus not connecting to GraphQ-LLM**
+
+**Check:**
+```bash
+# Verify GraphQ-LLM is running
+curl http://localhost:3001/health
+
+# Check Nexus environment variables
+cat /path/to/nexus/.env | grep GRAPHQ_LLM
+```
+
+**Solution:**
+- Ensure `GRAPHQ_LLM_API_URL=http://localhost:3001` is set in Nexus `.env`
+- Or set `NEXT_PUBLIC_GRAPHQ_LLM_API_URL=http://localhost:3001`
+- Restart Nexus after changing `.env`
+
+### **Issue: GraphQL Server not running**
+
+**Check:**
+```bash
+# Verify GraphQL server is running
+curl -X POST http://localhost:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+```
+
+**Solution:**
+- If using Docker: Check container logs: `docker-compose -f docker-compose.dev.yml logs resilientdb`
+- The `setup-graphql.sh` script should run automatically in Docker
+- If it fails, check that Python dependencies are installed
+- GraphQL server must be running on port 5001 for document ingestion to work
+
+### **Issue: No documents retrieved in explanations**
+
+**Check:**
+```bash
+# Verify GraphQL server is running first
+curl -X POST http://localhost:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+
+# Verify documents were ingested via GraphQL
+curl -X POST http://localhost:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ transactions(limit: 5) { id } }"}'
+```
+
+**Solution:**
+- **First:** Ensure GraphQL server is running (see issue above)
+- Re-run document ingestion: `npm run ingest:graphql`
+- Check that `docs/` directory has GraphQL documentation files
+- Verify ingestion completed successfully (check logs)
+- If GraphQL server is not running, ingestion will fail
+
+### **Issue: PostgreSQL connection failed (Nexus)**
+
+**Check:**
+```bash
+# Verify PostgreSQL is running
+docker ps | grep nexus-postgres
+
+# Test connection
+psql postgres://nexus:nexus@localhost:5432/nexus -c "SELECT 1"
+```
+
+**Solution:**
+- Start PostgreSQL: `docker start nexus-postgres`
+- Check `DATABASE_URL` in Nexus `.env` file
+- Wait 15-20 seconds after starting PostgreSQL before starting Nexus
+
+### **Issue: Nexus UI components not rendering**
+
+**Check:**
+- Verify all component files are created in correct locations
+- Check browser console for errors
+- Verify shadcn/ui components are installed
+
+**Solution:**
+- Ensure all files from `NEXUS_UI_EXTENSION_GUIDE.md` are created
+- Install missing dependencies: `npm install lucide-react`
+- Restart Nexus: `npm run dev`
+
+---
+
+## ๐ฏ Quick Start Commands (Copy-Paste)
+
+For team members who want to get started quickly:
+
+```bash
+# 1. Clone and install GraphQ-LLM
+# Replace <repo-url> with your actual GraphQ-LLM repository URL
+git clone <repo-url> && cd graphq-llm && npm install
+
+# 2. Create .env file (copy configuration from Step 3 above)
+touch .env
+# Edit .env with your configuration
+
+# 3. Start ResilientDB
+docker-compose -f docker-compose.dev.yml up -d resilientdb
+
+# 4. Wait for ResilientDB (60-120 seconds)
+sleep 60
+
+# 5. Start GraphQ-LLM HTTP API backend
+docker-compose -f docker-compose.dev.yml up -d graphq-llm-backend
+
+# 5.1. (Optional) Start MCP Server for MCP client integration
+docker-compose -f docker-compose.dev.yml up -d graphq-llm-mcp-server
+
+# 5.2. (Optional) Clone ResLens forks and start services
+cd /path/to/workspace
+git clone https://github.com/sophiequynn/incubator-resilientdb-ResLens.git ResLens
+git clone https://github.com/sophiequynn/incubator-resilientdb-ResLens-Middleware.git ResLens-Middleware
+
+# Start ResLens services (Docker Compose will use absolute paths from docker-compose.dev.yml)
+cd /path/to/graphq-llm
+docker-compose -f docker-compose.dev.yml up -d reslens-middleware
+sleep 30 # Wait for middleware to be healthy
+docker-compose -f docker-compose.dev.yml up -d reslens-frontend
+
+# 6. Wait for backend (30-60 seconds)
+sleep 30
+
+# 7. Ingest documents (REQUIRED - each teammate must do this)
+docker-compose -f docker-compose.dev.yml exec graphq-llm-backend npm run ingest:graphql
+
+# 8. Set up Nexus (separate repository)
+cd /path/to/workspace
+git clone https://github.com/sophiequynn/nexus.git && cd nexus && npm install
+
+# 9. Set up PostgreSQL for Nexus
+docker run -d --name nexus-postgres \
+ -e POSTGRES_USER=nexus -e POSTGRES_PASSWORD=nexus \
+ -e POSTGRES_DB=nexus -p 5432:5432 pgvector/pgvector:pg14
+
+# 10. Create Nexus .env file (copy configuration from Step 7.4 above)
+touch .env
+# Edit .env with your configuration
+
+# 11. Add GraphQ-LLM integration to Nexus
+# Follow Step 7.6 above - copy files from NEXUS_UI_EXTENSION_GUIDE.md
+# Location: /path/to/graphq-llm/NEXUS_UI_EXTENSION_GUIDE.md
+
+# 12. Start Nexus
+npm run dev
+
+# 13. Test integration
+curl -X POST http://localhost:3000/api/graphql-tutor/analyze \
+ -H "Content-Type: application/json" \
+ -d '{"query":"{ getTransaction(id: \"123\") { asset } }"}'
+```
+
+---
+
+## ๐ Additional Resources
+
+### **Repositories:**
+- **GraphQ-LLM Repository:** Replace `<repository-url>` with your actual repository URL
+- **Nexus Repository:** [https://github.com/sophiequynn/nexus](https://github.com/sophiequynn/nexus.git)
+- **ResilientDB Main Repository:** [https://github.com/apache/incubator-resilientdb](https://github.com/apache/incubator-resilientdb) (for reference - contains GraphQL server in `ecosystem/graphql/`)
+- **ResilientDB GraphQL Repository (Standalone):** [https://github.com/apache/incubator-resilientdb-graphql](https://github.com/apache/incubator-resilientdb-graphql) (for reference only - not needed if using Docker)
+
+### **Documentation Files (in GraphQ-LLM repository):**
+- **Nexus UI Extension Guide:** `NEXUS_UI_EXTENSION_GUIDE.md` (complete code for all Nexus integration files)
+- **Test Queries:** `TEST_QUERIES.md` (10 example queries to test the tutor)
+- **Docker Services Testing:** `TEST_DOCKER_SERVICES.md` (comprehensive testing guide for all Docker services including ResLens)
+- **Project Status:** `FINAL_PHASES_AND_STEPS.md` (overall project progress)
+- **Integration Details:** `WHY_INTEGRATE_RESLENS_NEXUS.md` (why these integrations are needed)
+- **ResilientDB Docs:** `docs/` directory (documentation ingested for RAG)
+
+### **API Key Resources:**
+- **Gemini API Key:** https://makersuite.google.com/app/apikey
+- **Hugging Face Token:** https://huggingface.co/settings/tokens
+- **DeepSeek API Key:** https://www.deepseek.com/
+- **LlamaCloud API Key:** https://cloud.llamaindex.ai/
+- **Supabase:** https://supabase.com
+
+---
+
+## ๐ Need Help?
+
+If you encounter issues:
+
+1. **Check logs:**
+ ```bash
+ # GraphQ-LLM logs
+ docker-compose -f docker-compose.dev.yml logs graphq-llm-backend
+
+ # Nexus logs (in Nexus directory)
+ npm run dev # Check terminal output
+ ```
+
+2. **Verify environment variables:**
+ - GraphQ-LLM `.env` file
+ - Nexus `.env` file
+
+3. **Check service health:**
+ ```bash
+ # GraphQ-LLM HTTP API Backend
+ curl http://localhost:3001/health
+
+ # GraphQ-LLM MCP Server (check container status)
+ docker-compose -f docker-compose.dev.yml ps graphq-llm-mcp-server
+
+ # Nexus
+ curl http://localhost:3000/api/research/documents
+
+ # ResilientDB KV Service
+ curl http://localhost:18000/v1/transactions/test
+
+ # ResilientDB GraphQL Server
+ curl -X POST http://localhost:5001/graphql -H "Content-Type: application/json" -d '{"query":"{ __typename }"}'
+
+ # ResLens Middleware (Optional)
+ curl http://localhost:3003/api/v1/healthcheck
+
+ # ResLens Frontend (Optional)
+ curl http://localhost:5173
+ ```
+
+4. **Review troubleshooting section above**
+
+---
+
+## โ
Success Criteria
+
+You've successfully set up the project when:
+
+1. โ
GraphQ-LLM HTTP API is running on port 3001
+2. โ
(Optional) GraphQ-LLM MCP Server is running (for MCP client integration)
+3. โ
ResilientDB is running and accessible (KV service on 18000, GraphQL on 5001)
+4. โ
(Optional) ResLens services are running (Middleware on 3003, Frontend on 5173)
+5. โ
Documents are ingested (check logs for chunk count - should be 100+)
+6. โ
Nexus is running on port 3000
+7. โ
Nexus UI shows GraphQL Tutor page at `http://localhost:3000/graphql-tutor`
+8. โ
Query analysis works in Nexus UI
+9. โ
Explanations include documentation context from ResilientDB
+
+**Congratulations! You're now at the same stage as the current setup! ๐**
+
+---
+
+## ๐ Notes for Team Members
+
+### **Critical Steps:**
+- **Each teammate must run document ingestion separately** - docs are stored in your local ResilientDB
+- **Nexus UI extensions must be added manually** - follow Step 7.6 and use `NEXUS_UI_EXTENSION_GUIDE.md`
+- **Gemini API key is required** - get it from https://makersuite.google.com/app/apikey
+
+### **Important Reminders:**
+- **First startup takes longer** - models need to be downloaded (5-10 minutes)
+- **Environment variables are critical** - double-check `.env` files in both GraphQ-LLM and Nexus
+- **Test with provided queries** - see `TEST_QUERIES.md` for 10 example queries
+- **Nexus must be cloned separately** - it's a different repository from GraphQ-LLM
+- **All Nexus integration files must be created** - see Step 7.6 for complete list
+
+### **What Gets Modified:**
+- **GraphQ-LLM:** No modifications needed (just clone and configure)
+- **Nexus:** Requires adding 6 new files (see Step 7.6):
+ 1. `src/app/api/graphql-tutor/analyze/route.ts`
+ 2. `src/app/graphql-tutor/page.tsx`
+ 3. `src/app/graphql-tutor/components/tutor-panel.tsx`
+ 4. `src/app/graphql-tutor/components/explanation-panel.tsx`
+ 5. `src/app/graphql-tutor/components/optimization-panel.tsx`
+ 6. `src/app/graphql-tutor/components/efficiency-display.tsx`
+ 7. Modify `src/app/page.tsx` (add navigation link)
+
+---
+
+**Ready to start? Begin with Step 1! ๐**.
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/TEST_DOCKER_SERVICES.md b/ecosystem/ai-tools/mcp/graphq-llm/TEST_DOCKER_SERVICES.md
new file mode 100644
index 00000000..139709bf
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/TEST_DOCKER_SERVICES.md
@@ -0,0 +1,504 @@
+# ๐งช Testing Dockerized Services - Communication Verification
+
+This guide helps you verify that all dockerized services are running and communicating correctly.
+
+---
+
+## ๐ Current Service Architecture
+
+### **Dockerized Services (docker-compose.dev.yml):**
+1. โ
**ResilientDB** - Database with GraphQL server
+ - Container: `resilientdb`
+ - Ports: `18000` (KV service), `5001` (GraphQL server)
+ - Network: `graphq-llm-network`
+
+2. โ
**GraphQ-LLM Backend** - HTTP API server for Nexus
+ - Container: `graphq-llm-backend`
+ - Ports: `3001` (HTTP API), `9229` (Debug)
+ - Network: `graphq-llm-network`
+ - Connects to: ResilientDB via `http://resilientdb:5001/graphql`
+
+3. โ
**GraphQ-LLM MCP Server** - Model Context Protocol server
+ - Container: `graphq-llm-mcp-server`
+ - Transport: stdio (no HTTP port)
+ - Network: `graphq-llm-network`
+ - Connects to: ResilientDB via `http://resilientdb:5001/graphql`
+
+4. โ
**ResLens Middleware** - Performance monitoring API server (Optional)
+ - Container: `reslens-middleware`
+ - Ports: `3003` (HTTP API)
+ - Network: `graphq-llm-network`
+ - Connects to: ResilientDB via `http://resilientdb:18000` (KV service)
+
+5. โ
**ResLens Frontend** - Performance monitoring UI (Optional)
+ - Container: `reslens-frontend`
+ - Ports: `5173` (host) โ `80` (container)
+ - Network: `graphq-llm-network`
+ - Connects to: ResLens Middleware via `http://reslens-middleware:3003/api/v1`
+
+### **External Services (Not Dockerized in dev):**
+6. โ ๏ธ **Nexus** - Next.js frontend application
+ - Runs: Locally with `npm run dev` (port 3000)
+ - Connects to: GraphQ-LLM Backend via `http://localhost:3001`
+
+**Note:** Nexus is NOT dockerized in `docker-compose.dev.yml` but runs separately. It connects to the dockerized backend via exposed ports.
+
+---
+
+## โ
Step-by-Step Verification
+
+### **Step 1: Check All Docker Services Are Running**
+
+```bash
+# Check status of all dockerized services
+docker-compose -f docker-compose.dev.yml ps
+```
+
+**Expected Output:**
+```
+NAME STATUS
+resilientdb Up X minutes (healthy)
+graphq-llm-backend Up X minutes (healthy)
+graphq-llm-mcp-server Up X minutes
+reslens-middleware Up X minutes (healthy/unhealthy)
+reslens-frontend Up X minutes (healthy/unhealthy)
+```
+
+**โ
Success Criteria:**
+- All core services (1-3) show "Up" status
+- ResilientDB shows "healthy"
+- GraphQ-LLM Backend shows "healthy"
+- MCP Server shows "Up" (may show "unhealthy" - that's OK, it uses stdio)
+- ResLens services (4-5) show "Up" (optional - may show "unhealthy" but still working)
+
+---
+
+### **Step 2: Test ResilientDB Services**
+
+#### **2.1: Test ResilientDB KV Service (Port 18000)**
+
+```bash
+# Test KV service from host
+curl http://localhost:18000/v1/transactions/test
+```
+
+**Expected:** Any response (even error) means service is running
+
+#### **2.2: Test ResilientDB GraphQL Server (Port 5001)**
+
+```bash
+# Test GraphQL server from host
+curl -X POST http://localhost:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+```
+
+**Expected Response:**
+```json
+{"data":{"__typename":"Query"}}
+```
+
+**โ
Success Criteria:** Returns GraphQL response (not connection error)
+
+#### **2.3: Test ResilientDB from Inside Docker Network**
+
+```bash
+# Test from backend container (internal network communication)
+docker-compose -f docker-compose.dev.yml exec graphq-llm-backend \
+ curl -X POST http://resilientdb:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+```
+
+**โ
Success Criteria:** Same GraphQL response - proves internal Docker network works
+
+---
+
+### **Step 3: Test GraphQ-LLM Backend (HTTP API)**
+
+#### **3.1: Test Health Endpoint**
+
+```bash
+# Test health endpoint
+curl http://localhost:3001/health
+```
+
+**Expected Response:**
+```json
+{"status":"ok","service":"graphq-llm-api"}
+```
+
+**โ
Success Criteria:** Returns health status
+
+#### **3.2: Test Backend Connection to ResilientDB**
+
+```bash
+# Test that backend can query ResilientDB
+curl -X POST http://localhost:3001/api/explanations/explain \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ getTransaction(id: \"test\") { id } }"}'
+```
+
+**Expected:** Returns explanation with documentation context
+
+**โ
Success Criteria:**
+- Returns 200 OK
+- Response includes explanation text
+- No connection errors to ResilientDB
+
+#### **3.3: Test Backend Logs for ResilientDB Connection**
+
+```bash
+# Check backend logs for connection status
+docker-compose -f docker-compose.dev.yml logs graphq-llm-backend | grep -i resilientdb
+```
+
+**โ
Success Criteria:** Should show successful connections or health checks
+
+---
+
+### **Step 4: Test MCP Server**
+
+#### **4.1: Check MCP Server Container Status**
+
+```bash
+# Check MCP server is running
+docker-compose -f docker-compose.dev.yml ps graphq-llm-mcp-server
+```
+
+**โ
Success Criteria:** Container shows "Up" status
+
+#### **4.2: Check MCP Server Logs**
+
+```bash
+# Check MCP server logs
+docker-compose -f docker-compose.dev.yml logs graphq-llm-mcp-server | tail -20
+```
+
+**Expected Output:**
+```
+MCP Server started and listening on stdio
+Live Stats Service: Enabled/Disabled
+```
+
+**โ
Success Criteria:** Shows "MCP Server started and listening on stdio"
+
+#### **4.3: Test MCP Server Connection to ResilientDB (Internal)**
+
+```bash
+# Test from MCP server container that it can reach ResilientDB
+docker-compose -f docker-compose.dev.yml exec graphq-llm-mcp-server \
+ curl -X POST http://resilientdb:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+```
+
+**โ
Success Criteria:** Returns GraphQL response - proves MCP server can communicate with ResilientDB
+
+**Note:** MCP server uses stdio transport, so it can't be tested via HTTP directly. It's designed to be spawned as a subprocess by MCP clients.
+
+---
+
+### **Step 5: Test ResLens Services (Optional - Performance Monitoring)**
+
+#### **5.1: Test ResLens Middleware**
+
+```bash
+# Test ResLens Middleware health endpoint from host
+curl http://localhost:3003/api/v1/healthcheck
+```
+
+**Expected Response:**
+```json
+{"status":"UP"}
+```
+
+**โ
Success Criteria:** Returns health status JSON
+
+#### **5.2: Test ResLens Middleware Connection to ResilientDB**
+
+```bash
+# Test that middleware can reach ResilientDB from inside Docker network
+docker-compose -f docker-compose.dev.yml exec reslens-middleware \
+ curl http://resilientdb:18000/v1/transactions/test
+```
+
+**โ
Success Criteria:** Returns any response (even error) - proves middleware can reach ResilientDB
+
+#### **5.3: Test ResLens Frontend**
+
+```bash
+# Test ResLens Frontend from host
+curl http://localhost:5173
+```
+
+**Expected Response:** HTML page content (should start with `<!DOCTYPE html>`)
+
+**โ
Success Criteria:** Returns HTML page
+
+#### **5.4: Test ResLens Frontend Connection to Middleware**
+
+```bash
+# Test that frontend container can reach middleware
+docker-compose -f docker-compose.dev.yml exec reslens-frontend \
+ wget -O- http://reslens-middleware:3003/api/v1/healthcheck
+```
+
+**Expected Response:**
+```json
+{"status":"UP"}
+```
+
+**โ
Success Criteria:** Returns middleware health status - proves frontend can communicate with middleware
+
+#### **5.5: Check ResLens Service Logs**
+
+```bash
+# Check ResLens Middleware logs
+docker-compose -f docker-compose.dev.yml logs reslens-middleware | tail -20
+
+# Check ResLens Frontend logs
+docker-compose -f docker-compose.dev.yml logs reslens-frontend | tail -20
+```
+
+**โ
Success Criteria:**
+- Middleware logs show server started successfully
+- Frontend logs show Nginx serving static files
+
+#### **5.6: Access ResLens UI**
+
+Open in browser: `http://localhost:5173`
+
+**โ
Success Criteria:**
+- Page loads successfully
+- Dashboard displays (may show offline mode if profiling services aren't configured)
+- No connection errors in browser console
+
+**Note:** ResLens services are optional. If they show "unhealthy" but still respond to requests, that's acceptable. Health checks may fail due to timing or configuration, but the services can still function.
+
+---
+
+### **Step 6: Test Nexus Connection to GraphQ-LLM Backend**
+
+#### **5.1: Verify Nexus Is Running**
+
+```bash
+# Check if Nexus is running (should be running locally, not in Docker)
+curl http://localhost:3000/api/research/documents
+```
+
+**โ
Success Criteria:** Returns response (even if empty array)
+
+#### **5.2: Test Nexus API Route That Calls GraphQ-LLM Backend**
+
+```bash
+# Test Nexus API route that proxies to GraphQ-LLM
+curl -X POST http://localhost:3000/api/graphql-tutor/analyze \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ getTransaction(id: \"test\") { id asset } }"}'
+```
+
+**Expected Response:**
+```json
+{
+ "explanation": "...",
+ "optimizations": [...],
+ "efficiency": {...}
+}
+```
+
+**โ
Success Criteria:**
+- Returns 200 OK
+- Response includes explanation, optimizations, and efficiency data
+- No errors connecting to GraphQ-LLM backend
+
+#### **5.3: Verify Nexus Environment Configuration**
+
+Check that Nexus has the correct backend URL configured:
+
+```bash
+# If Nexus .env file exists, check configuration
+grep GRAPHQ_LLM_API_URL /path/to/nexus/.env
+```
+
+**Expected:**
+```
+GRAPHQ_LLM_API_URL=http://localhost:3001
+# or
+NEXT_PUBLIC_GRAPHQ_LLM_API_URL=http://localhost:3001
+```
+
+**โ
Success Criteria:** Points to `http://localhost:3001` (the dockerized backend)
+
+---
+
+### **Step 7: End-to-End Test - Full Communication Chain**
+
+#### **7.1: Test Complete Flow (GraphQ-LLM)**
+
+1. **Nexus UI** โ `http://localhost:3000/graphql-tutor`
+2. **Nexus API** โ `http://localhost:3001` (GraphQ-LLM Backend)
+3. **GraphQ-LLM Backend** โ `http://resilientdb:5001/graphql` (ResilientDB)
+4. **ResilientDB** โ Returns data
+
+#### **7.2: Test Complete Flow (ResLens)**
+
+1. **ResLens Frontend** โ `http://localhost:5173`
+2. **ResLens Frontend** โ `http://reslens-middleware:3003/api/v1` (Middleware API)
+3. **ResLens Middleware** โ `http://resilientdb:18000` (ResilientDB KV service)
+4. **ResilientDB** โ Returns performance metrics
+
+```bash
+# Simulate the full chain
+# Step 1: Nexus calls backend
+curl -X POST http://localhost:3000/api/graphql-tutor/analyze \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ getTransaction(id: \"123\") { id asset } }"}' \
+ | jq '.'
+```
+
+**โ
Success Criteria:**
+- Request succeeds through all layers
+- Response includes all expected data
+- No connection timeouts or errors
+
+---
+
+## ๐ Network Verification
+
+### **Check Docker Network**
+
+```bash
+# Inspect the Docker network
+docker network inspect graphq-llm-network
+```
+
+**Expected:** Should show all containers connected:
+- `resilientdb`
+- `graphq-llm-backend`
+- `graphq-llm-mcp-server`
+- `reslens-middleware` (if running)
+- `reslens-frontend` (if running)
+
+**โ
Success Criteria:** All containers are connected to the same network
+
+---
+
+## ๐ Quick Verification Checklist
+
+Run all these commands to verify everything:
+
+```bash
+# 1. Check all services are running
+docker-compose -f docker-compose.dev.yml ps
+
+# 2. Test ResilientDB GraphQL
+curl -X POST http://localhost:5001/graphql \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+
+# 3. Test GraphQ-LLM Backend health
+curl http://localhost:3001/health
+
+# 4. Test GraphQ-LLM Backend query explanation
+curl -X POST http://localhost:3001/api/explanations/explain \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+
+# 5. Check MCP server logs
+docker-compose -f docker-compose.dev.yml logs graphq-llm-mcp-server | tail -5
+
+# 6. Test ResLens Middleware (if running)
+curl http://localhost:3003/api/v1/healthcheck
+
+# 7. Test ResLens Frontend (if running)
+curl http://localhost:5173
+
+# 8. Test Nexus backend connection (if Nexus is running)
+curl -X POST http://localhost:3000/api/graphql-tutor/analyze \
+ -H "Content-Type: application/json" \
+ -d '{"query": "{ __typename }"}'
+
+# 9. Check Docker network
+docker network inspect graphq-llm-network | grep -A 5 "Containers"
+```
+
+---
+
+## โ ๏ธ Common Issues
+
+### **Issue 1: MCP Server Shows "unhealthy"**
+
+**Status:** โ
**This is NORMAL**
+- MCP server uses stdio transport (not HTTP)
+- No HTTP health endpoint exists
+- Check logs instead: `docker-compose -f docker-compose.dev.yml logs graphq-llm-mcp-server`
+
+### **Issue 2: Nexus Can't Connect to Backend**
+
+**Check:**
+1. Is GraphQ-LLM backend running? `curl http://localhost:3001/health`
+2. Is Nexus `.env` configured correctly? Should have `GRAPHQ_LLM_API_URL=http://localhost:3001`
+3. Is Nexus running? `curl http://localhost:3000`
+
+### **Issue 3: Backend Can't Connect to ResilientDB**
+
+**Check:**
+1. Is ResilientDB running? `docker-compose -f docker-compose.dev.yml ps resilientdb`
+2. Test GraphQL server: `curl -X POST http://localhost:5001/graphql ...`
+3. Check backend logs: `docker-compose -f docker-compose.dev.yml logs graphq-llm-backend`
+
+### **Issue 4: ResLens Services Show "unhealthy"**
+
+**Status:** โ ๏ธ **May be normal**
+- ResLens health checks may fail due to timing or configuration
+- Services can still function even if health check shows "unhealthy"
+- Check if services respond to requests:
+ ```bash
+ curl http://localhost:3003/api/v1/healthcheck # Middleware
+ curl http://localhost:5173 # Frontend
+ ```
+- If services respond, they're working despite health check status
+
+### **Issue 5: ResLens Frontend Can't Connect to Middleware**
+
+**Check:**
+1. Is middleware running? `curl http://localhost:3003/api/v1/healthcheck`
+2. Check middleware logs: `docker-compose -f docker-compose.dev.yml logs reslens-middleware`
+3. Test network connectivity: `docker-compose -f docker-compose.dev.yml exec reslens-frontend wget -O- http://reslens-middleware:3003/api/v1/healthcheck`
+4. Verify both containers are on the same network: `docker network inspect graphq-llm-network`
+
+### **Issue 6: ResLens Middleware Can't Connect to ResilientDB**
+
+**Check:**
+1. Is ResilientDB running? `docker-compose -f docker-compose.dev.yml ps resilientdb`
+2. Test ResilientDB KV service: `curl http://localhost:18000/v1/transactions/test`
+3. Test from middleware container: `docker-compose -f docker-compose.dev.yml exec reslens-middleware curl http://resilientdb:18000/v1/transactions/test`
+4. Check middleware logs: `docker-compose -f docker-compose.dev.yml logs reslens-middleware`
+
+---
+
+## ๐ฏ Success Summary
+
+All services are communicating correctly when:
+
+**Core Services (Required):**
+- โ
ResilientDB responds to GraphQL queries
+- โ
GraphQ-LLM Backend health check passes
+- โ
GraphQ-LLM Backend can query ResilientDB
+- โ
MCP Server is running (logs show "started")
+- โ
MCP Server can reach ResilientDB (internal network)
+- โ
Nexus can call GraphQ-LLM Backend API
+- โ
All containers are on the same Docker network
+
+**ResLens Services (Optional):**
+- โ
ResLens Middleware responds to health check (`http://localhost:3003/api/v1/healthcheck`)
+- โ
ResLens Middleware can reach ResilientDB (internal network)
+- โ
ResLens Frontend serves HTML (`http://localhost:5173`)
+- โ
ResLens Frontend can communicate with Middleware (internal network)
+- โ
ResLens UI is accessible in browser (`http://localhost:5173`)
+
+---
+
+**Ready to test? Start with Step 1! ๐**
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/TEST_QUERIES.md b/ecosystem/ai-tools/mcp/graphq-llm/TEST_QUERIES.md
new file mode 100644
index 00000000..a611f4c5
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/TEST_QUERIES.md
@@ -0,0 +1,283 @@
+# ๐งช Test Queries for GraphQL Tutor
+
+Use these 10 queries to test the GraphQL Tutor in Nexus. Copy and paste them into the query editor.
+
+---
+
+## 1. **Basic Transaction Query (Simple)**
+**Complexity:** Low
+**Purpose:** Test basic query retrieval
+
+```graphql
+{
+ getTransaction(id: "123") {
+ id
+ asset
+ }
+}
+```
+
+---
+
+## 2. **Full Transaction Details (Complete)**
+**Complexity:** Medium
+**Purpose:** Test retrieving all available fields
+
+```graphql
+{
+ getTransaction(id: "abc123") {
+ id
+ version
+ amount
+ uri
+ type
+ publicKey
+ signerPublicKey
+ operation
+ metadata
+ asset
+ }
+}
+```
+
+---
+
+## 3. **Transaction with Selected Fields (Focused)**
+**Complexity:** Low
+**Purpose:** Test field selection optimization
+
+```graphql
+{
+ getTransaction(id: "txn_001") {
+ id
+ operation
+ amount
+ asset
+ }
+}
+```
+
+---
+
+## 4. **Transaction Metadata Query (Specific)**
+**Complexity:** Low
+**Purpose:** Test querying specific transaction metadata
+
+```graphql
+{
+ getTransaction(id: "metadata_test_123") {
+ id
+ version
+ metadata
+ operation
+ }
+}
+```
+
+---
+
+## 5. **Transaction with Asset Details (Nested)**
+**Complexity:** Medium
+**Purpose:** Test JSON scalar handling
+
+```graphql
+{
+ getTransaction(id: "asset_456") {
+ id
+ asset
+ type
+ operation
+ }
+}
+```
+
+---
+
+## 6. **Transaction Key Fields Only (Minimal)**
+**Complexity:** Low
+**Purpose:** Test minimal field selection
+
+```graphql
+{
+ getTransaction(id: "minimal_789") {
+ id
+ operation
+ }
+}
+```
+
+---
+
+## 7. **Transaction with Public Keys (Security Context)**
+**Complexity:** Medium
+**Purpose:** Test security-related fields
+
+```graphql
+{
+ getTransaction(id: "key_test_001") {
+ id
+ publicKey
+ signerPublicKey
+ operation
+ type
+ }
+}
+```
+
+---
+
+## 8. **Transaction Amount and URI (Financial)**
+**Complexity:** Low
+**Purpose:** Test financial transaction fields
+
+```graphql
+{
+ getTransaction(id: "amount_uri_123") {
+ id
+ amount
+ uri
+ version
+ }
+}
+```
+
+---
+
+## 9. **Complete Transaction with All Metadata (Comprehensive)**
+**Complexity:** High
+**Purpose:** Test comprehensive field retrieval
+
+```graphql
+query GetFullTransaction {
+ getTransaction(id: "comprehensive_001") {
+ id
+ version
+ amount
+ uri
+ type
+ publicKey
+ signerPublicKey
+ operation
+ metadata
+ asset
+ }
+}
+```
+
+---
+
+## 10. **Transaction Query with Alias (Advanced)**
+**Complexity:** Medium
+**Purpose:** Test GraphQL aliases and query naming
+
+```graphql
+query GetTransactionDetails {
+ transaction: getTransaction(id: "alias_test_123") {
+ transactionId: id
+ transactionType: type
+ transactionOperation: operation
+ transactionAmount: amount
+ assetData: asset
+ }
+}
+```
+
+---
+
+## ๐ Mutation Examples (For Testing Mutations)
+
+### **Create Transaction Mutation**
+
+```graphql
+mutation CreateTransaction {
+ postTransaction(
+ data: {
+ operation: "CREATE"
+ amount: 100
+ signerPublicKey: "signer_pub_key_123"
+ signerPrivateKey: "signer_priv_key_123"
+ recipientPublicKey: "recipient_pub_key_123"
+ asset: {
+ "name": "Test Asset"
+ "description": "This is a test asset"
+ "value": 100
+ }
+ }
+ ) {
+ id
+ }
+}
+```
+
+### **Transfer Transaction Mutation**
+
+```graphql
+mutation TransferTransaction {
+ postTransaction(
+ data: {
+ operation: "TRANSFER"
+ amount: 50
+ signerPublicKey: "signer_pub_key_456"
+ signerPrivateKey: "signer_priv_key_456"
+ recipientPublicKey: "recipient_pub_key_456"
+ asset: {
+ "from": "sender_id"
+ "to": "recipient_id"
+ "amount": 50
+ }
+ }
+ ) {
+ id
+ }
+}
+```
+
+---
+
+## ๐ฏ Testing Strategy
+
+### **Progressive Testing:**
+1. Start with **Query #1** (simplest) to verify basic functionality
+2. Move to **Query #2** (complete) to test all fields
+3. Try **Query #9** (comprehensive) to test complex queries
+4. Test **Query #10** (aliases) to verify advanced GraphQL features
+
+### **What to Check:**
+- โ
**Explanation:** Should explain what the query does
+- โ
**Complexity:** Should show complexity level (low/medium/high)
+- โ
**Documentation Context:** Should reference relevant docs from `docs/`
+- โ
**Optimization Suggestions:** Should provide actionable recommendations
+- โ
**Efficiency Metrics:** Should show estimated performance
+
+### **Expected Behaviors:**
+- Simple queries (1, 3, 6) should show **low complexity**
+- Complete queries (2, 9) should show **medium/high complexity**
+- Queries with many fields should suggest **field selection optimization**
+- All queries should include **documentation context** from ResilientDB docs
+
+---
+
+## ๐ก Tips
+
+1. **Use Real Transaction IDs:** Replace placeholder IDs with actual transaction IDs from your ResilientDB
+2. **Test Edge Cases:** Try queries with non-existent IDs to test error handling
+3. **Compare Results:** Run the same query multiple times to see consistency
+4. **Check Documentation:** Verify that explanations reference the correct documentation
+5. **Test Mutations:** Use mutation examples to test write operations (if supported)
+
+---
+
+## ๐ Query Analysis Focus Areas
+
+When testing, pay attention to:
+
+1. **Field Selection:** Does the tutor suggest selecting only needed fields?
+2. **Query Complexity:** Is the complexity assessment accurate?
+3. **Documentation Relevance:** Are the retrieved docs relevant to the query?
+4. **Optimization Suggestions:** Are suggestions actionable and helpful?
+5. **Efficiency Predictions:** Are performance estimates reasonable?
+
+---
+
+**Happy Testing! ๐**
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/check-docker-services.sh b/ecosystem/ai-tools/mcp/graphq-llm/check-docker-services.sh
new file mode 100755
index 00000000..6dc7b775
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/check-docker-services.sh
@@ -0,0 +1,131 @@
+#!/bin/bash
+# Check which services are running in Docker
+
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "๐ณ Docker Services Status"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo ""
+
+cd /Users/sandhya/UCD/ECS_DDS/graphq-llm
+
+# Check Docker Compose services
+echo "๐ Services defined in docker-compose.dev.yml:"
+docker-compose -f docker-compose.dev.yml config --services
+echo ""
+
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "๐ Running Docker Containers:"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+docker-compose -f docker-compose.dev.yml ps
+echo ""
+
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "๐ Service URLs and Status:"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo ""
+
+# Check each service
+services=(
+ "resilientdb:18000:ResilientDB KV"
+ "resilientdb:5001:ResilientDB GraphQL"
+ "graphq-llm-backend:3001:GraphQ-LLM Backend"
+ "reslens-middleware:3003:ResLens Middleware"
+ "reslens-frontend:5173:ResLens Frontend"
+ "nexus-frontend:3002:Nexus Frontend"
+)
+
+for service_info in "${services[@]}"; do
+ IFS=':' read -r service port name <<< "$service_info"
+
+ # Check if container is running
+ if docker ps --format '{{.Names}}' | grep -q "^${service}$"; then
+ status="โ
Running"
+
+ # Try to test the service
+ if [ "$port" == "18000" ]; then
+ # ResilientDB KV - hard to test, just check container
+ test_result="Container running"
+ elif [ "$port" == "5001" ]; then
+ # ResilientDB GraphQL
+ if curl -s -X POST http://localhost:5001/graphql -H "Content-Type: application/json" -d '{"query": "{ __typename }"}' > /dev/null 2>&1; then
+ test_result="โ
Accessible"
+ else
+ test_result="โ ๏ธ Not responding"
+ fi
+ elif [ "$port" == "3001" ]; then
+ # GraphQ-LLM Backend
+ if curl -s http://localhost:3001/health | grep -q "ok" 2>/dev/null; then
+ test_result="โ
Healthy"
+ else
+ test_result="โ ๏ธ Not responding"
+ fi
+ elif [ "$port" == "3003" ]; then
+ # ResLens Middleware
+ if curl -s http://localhost:3003/api/v1/healthcheck | grep -q "UP" 2>/dev/null; then
+ test_result="โ
Healthy"
+ else
+ test_result="โ ๏ธ Not responding"
+ fi
+ elif [ "$port" == "5173" ]; then
+ # ResLens Frontend
+ if curl -s http://localhost:5173 > /dev/null 2>&1; then
+ test_result="โ
Accessible"
+ else
+ test_result="โ ๏ธ Not responding"
+ fi
+ elif [ "$port" == "3002" ]; then
+ # Nexus Frontend
+ if curl -s http://localhost:3002 > /dev/null 2>&1; then
+ test_result="โ
Accessible"
+ else
+ test_result="โ ๏ธ Not responding"
+ fi
+ fi
+ else
+ status="โ Not Running"
+ test_result="Container not found"
+ fi
+
+ printf "%-25s %-15s %s\n" "$name" "$status" "$test_result"
+done
+
+echo ""
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "๐ Summary:"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo ""
+
+# Count running containers
+running_count=$(docker-compose -f docker-compose.dev.yml ps --services --filter "status=running" | wc -l | tr -d ' ')
+total_count=$(docker-compose -f docker-compose.dev.yml config --services | wc -l | tr -d ' ')
+
+echo "Running: $running_count / $total_count services"
+echo ""
+
+# Check for local services
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "๐ป Local Services (Not Docker):"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo ""
+
+# Check for local Nexus on port 3002
+if lsof -ti:3002 >/dev/null 2>&1 && ! docker ps --format '{{.Names}}' | grep -q "nexus-frontend"; then
+ echo "โ
Nexus running locally on port 3002 (not Docker)"
+fi
+
+# Check for local ResLens on port 5173
+if lsof -ti:5173 >/dev/null 2>&1 && ! docker ps --format '{{.Names}}' | grep -q "reslens-frontend"; then
+ echo "โ
ResLens running locally on port 5173 (not Docker)"
+fi
+
+# Check for local middleware on port 3003
+if lsof -ti:3003 >/dev/null 2>&1 && ! docker ps --format '{{.Names}}' | grep -q "reslens-middleware"; then
+ echo "โ
ResLens Middleware running locally on port 3003 (not Docker)"
+fi
+
+echo ""
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "โ
Check Complete!"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo ""
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/copy-repositories.sh b/ecosystem/ai-tools/mcp/graphq-llm/copy-repositories.sh
new file mode 100644
index 00000000..6f06b23d
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/copy-repositories.sh
@@ -0,0 +1,131 @@
+#!/bin/bash
+# Copy ResLens, ResLens-Middleware, and nexus into graphq-llm directory
+# Excludes .git files and node_modules
+
+set -e
+
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "๐ฆ Copying Repositories into graphq-llm"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo ""
+
+BASE_DIR="/Users/sandhya/UCD/ECS_DDS"
+TARGET_DIR="/Users/sandhya/UCD/ECS_DDS/graphq-llm"
+
+# Create target directories
+echo "Creating target directories..."
+mkdir -p "$TARGET_DIR/ResLens"
+mkdir -p "$TARGET_DIR/ResLens-Middleware"
+mkdir -p "$TARGET_DIR/nexus"
+echo "โ
Target directories created"
+echo ""
+
+# Copy ResLens
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "Copying ResLens..."
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+if [ -d "$BASE_DIR/ResLens" ]; then
+ echo "Source: $BASE_DIR/ResLens"
+ echo "Target: $TARGET_DIR/ResLens"
+ rsync -av --progress \
+ --exclude='.git' \
+ --exclude='.gitignore' \
+ --exclude='node_modules' \
+ --exclude='.next' \
+ --exclude='dist' \
+ --exclude='build' \
+ "$BASE_DIR/ResLens/" "$TARGET_DIR/ResLens/"
+ echo "โ
ResLens copied successfully"
+else
+ echo "โ ResLens directory not found at: $BASE_DIR/ResLens"
+fi
+echo ""
+
+# Copy ResLens-Middleware
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "Copying ResLens-Middleware..."
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+if [ -d "$BASE_DIR/ResLens-Middleware" ]; then
+ echo "Source: $BASE_DIR/ResLens-Middleware"
+ echo "Target: $TARGET_DIR/ResLens-Middleware"
+ rsync -av --progress \
+ --exclude='.git' \
+ --exclude='.gitignore' \
+ --exclude='node_modules' \
+ --exclude='.next' \
+ --exclude='dist' \
+ --exclude='build' \
+ "$BASE_DIR/ResLens-Middleware/" "$TARGET_DIR/ResLens-Middleware/"
+ echo "โ
ResLens-Middleware copied successfully"
+else
+ echo "โ ResLens-Middleware directory not found at: $BASE_DIR/ResLens-Middleware"
+fi
+echo ""
+
+# Copy nexus
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "Copying nexus..."
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+if [ -d "$BASE_DIR/nexus" ]; then
+ echo "Source: $BASE_DIR/nexus"
+ echo "Target: $TARGET_DIR/nexus"
+ rsync -av --progress \
+ --exclude='.git' \
+ --exclude='.gitignore' \
+ --exclude='node_modules' \
+ --exclude='.next' \
+ --exclude='dist' \
+ --exclude='build' \
+ "$BASE_DIR/nexus/" "$TARGET_DIR/nexus/"
+ echo "โ
nexus copied successfully"
+else
+ echo "โ nexus directory not found at: $BASE_DIR/nexus"
+fi
+echo ""
+
+# Verify no .git folders were copied
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "Verifying .git folders were excluded..."
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+GIT_COUNT=$(find "$TARGET_DIR/ResLens" "$TARGET_DIR/ResLens-Middleware" "$TARGET_DIR/nexus" -type d -name ".git" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$GIT_COUNT" -eq 0 ]; then
+ echo "โ
No .git folders found (as expected)"
+else
+ echo "โ ๏ธ Found $GIT_COUNT .git folder(s) - removing them..."
+ find "$TARGET_DIR/ResLens" "$TARGET_DIR/ResLens-Middleware" "$TARGET_DIR/nexus" -type d -name ".git" -exec rm -rf {} + 2>/dev/null || true
+ echo "โ
.git folders removed"
+fi
+echo ""
+
+# Show summary
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "๐ Copy Summary"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo ""
+echo "Copied directories:"
+ls -d "$TARGET_DIR"/ResLens "$TARGET_DIR"/ResLens-Middleware "$TARGET_DIR"/nexus 2>/dev/null | while read dir; do
+ if [ -d "$dir" ]; then
+ size=$(du -sh "$dir" 2>/dev/null | cut -f1)
+ file_count=$(find "$dir" -type f 2>/dev/null | wc -l | tr -d ' ')
+ dir_name=$(basename "$dir")
+ echo " โ
$dir_name: $size ($file_count files)"
+ fi
+done
+echo ""
+
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo "โ
Copy Complete!"
+echo "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ"
+echo ""
+echo "Next steps:"
+echo " 1. Install dependencies in each directory:"
+echo " cd $TARGET_DIR/ResLens && npm install"
+echo " cd $TARGET_DIR/ResLens-Middleware/middleware && npm install"
+echo " cd $TARGET_DIR/nexus && npm install"
+echo ""
+echo " 2. Update fix-reslens.sh to use local directories:"
+echo " RESLENS_DIR=\"$TARGET_DIR/ResLens\""
+echo " MIDDLEWARE_DIR=\"$TARGET_DIR/ResLens-Middleware/middleware\""
+echo " NEXUS_DIR=\"$TARGET_DIR/nexus\""
+echo ""
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docker-compose.dev.yml b/ecosystem/ai-tools/mcp/graphq-llm/docker-compose.dev.yml
new file mode 100644
index 00000000..02d513fb
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docker-compose.dev.yml
@@ -0,0 +1,241 @@
+version: '3.8'
+
+services:
+ # ResilientDB Database
+ # Note: Using existing ResilientDB setup from start-resilientdb.sh
+ # This service is optional if ResilientDB is already running
+ resilientdb:
+ image: expolab/resdb:${ARCH:-amd64}
+ # Platform should match ARCH variable - remove if you want Docker to auto-detect
+ # For ARM64: set ARCH=arm64 in .env or export ARCH=arm64
+ # For AMD64: leave ARCH unset or set ARCH=amd64 (default)
+ container_name: resilientdb
+ ports:
+ - "18000:18000"
+ - "5001:5001" # GraphQL server port
+ volumes:
+ - resilientdb-data:/data
+ # Mount GraphQL setup script for persistence
+ - ./setup-graphql.sh:/app/setup-graphql.sh:ro
+ networks:
+ - graphq-llm-network
+ environment:
+ - RESDB_HOST=0.0.0.0
+ - RESDB_PORT=18000
+ # โ ๏ธ IMPORTANT: This configuration may prevent ResilientDB KV service from starting
+ # The expolab/resdb image's default entrypoint should start the KV service automatically,
+ # but we're overriding it to run setup-graphql.sh. This might prevent KV service startup.
+ #
+ # RECOMMENDED: Set up ResilientDB separately first (see TEAM_SETUP.md for details)
+ # Then comment out this service and use your existing ResilientDB instance.
+ #
+ # If you want to try this setup:
+ # 1. Start containers: docker-compose up -d
+ # 2. Verify KV service: curl http://localhost:18000/v1/transactions/test
+ # 3. If it fails, set up ResilientDB separately (see TEAM_SETUP.md)
+ #
+ # The healthcheck tests port 18000 (KV service) - if it fails, KV service isn't running
+ # Note: Use default entrypoint which starts KV service
+ # GraphQL setup can be done manually after container starts
+ # Remove entrypoint override to use default
+ # entrypoint: ["/bin/sh", "-c"]
+ # command: "tail -f /dev/null"
+ healthcheck:
+ # Check if KV service processes are running instead of HTTP endpoint
+ # The HTTP endpoint on 18000 may not be immediately available
+ test: ["CMD-SHELL", "ps aux | grep -E '[k]v_service' | wc -l | xargs test $(cat) -ge 1 || exit 1"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 120s # Give more time for services to start
+
+ # GraphQ-LLM Backend (HTTP API Server for Nexus)
+ graphq-llm-backend:
+ build:
+ context: .
+ dockerfile: Dockerfile
+ container_name: graphq-llm-backend
+ ports:
+ - "3001:3001"
+ - "9229:9229" # Debug port
+ environment:
+ # ResilientDB Configuration
+ - RESILIENTDB_GRAPHQL_URL=${RESILIENTDB_GRAPHQL_URL:-http://resilientdb:5001/graphql}
+ - RESILIENTDB_API_KEY=${RESILIENTDB_API_KEY:-}
+
+ # Nexus Configuration (optional)
+ - NEXUS_API_URL=${NEXUS_API_URL:-}
+ - NEXUS_API_KEY=${NEXUS_API_KEY:-}
+
+ # ResLens Configuration (for Live Mode)
+ - RESLENS_API_URL=${RESLENS_API_URL:-}
+ - RESLENS_API_KEY=${RESLENS_API_KEY:-}
+ - RESLENS_LIVE_MODE=${RESLENS_LIVE_MODE:-false}
+ - RESLENS_POLL_INTERVAL=${RESLENS_POLL_INTERVAL:-5000}
+
+ # LLM Configuration
+ - LLM_PROVIDER=${LLM_PROVIDER:-deepseek}
+ - LLM_API_KEY=${LLM_API_KEY:-}
+ - LLM_MODEL=${LLM_MODEL:-deepseek-chat}
+ # Enable Live Stats access for LLM (requires ResLens Live Mode)
+ - LLM_ENABLE_LIVE_STATS=${LLM_ENABLE_LIVE_STATS:-false}
+
+ # Embedding Provider Configuration (Hugging Face)
+ - HUGGINGFACE_API_KEY=${HUGGINGFACE_API_KEY:-}
+
+ # MCP Server Configuration (for HTTP API)
+ - MCP_SERVER_PORT=3001
+ - MCP_SERVER_HOST=0.0.0.0
+
+ # Logging
+ - LOG_LEVEL=${LOG_LEVEL:-info}
+ - NODE_ENV=development
+
+ # Debug
+ - NODE_OPTIONS=--inspect=0.0.0.0:9229
+ depends_on:
+ resilientdb:
+ condition: service_healthy
+ networks:
+ - graphq-llm-network
+ volumes:
+ # Live updates: mount source code
+ - ./src:/app/src
+ - ./dist:/app/dist
+ - ./package.json:/app/package.json
+ - ./tsconfig.json:/app/tsconfig.json
+ # Mount docs directory for document ingestion
+ - ./docs:/app/docs
+ # Exclude node_modules from volume mount
+ - /app/node_modules
+ command: sh -c "npm install && npm run http-api"
+ restart: unless-stopped
+ healthcheck:
+ test: ["CMD", "node", "-e", "require('http').get('http://localhost:3001/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 10s
+
+ # MCP Server (Model Context Protocol Server)
+ # Uses stdio transport for communication with MCP clients
+ graphq-llm-mcp-server:
+ build:
+ context: .
+ dockerfile: Dockerfile
+ container_name: graphq-llm-mcp-server
+ stdin_open: true # Keep stdin open for MCP stdio communication
+ tty: true # Allocate a pseudo-TTY
+ environment:
+ # ResilientDB Configuration
+ - RESILIENTDB_GRAPHQL_URL=${RESILIENTDB_GRAPHQL_URL:-http://resilientdb:5001/graphql}
+ - RESILIENTDB_SIGNER_PUBLIC_KEY=${RESILIENTDB_SIGNER_PUBLIC_KEY:-}
+ - RESILIENTDB_SIGNER_PRIVATE_KEY=${RESILIENTDB_SIGNER_PRIVATE_KEY:-}
+ - RESILIENTDB_RECIPIENT_PUBLIC_KEY=${RESILIENTDB_RECIPIENT_PUBLIC_KEY:-}
+ - RESILIENTDB_API_KEY=${RESILIENTDB_API_KEY:-}
+
+ # ResLens Configuration (for Live Mode)
+ - RESLENS_API_URL=${RESLENS_API_URL:-}
+ - RESLENS_API_KEY=${RESLENS_API_KEY:-}
+ - RESLENS_LIVE_MODE=${RESLENS_LIVE_MODE:-false}
+ - RESLENS_POLL_INTERVAL=${RESLENS_POLL_INTERVAL:-5000}
+
+ # LLM Configuration
+ - LLM_PROVIDER=${LLM_PROVIDER:-deepseek}
+ - LLM_API_KEY=${LLM_API_KEY:-}
+ - LLM_MODEL=${LLM_MODEL:-deepseek-chat}
+ # Enable Live Stats access for LLM (requires ResLens Live Mode)
+ - LLM_ENABLE_LIVE_STATS=${LLM_ENABLE_LIVE_STATS:-false}
+
+ # Embedding Provider Configuration (Hugging Face)
+ - HUGGINGFACE_API_KEY=${HUGGINGFACE_API_KEY:-}
+
+ # Logging
+ - LOG_LEVEL=${LOG_LEVEL:-info}
+ - NODE_ENV=development
+ depends_on:
+ resilientdb:
+ condition: service_healthy
+ networks:
+ - graphq-llm-network
+ volumes:
+ # Live updates: mount source code
+ - ./src:/app/src
+ - ./dist:/app/dist
+ - ./package.json:/app/package.json
+ - ./tsconfig.json:/app/tsconfig.json
+ # Mount docs directory for RAG
+ - ./docs:/app/docs
+ # Exclude node_modules from volume mount
+ - /app/node_modules
+ command: sh -c "npm install && npm run mcp-server"
+ restart: unless-stopped
+ # Note: MCP server uses stdio transport, so it doesn't expose HTTP ports
+ # Health check is not applicable for stdio-based services
+ # The server will run until terminated via stdin
+
+ # ResLens Middleware (Optional - for live performance monitoring)
+ # See DOCKER_RESLENS_SETUP.md for full setup instructions
+ reslens-middleware:
+ build:
+ context: /Users/sophiequynn/ResLens-Middleware/middleware
+ dockerfile: Dockerfile
+ container_name: reslens-middleware
+ ports:
+ - "3003:3003" # Middleware HTTP API
+ environment:
+ - PORT=3003
+ - CPP_STATS_API_BASE_URL=http://resilientdb:18000
+ - CPP_TRANSACTIONS_API_BASE_URL=http://resilientdb:18000
+ # Optional: Add other environment variables as needed
+ # - PYROSCOPE_SERVER_URL=http://pyroscope:4040
+ # - PROMETHEUS_URL=http://prometheus:9090
+ # - NODE_EXPORTER_BASE_URL=http://node-exporter:9100
+ # - PROCESS_EXPORTER_BASE_URL=http://process-exporter:9256
+ # - EXPLORER_BASE_URL=http://explorer:8080
+ depends_on:
+ resilientdb:
+ condition: service_healthy
+ networks:
+ - graphq-llm-network
+ healthcheck:
+ test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3003/api/v1/healthcheck || exit 1"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 30s
+ restart: unless-stopped
+
+ # ResLens Frontend (Optional - for performance monitoring UI)
+ reslens-frontend:
+ build:
+ context: /Users/sophiequynn/ResLens
+ dockerfile: Dockerfile
+ args:
+ - VITE_MIDDLEWARE_BASE_URL=http://localhost:3003/api/v1
+ - VITE_MIDDLEWARE_SECONDARY_BASE_URL=http://localhost:3003/api/v1
+ container_name: reslens-frontend
+ ports:
+ - "5173:80" # Frontend UI
+ # depends_on:
+ # reslens-middleware:
+ # condition: service_healthy
+ networks:
+ - graphq-llm-network
+ healthcheck:
+ test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:80 || exit 1"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 30s
+ restart: unless-stopped
+
+networks:
+ graphq-llm-network:
+ driver: bridge
+ name: graphq-llm-network
+
+volumes:
+ resilientdb-data:
+ name: resilientdb-data
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docker-compose.yml b/ecosystem/ai-tools/mcp/graphq-llm/docker-compose.yml
new file mode 100644
index 00000000..e2e43b25
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docker-compose.yml
@@ -0,0 +1,138 @@
+# Production Docker Compose for AWS Deployment
+# Note: 'version' field is deprecated in Docker Compose v2+
+# This includes all services: ResilientDB, PostgreSQL (for Nexus), and GraphQ-LLM Backend
+
+services:
+ # PostgreSQL + GraphQ-LLM Backend Container
+ graphql-nexus:
+ build:
+ context: .
+ dockerfile: Dockerfile.all-in-one
+ args:
+ - ARCH=${ARCH:-arm64}
+ container_name: graphql-nexus
+ ports:
+ - "5432:5432" # PostgreSQL
+ - "3001:3001" # GraphQ-LLM Backend
+ volumes:
+ - nexus-postgres-data:/var/lib/postgresql/data
+ - huggingface-cache:/root/.cache/huggingface
+ - ./docs:/app/graphq-llm/docs:ro
+ networks:
+ - graphq-llm-network
+ environment:
+ # PostgreSQL Configuration
+ - POSTGRES_USER=${POSTGRES_USER:-nexus}
+ - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-nexus}
+ - POSTGRES_DB=${POSTGRES_DB:-nexus}
+ # GraphQ-LLM Configuration (connects to ResilientDB sidecar)
+ - RESILIENTDB_GRAPHQL_URL=http://graphql-nexus-resilientdb:5001/graphql
+ - NEXUS_API_URL=${NEXUS_API_URL:-http://localhost:3000}
+ - LLM_PROVIDER=${LLM_PROVIDER:-local}
+ - LLM_MODEL=${LLM_MODEL:-Xenova/gpt2}
+ - EMBEDDINGS_PROVIDER=${EMBEDDINGS_PROVIDER:-local}
+ - HUGGINGFACE_API_KEY=${HUGGINGFACE_API_KEY:-}
+ - MCP_SERVER_PORT=3001
+ - MCP_SERVER_HOST=0.0.0.0
+ - LOG_LEVEL=${LOG_LEVEL:-info}
+ - NODE_ENV=production
+ depends_on:
+ - graphql-nexus-resilientdb
+ healthcheck:
+ test: ["CMD", "/app/healthcheck-all.sh"]
+ interval: 30s
+ timeout: 10s
+ retries: 5
+ start_period: 120s
+ restart: unless-stopped
+
+ # ResilientDB Sidecar (runs alongside graphql-nexus)
+ graphql-nexus-resilientdb:
+ image: expolab/resdb:${ARCH:-arm64}
+ container_name: graphql-nexus-resilientdb
+ ports:
+ - "18000:18000" # ResilientDB KV
+ - "5001:5001" # ResilientDB GraphQL
+ volumes:
+ - resilientdb-data:/data
+ - ./setup-graphql.sh:/app/setup-graphql.sh:ro
+ networks:
+ - graphq-llm-network
+ environment:
+ - RESDB_HOST=0.0.0.0
+ - RESDB_PORT=18000
+ # Use default entrypoint to start KV service, then setup GraphQL
+ # Don't override entrypoint - let default start KV service
+ # GraphQL setup will be done manually or via a separate init container
+ # For now, just start the container normally
+ healthcheck:
+ test: ["CMD-SHELL", "curl -f http://localhost:18000/v1/transactions/test || exit 1"]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 60s
+ restart: unless-stopped
+
+ # Nexus (Next.js Application)
+ # NOTE: Nexus must be cloned first. Run: ./setup-nexus.sh
+ # Or manually: git clone https://github.com/sophiequynn/nexus.git ./nexus
+ nexus:
+ build:
+ context: ./nexus
+ dockerfile: ../Dockerfile.nexus
+ container_name: nexus
+ ports:
+ - "3000:3000"
+ environment:
+ # Database Configuration (connect to unified graphql-nexus service)
+ - DATABASE_URL=postgres://${POSTGRES_USER:-nexus}:${POSTGRES_PASSWORD:-nexus}@graphql-nexus:5432/${POSTGRES_DB:-nexus}
+
+ # Embedding Configuration
+ - EMBEDDING_DIM=${EMBEDDING_DIM:-384}
+
+ # API Keys (Optional)
+ - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY:-}
+ - GEMINI_API_KEY=${GEMINI_API_KEY:-}
+ - LLAMA_CLOUD_API_KEY=${LLAMA_CLOUD_API_KEY:-}
+ - TAVILY_API_KEY=${TAVILY_API_KEY:-}
+
+ # Supabase Configuration (Optional)
+ - SUPABASE_URL=${SUPABASE_URL:-}
+ - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY:-}
+
+ # GraphQ-LLM Backend URL (connect to unified graphql-nexus service)
+ - GRAPHQ_LLM_API_URL=http://graphql-nexus:3001
+ - NEXT_PUBLIC_GRAPHQ_LLM_API_URL=http://graphql-nexus:3001
+
+ - NODE_ENV=production
+ depends_on:
+ graphql-nexus:
+ condition: service_healthy
+ graphql-nexus-resilientdb:
+ condition: service_healthy
+ networks:
+ - graphq-llm-network
+ volumes:
+ # Mount documents directory if needed
+ - ./nexus/documents:/app/documents:ro
+ restart: unless-stopped
+ healthcheck:
+ test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/research/documents || exit 0"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 60s # Next.js build takes time
+
+networks:
+ graphq-llm-network:
+ driver: bridge
+ name: graphq-llm-network
+
+volumes:
+ resilientdb-data:
+ name: resilientdb-data
+ nexus-postgres-data:
+ name: nexus-postgres-data
+ huggingface-cache:
+ name: huggingface-cache
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docs/GRAPHQL_SCHEMA_EXAMPLES.md b/ecosystem/ai-tools/mcp/graphq-llm/docs/GRAPHQL_SCHEMA_EXAMPLES.md
new file mode 100644
index 00000000..b539e664
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docs/GRAPHQL_SCHEMA_EXAMPLES.md
@@ -0,0 +1,182 @@
+# GraphQL Schema Examples
+
+Based on `app.py` from incubator-resilientdb-graphql repository.
+
+## GraphQL Schema Structure
+
+### Query Type
+
+#### `getTransaction(id: ID!): RetrieveTransaction`
+
+Retrieves a transaction by its ID.
+
+**Example Query:**
+```graphql
+query {
+ getTransaction(id: "abc123") {
+ id
+ version
+ amount
+ uri
+ type
+ publicKey
+ signerPublicKey
+ operation
+ metadata
+ asset
+ }
+}
+```
+
+**Response:**
+```json
+{
+ "data": {
+ "getTransaction": {
+ "id": "abc123",
+ "version": "2.0",
+ "amount": 100,
+ "uri": "uri://...",
+ "type": "Ed25519Sha256",
+ "publicKey": "public_key_string",
+ "signerPublicKey": "signer_public_key",
+ "operation": "CREATE",
+ "metadata": null,
+ "asset": { /* JSON object */ }
+ }
+ }
+}
+```
+
+### Mutation Type
+
+#### `postTransaction(data: PrepareAsset!): CommitTransaction`
+
+Creates and commits a new transaction to ResilientDB.
+
+**Input Type: `PrepareAsset`**
+```graphql
+input PrepareAsset {
+ operation: String!
+ amount: Int!
+ signerPublicKey: String!
+ signerPrivateKey: String!
+ recipientPublicKey: String!
+ asset: JSON!
+}
+```
+
+**Example Mutation:**
+```graphql
+mutation {
+ postTransaction(
+ data: {
+ operation: "CREATE"
+ amount: 100
+ signerPublicKey: "public_key_string"
+ signerPrivateKey: "private_key_string"
+ recipientPublicKey: "recipient_public_key"
+ asset: {
+ "data": {
+ "name": "My Asset",
+ "description": "Asset description"
+ }
+ }
+ }
+ ) {
+ id
+ }
+}
+```
+
+**Response:**
+```json
+{
+ "data": {
+ "postTransaction": {
+ "id": "transaction_id_here"
+ }
+ }
+}
+```
+
+## Transaction Types
+
+### RetrieveTransaction
+
+Fields returned when retrieving a transaction:
+
+- `id: String` - Transaction ID
+- `version: String` - Transaction version
+- `amount: Int` - Transaction amount
+- `uri: String` - URI condition
+- `type: String` - Condition type (e.g., "Ed25519Sha256")
+- `publicKey: String` - Public key from output condition
+- `signerPublicKey: String` - Public key from input (signer)
+- `operation: String` - Operation type ("CREATE" or "TRANSFER")
+- `metadata: String` - Optional metadata
+- `asset: JSON` - Asset data (JSON object)
+
+### CommitTransaction
+
+Fields returned when committing a transaction:
+
+- `id: String` - Committed transaction ID
+
+## Key-Value Operations
+
+Underlying ResilientDB operations use key-value pairs:
+
+### Key-Value Storage
+
+- Transactions are stored as key-value pairs
+- Key: Transaction ID
+- Value: JSON object containing transaction data
+
+### Example Key-Value Operations
+
+**Commit Transaction (Key-Value):**
+```bash
+curl -X POST -d '{"id":"key1","value":"value1"}' \
+ http://localhost:18000/v1/transactions/commit
+```
+
+**Retrieve Transaction (Key-Value):**
+```bash
+curl http://localhost:18000/v1/transactions/key1
+```
+
+**Get All Transactions:**
+```bash
+curl http://localhost:18000/v1/transactions
+```
+
+## Common Patterns
+
+### Creating an Asset
+
+1. Prepare transaction with operation "CREATE"
+2. Specify asset data as JSON
+3. Commit transaction
+4. Get transaction ID
+
+### Transferring an Asset
+
+1. Prepare transaction with operation "TRANSFER"
+2. Specify recipient public key
+3. Use existing transaction as input
+4. Commit transaction
+
+### Querying Transactions
+
+1. Use `getTransaction` query with transaction ID
+2. Retrieve all transaction fields
+3. Access asset data from response
+
+## Notes
+
+- All transactions use JSON scalar for flexible asset data
+- Private keys are required for mutations but never stored
+- Transactions are immutable once committed
+- GraphQL provides type safety over raw key-value operations
+
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docs/GRAPHQL_SETUP.md b/ecosystem/ai-tools/mcp/graphq-llm/docs/GRAPHQL_SETUP.md
new file mode 100644
index 00000000..2c296d41
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docs/GRAPHQL_SETUP.md
@@ -0,0 +1,305 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+
+# ResilientDB GraphQL
+ResilientDB GraphQL Server
+
+# Get Prepared
+
+(If you're using this for the first time, the steps below would be useful)
+
+Install **Ubuntu 20.04** on your local machine.
+
+Once installed, go to File Explorer -> Linux -> Ubuntu 20.04.
+
+Clone this repository.
+
+Install python3 (version - 3.9+) and ensure pip is installed using the command.
+
+ sudo apt-get install python3-pip
+
+Also make sure to install the venv module which creates a virtual Python environment that helps encapsulate the project's dependencies and prevents possible conflicts with the global Python environment. The command is:
+
+ sudo apt-get install -y python3.10-venv
+
+Create a virtual environment:
+
+ python3 -m venv venv
+
+Start a virtual environment:
+
+ source venv/bin/activate
+
+Go back from the virtual environment when you no longer need it:
+
+ deactivate
+
+# Using the SDK
+
+To use the SDK, you need to start a KV service first, which you can refer to the [resilientdb](https://github.com/resilientdb/resilientdb) repository and the [blog](https://blog.resilientdb.com/2022/09/28/GettingStartedNexRes.html).
+
+Then you should start the crow http service, which may take a few minutes at the first time.
+
+ bazel build service/http_server:crow_service_main
+
+ bazel-bin/service/http_server/crow_service_main service/tools/config/interface/service.config service/http_server/server_config.config
+
+After starting the crow service, you can optionally test it by using the **curl** command to send HTTP requests.
+
+ curl -X POST -d '{"id":"key1","value":"value1"}' 127.0.0.1:18000/v1/transactions/commit
+
+ curl 127.0.0.1:18000/v1/transactions/key1
+
+The expected output of the two commands above are: `id: key1` and `{"id":"key1","value":"value1"}`, respectively.
+
+Start your virtual environment.
+
+ source venv/bin/activate
+
+Run the requirements.txt command to install the SDK related dependencies.
+
+ pip3 install -r requirements.txt
+
+Try the test script.
+
+ python3 test_sdk.py
+
+You have successfully run the script if you see the output: `The retrieved txn is successfully validated`
+
+# GraphQL
+
+<!-- 7. (Temporary resolve) Copy app.py to the nexres_sdk folder to ensure execution -->
+
+(Optional) If there is an error while running any command relating to NexRes, this command below may help:
+
+ sudo apt-get install python3.10-distutils
+
+Note: If there is an error with the pip version, use the command:
+
+ curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10
+
+Open a venv in the Ubuntu server and run the command:
+
+ source venv/bin/activate
+
+ sudo apt-get install cloud-init
+
+Install the remaining dependencies in venv
+
+ python3 -m pip install strawberry-graphql
+
+ python3 -m pip install flask_cors
+
+**BUG FIX**: in the case requirements.txt doesn't work, and the `cloud-init` version is not found, edit the file to be:
+```C
+aiohttp==3.8.3
+aiohttp-cors==0.7.0
+aiosignal==1.3.1
+anyio==3.6.2
+ariadne==0.17.0
+async-timeout==4.0.2
+attrs==22.2.0
+base58==2.1.0
+certifi==2022.12.7
+cffi==1.15.1
+charset-normalizer==2.1.1
+click==8.1.3
+commonmark==0.9.1
+cryptoconditions==0.8.1
+cryptography==3.4.7
+Flask==2.2.2
+Flask-Cors==3.0.10
+frozenlist==1.3.3
+graphql-core==3.2.3
+h11==0.14.0
+idna==3.4
+importlib-metadata==5.2.0
+itsdangerous==2.1.2
+Jinja2==3.1.2
+libcst==0.4.9
+MarkupSafe==2.1.1
+multidict==6.0.4
+mypy-extensions==0.4.3
+pyasn1==0.4.8
+pycparser==2.21
+Pygments==2.14.0
+PyNaCl==1.4.0
+pysha3==1.0.2
+python-dateutil==2.8.2
+python-multipart==0.0.5
+python-rapidjson==1.8
+PyYAML==6.0
+requests==2.28.1
+rich==13.0.1
+six==1.16.0
+sniffio==1.3.0
+starlette==0.23.1
+strawberry-graphql==0.152.0
+typing-inspect==0.8.0
+typing_extensions==4.4.0
+urllib3==1.26.13
+uvicorn==0.20.0
+Werkzeug==2.2.2
+yarl==1.8.2
+zipp==3.11.0
+```
+
+- You may get an error that says `Running setup.py install for <dependency> did not run successfully.`
+- First, try `pip3 install wheel` or `pip install wheel`
+- Next, install all missing dependencies manually
+ - **NOTE** as long as you still have dependencies to install, you will get an error message, but this is okay!
+ - From the stack trace, identify the module, then use `pip install <dependency>`
+ - keep generating errors by running `python3 app.py` every time, and resolve each missing dependency
+- Ex:
+```C
+Traceback (most recent call last):
+File "/home/user/repos/NexresGraphQL/app.py", line 1, in <module>
+from resdb_driver import Resdb
+File "/home/user/repos/NexresGraphQL/resdb_driver/__init__.py", line 1, in <module>
+from .driver import Resdb
+File "/home/user/repos/NexresGraphQL/resdb_driver/driver.py", line 4, in <module>
+from .offchain import prepare_transaction, fulfill_transaction
+File "/home/user/repos/NexresGraphQL/resdb_driver/offchain.py", line 8, in <module>
+from .transaction import Input, Transaction, TransactionLink, _fulfillment_from_details
+File "/home/user/repos/NexresGraphQL/resdb_driver/transaction.py", line 14, in <module>
+import base58
+ModuleNotFoundError: No module named 'base58'
+```
+- In the last line, you can run `pip install base58`
+- Keep running `python3 app.py` until you get to the broken dependency (ex: pysha3, sha3), then try running `sudo apt-get install python3.10-dev`
+- Hopefully, all your dependencies should be installed, and running `python3 app.py` will run the server!
+
+Start the app using:
+
+ python3 app.py
+
+This would be hosted on your local server to test the React App/Frontend.
+Also, this would give info on the console about the POST command, which are used to create an account. This consists of 3 stages: publicKey. AES encrypted private key and decrypted privateKey
+
+Note: To run Ubuntu virtual instance, open Command Prompt, then type `ubuntu2004` to open an instance
+
+# Serve GraphQL Using Nginx
+
+Install the Nginx web server package:
+
+ sudo apt-get install nginx -y
+
+Once the Nginx is installed, start and enable the Nginx service using the following command:
+
+ systemctl start nginx
+ systemctl enable nginx
+
+Activate your virtual environment and install Gunicorn and Flask:
+
+ source venv/bin/activate
+ pip install wheel
+ pip install gunicorn flask
+
+Verify whether Gunicorn can serve the application correctly using the command below:
+
+ gunicorn --bind 0.0.0.0:5000 wsgi:app
+
+If everything is fine, you should get the following output:
+
+ [2023-10-06 22:28:11 +0000] [24074] [INFO] Starting gunicorn 21.2.0
+ [2023-10-06 22:28:11 +0000] [24074] [INFO] Listening at: http://0.0.0.0:5000 (24074)
+ [2023-10-06 22:28:11 +0000] [24074] [INFO] Using worker: sync
+ [2023-10-06 22:28:11 +0000] [24075] [INFO] Booting worker with pid: 24075
+
+Press CTRL+C to stop the application. And deactivate the virtual environment.
+
+ deactivate
+
+Next, you will need to create a systemd unit file for the Flask application:
+
+ sudo vim /etc/systemd/system/flask.service
+
+Add the following lines:
+
+ [Unit]
+ Description=Gunicorn instance to serve Flask
+ After=network.target
+ [Service]
+ User=root
+ Group=www-data
+ WorkingDirectory=\{Your Absolute Path to this Folder\}
+ Environment="PATH=\{Your Absolute Path to this Folder\}/venv/bin"
+ ExecStart=\{Your Absolute Path to this Folder\}/venv/bin/gunicorn --bind 0.0.0.0:8000 wsgi:app
+ [Install]
+ WantedBy=multi-user.target
+
+Next, reload the systemd daemon with the following command:
+
+ sudo systemctl daemon-reload
+
+Next, start the flask service and enable it to start at system reboot:
+
+ sudo systemctl start flask
+ sudo systemctl enable flask
+
+Next, verify the status of the flask with the following command:
+
+ sudo systemctl status flask
+
+Output:
+
+ โ flask.service - Gunicorn instance to serve Flask
+ Loaded: loaded (/etc/systemd/system/flask.service; enabled; vendor preset: enabled)
+ Active: active (running) since Fri 2023-10-06 22:20:00 UTC; 14min ago
+ Main PID: 23745 (gunicorn)
+ Tasks: 2 (limit: 38067)
+ Memory: 40.6M
+ CGroup: /system.slice/flask.service
+ โโ23745 /home/ubuntu/ResilientDB-GraphQL/venv/bin/python3 /home/ubuntu/ResilientDB-GraphQL/venv/b>
+ โโ23747 /home/ubuntu/ResilientDB-GraphQL/venv/bin/python3 /home/ubuntu/ResilientDB-GraphQL/venv/b>
+
+
+Next, you will need to configure Nginx as a reverse proxy to serve the Flask application through port 80. To do so, create an Nginx virtual host configuration file:
+
+ sudo vim /etc/nginx/conf.d/flask.conf
+
+Add the following lines:
+
+ server {
+ listen 80;
+ server_name {The public IP address of your machine};
+ location / {
+ proxy_pass http://127.0.0.1:8000;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ }
+ }
+
+Save and close the file then verify the Nginx for any syntax error:
+
+ sudo nginx -t
+
+You should see the following output:
+
+ nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
+ nginx: configuration file /etc/nginx/nginx.conf test is successful
+
+Finally, restart the Nginx service to apply the changes:
+
+ sudo systemctl restart nginx
+
+Then, test with:
+
+ {The public IP address of your machine}/graphql
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docs/HTTP_SERVER.md b/ecosystem/ai-tools/mcp/graphq-llm/docs/HTTP_SERVER.md
new file mode 100644
index 00000000..51d0e861
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docs/HTTP_SERVER.md
@@ -0,0 +1,56 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+
+# HTTP Server Endpoints
+
+## Transactions
+Note that key-value pairs committed to ResilientDB through the API store the JSON object as the value. To get the intended value of the pair, simply access the value of the JSON object.
+
+### GET /v1/transactions
+Get all values
+
+### GET /v1/transactions/\<string>
+Get value of specific id
+
+### GET /v1/transactions/\<string>/\<string>
+Get values based on key range
+
+### POST /v1/transactions/commit
+Sets a new value for a key. Note that key-value pairs committed to ResilientDB through the API store the JSON object as the value. To get the intended value of the pair, simply access the value of the JSON object.
+
+Ex: `curl -X POST -d '{"id":"samplekey","value":"samplevalue"}' localhost:18000/v1/transactions/commit`
+
+## Blocks
+
+### GET /v1/blocks
+Retrieve all blocks
+
+### GET /v1/blocks/\<int>
+Retrieve all blocks, grouped in batch sizes of the int parameter
+
+### GET /v1/blocks/\<int>/\<int>
+Retrieve list of blocks within a range
+
+## Miscellaneous
+### GET /populatetable
+Used for the Explorer webpage
+
+## Todo
+Update endpoints to use URL query parameters
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docs/KV_SERVICE.md b/ecosystem/ai-tools/mcp/graphq-llm/docs/KV_SERVICE.md
new file mode 100644
index 00000000..5f9ea8d0
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docs/KV_SERVICE.md
@@ -0,0 +1,20 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+bazel build --cxxopt="-std=c++17" @nexres//service/tools/kv_service/api_tools:kv_service_tools
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docs/README.md b/ecosystem/ai-tools/mcp/graphq-llm/docs/README.md
new file mode 100644
index 00000000..3a48aa35
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docs/README.md
@@ -0,0 +1,373 @@
+**Title:** GraphQ-LLM: Building an AI Query Tutor for ResilientDB
+
+**Authors:** Aayusha Hadke, Celine John Philip, Sandhya Ghanathe, Sophie Quynn, Theodore Pan
+
+**Project:** ECS 265 DDS Mid-term Progress Report
+
+**Tags:** #ResilientDB, #GraphQL, #AI, #LLM, #Blockchain
+
+# GraphQ-LLM: AI-Powered GraphQL Query Tutor for ResilientDB
+
+## Introduction
+
+GraphQ-LLM is an intelligent AI assistant that helps developers learn, understand, and optimize GraphQL queries for ResilientDB. Built with Retrieval-Augmented Generation (RAG) and integrated with the ResilientApp ecosystem, it provides real-time explanations, suggestions, and performance insights for your GraphQL queries.
+
+---
+
+## ๐ฏ What is GraphQ-LLM?
+
+GraphQ-LLM is a comprehensive AI tutor that transforms how developers interact with GraphQL APIs. Instead of searching through documentation or trial-and-error query writing, developers can ask questions in natural language or paste their queries to get:
+
+- **Detailed Explanations**: Understand what each query does, how fields work, and what to expect in responses
+- **Efficiency Metrics**: See estimated execution time, resource usage, and complexity scores
+- **Documentation Context**: Access relevant ResilientDB and GraphQL documentation through semantic search
+
+---
+
+## ๐๏ธ How It Works
+
+### Architecture Overview
+
+GraphQ-LLM uses a three-tier architecture that combines AI, vector search, and real-time monitoring:
+
+```
+โโโโโโโโโโโโโโโโโโโ
+โ Nexus UI โ (Next.js Frontend)
+โ GraphQL Tutor โ
+โโโโโโโโโโฌโโโโโโโโโ
+ โ
+ โผ
+โโโโโโโโโโโโโโโโโโโ
+โ GraphQ-LLM โ (HTTP API Backend)
+โ Backend โ โข Explanation Service
+โ โ โข Optimization Service
+โ โ โข Efficiency Estimator
+โโโโโโโโโโฌโโโโโโโโโ
+ โ
+ โโโโโโดโโโโโ
+ โผ โผ
+โโโโโโโโโโ โโโโโโโโโโโโโโโ
+โResDB โ โ ResLens โ
+โGraphQL โ โ Monitoring โ
+โServer โ โ API โ
+โโโโโโโโโโ โโโโโโโโโโโโโโโ
+```
+
+### Core Components
+
+1. **RAG System (Retrieval-Augmented Generation)**
+ - Stores GraphQL documentation in ResilientDB with vector embeddings
+ - Uses semantic search to find relevant documentation chunks
+ - Combines retrieved context with LLM for accurate, contextual responses
+
+2. **AI Explanation Service**
+ - Detects whether input is a GraphQL query or natural language question
+ - For queries: Analyzes structure, fields, operations, and provides explanations
+ - For questions: Retrieves relevant docs and generates comprehensive answers
+
+3. **Efficiency Estimator**
+ - Calculates query complexity scores
+ - Estimates execution time and resource usage
+ - Provides real-time metrics when ResLens is enabled
+
+---
+
+## ๐ Key Features
+
+### 1. **Intelligent Query Explanation**
+
+Paste any GraphQL query and get a detailed breakdown:
+
+```graphql
+{
+ getTransaction(id: "123") {
+ id
+ asset
+ amount
+ }
+}
+```
+
+**Response includes:**
+- What the query does (in plain English)
+- How each field and operation works
+- Expected response format
+- Common use cases
+
+### 2. **Natural Language Q&A**
+
+Ask questions like:
+- "How do I retrieve a transaction by ID in GraphQL?"
+- "What is the difference between query and mutation?"
+- "How can I optimize my GraphQL queries?"
+
+The system retrieves relevant documentation and provides comprehensive answers with examples.
+
+### 3. **Efficiency Estimator**
+ - Calculates query complexity scores
+ - Estimates execution time and resource usage
+ - Provides real-time metrics when ResLens is enabled
+ - **Query Stats Integration**: Direct link to ResLens query statistics page from the efficiency tab
+
+### 4. **Performance Metrics**
+
+See efficiency scores, estimated execution times, and resource usage to understand query performance at a glance. The efficiency tab includes a "View Query Stats in ResLens" button that opens the ResLens query statistics dashboard in a new tab, allowing you to see historical query performance data.
+
+---
+
+## ๐ฆ Setup Overview
+
+GraphQ-LLM is fully dockerized for easy deployment. Here's what you need:
+
+### Prerequisites
+
+- **Docker & Docker Compose** - For running all services
+- **Node.js 18+** - For local development (optional)
+- **Gemini API Key** - For LLM capabilities (get from [Google AI Studio](https://makersuite.google.com/app/apikey))
+- **Nexus Repository** - Separate Next.js frontend (use the forked version with GraphQ-LLM integration: [sophiequynn/nexus](https://github.com/sophiequynn/nexus))
+- **ResLens Repositories** - Optional performance monitoring (use forked versions: [sophiequynn/incubator-resilientdb-ResLens](https://github.com/sophiequynn/incubator-resilientdb-ResLens) and [sophiequynn/incubator-resilientdb-ResLens-Middleware](https://github.com/sophiequynn/incubator-resilientdb-ResLens-Middleware))
+
+### Quick Start
+
+1. **Clone and Install**
+ ```bash
+ git clone <graphq-llm-repo>
+ cd graphq-llm
+ npm install
+ ```
+
+2. **Configure Environment**
+ ```bash
+ # Create .env file and add your Gemini API key
+ LLM_PROVIDER=gemini
+ LLM_API_KEY=your_gemini_api_key_here
+ RESILIENTDB_GRAPHQL_URL=http://localhost:5001/graphql
+ ```
+
+3. **Clone ResLens Forks (Optional - for performance monitoring)**
+ ```bash
+ # Clone ResLens Frontend
+ git clone https://github.com/sophiequynn/incubator-resilientdb-ResLens.git ResLens
+
+ # Clone ResLens Middleware
+ git clone https://github.com/sophiequynn/incubator-resilientdb-ResLens-Middleware.git ResLens-Middleware
+ ```
+ **Note:** These forks include Dockerfile and configuration updates for GraphQ-LLM integration.
+
+4. **Start Services with Docker**
+ ```bash
+ # Start ResilientDB (database + GraphQL server)
+ docker-compose -f docker-compose.dev.yml up -d resilientdb
+
+ # Start GraphQ-LLM Backend
+ docker-compose -f docker-compose.dev.yml up -d graphq-llm-backend
+
+ # (Optional) Start ResLens for performance monitoring
+ docker-compose -f docker-compose.dev.yml up -d reslens-middleware reslens-frontend
+ ```
+
+5. **Ingest Documentation**
+ ```bash
+ npm run ingest:graphql
+ # This loads all GraphQL docs into ResilientDB for RAG
+ ```
+
+6. **Set Up Nexus Frontend**
+ - Clone the forked Nexus repository (includes GraphQ-LLM integration):
+ ```bash
+ git clone https://github.com/sophiequynn/nexus.git
+ cd nexus
+ npm install
+ ```
+ - **Note:** This fork already includes all GraphQ-LLM integration files - no manual setup needed!
+ - Start with `npm run dev`
+
+7. **Access the Tool**
+ - **Tab-based UI:** Open `http://localhost:3000/graphql-tutor` in your browser
+ - **Chatbot UI:** Open `http://localhost:3000/graphql-tutor/chat` for a chat-style interface
+ - Start querying or asking questions!
+
+### Service Architecture
+
+All services run in Docker containers:
+
+- **ResilientDB** (Port 18000, 5001) - Database with GraphQL server
+- **GraphQ-LLM Backend** (Port 3001) - HTTP API for Nexus integration
+- **GraphQ-LLM MCP Server** - For MCP client integration (stdio transport)
+- **ResLens Middleware** (Port 3003) - Performance monitoring API (optional)
+- **ResLens Frontend** (Port 5173) - Performance monitoring UI (optional)
+- **Nexus Frontend** (Port 3000) - GraphQL Tutor UI
+
+### Access URLs
+- **Nexus Frontend:** http://localhost:3000
+- **GraphQL Tutor (Tab UI):** http://localhost:3000/graphql-tutor
+- **GraphQL Tutor (Chat UI):** http://localhost:3000/graphql-tutor/chat
+- **GraphQ-LLM Backend API:** http://localhost:3001
+- **ResLens Frontend:** http://localhost:5173
+- **ResLens Middleware API:** http://localhost:3003
+- **ResilientDB GraphQL:** http://localhost:5001/graphql
+
+---
+
+## ๐ก How It Helps Developers
+
+### Learning GraphQL
+
+New to GraphQL? GraphQ-LLM explains:
+- Query syntax and structure
+- Field selection and arguments
+- Mutations vs queries
+- Schema exploration
+- Best practices
+
+### Query Effeciency
+
+Working on performance? Get:
+- Complexity analysis
+- Field selection recommendations
+- Execution time estimates
+- Resource usage insights
+- Historical query comparisons (with ResLens)
+
+### Troubleshooting
+
+Stuck on an error? The system helps:
+- Understand query structure issues
+- Find relevant documentation
+- Compare with similar working queries
+- Get optimization suggestions
+
+---
+
+## ๐ง Technology Stack
+
+- **Backend**: Node.js/TypeScript with RAG architecture
+- **LLM**: Gemini 2.5 Flash Lite (configurable: DeepSeek, OpenAI, Anthropic, Hugging Face, local models)
+- **Embeddings**: Local (Xenova/all-MiniLM-L6-v2) or Hugging Face API
+- **Database**: ResilientDB for vector storage and document chunks
+- **Frontend**: Next.js (Nexus integration)
+- **Monitoring**: ResLens for real-time performance metrics
+- **Protocol**: MCP (Model Context Protocol) for secure AI tool integration
+
+---
+
+## ๐ Integration with ResilientApp Ecosystem
+
+GraphQ-LLM is designed to work seamlessly with:
+
+- **ResilientDB**: The underlying blockchain database
+- **Nexus**: The ResilientApp frontend platform
+- **ResLens**: Performance monitoring and profiling tools
+
+Together, these tools provide a complete development and monitoring experience for ResilientDB applications.
+
+---
+
+## ๐ Documentation & Resources
+
+Complete setup instructions are available in:
+- **TEAM_SETUP.md** - Step-by-step setup guide (includes Nexus fork setup)
+- **TEST_DOCKER_SERVICES.md** - Service verification guide
+- **QUERY_TUTOR_EXAMPLES.md** - Example queries and questions
+- **NEXUS_UI_EXTENSION_GUIDE.md** - Frontend integration guide (reference only - fork already includes integration)
+
+### ๐ฆ Fork Information
+
+GraphQ-LLM uses forked versions of external repositories that include GraphQ-LLM-specific modifications:
+
+#### **Nexus Fork**
+- **Fork Repository:** [sophiequynn/nexus](https://github.com/sophiequynn/nexus)
+- **Original Repository:** [ResilientApp/nexus](https://github.com/ResilientApp/nexus)
+- **Integration Status:** The fork includes all GraphQ-LLM UI components and API routes
+- **Setup:** Simply clone the fork - no additional modifications needed!
+
+#### **ResLens Forks**
+- **ResLens Frontend Fork:** [sophiequynn/incubator-resilientdb-ResLens](https://github.com/sophiequynn/incubator-resilientdb-ResLens)
+- **ResLens Middleware Fork:** [sophiequynn/incubator-resilientdb-ResLens-Middleware](https://github.com/sophiequynn/incubator-resilientdb-ResLens-Middleware)
+- **Original Repository:** [Apache ResLens](https://github.com/apache/incubator-resilientdb-ResLens)
+- **Integration Status:** Forks include Dockerfile updates, additional routes (CpuPage, MemoryPage, QueryStats), and improved configuration
+- **Setup:** Clone both forks - Docker Compose will use them automatically via absolute paths
+- **Note:** ResLens Frontend is configured to connect to middleware at `http://localhost:3003` (browser-accessible URL) rather than Docker service names
+
+---
+
+## ๐ Example Use Cases
+
+### Scenario 1: Learning GraphQL
+
+**Input:**
+```
+"What is GraphQL and how do I write a basic query?"
+```
+
+**Output:**
+Comprehensive explanation with examples, documentation references, and links to relevant guides.
+
+### Scenario 2: Explaining a Query
+
+**Input:**
+```graphql
+{
+ getTransaction(id: "abc123") {
+ id
+ asset
+ amount
+ }
+}
+```
+
+**Output:**
+- Detailed breakdown of what this query does
+- Explanation of each field
+- Expected response format
+- Use cases and examples
+
+### Scenario 3: Optimizing Performance
+
+**Input:**
+```graphql
+{
+ getTransaction(id: "test") {
+ id version amount uri type publicKey signerPublicKey operation metadata asset
+ }
+}
+```
+
+**Output:**
+- Efficiency score: 75/100
+- Optimization suggestions: "Consider selecting only needed fields"
+- Estimated execution time: 45ms
+- Complexity: Medium
+
+---
+
+## ๐ฆ Getting Started Checklist
+
+- [ ] Install Docker and Docker Compose
+- [ ] Clone GraphQ-LLM repository
+- [ ] Get Gemini API key from Google AI Studio
+- [ ] Configure `.env` file with API key
+- [ ] Start ResilientDB container
+- [ ] Start GraphQ-LLM Backend container
+- [ ] Ingest documentation (one-time setup)
+- [ ] Clone forked Nexus repository (`https://github.com/sophiequynn/nexus`)
+- [ ] Install Nexus dependencies (`npm install`)
+- [ ] Configure Nexus `.env` file (see `TEAM_SETUP.md`)
+- [ ] (Optional) Clone ResLens forks for performance monitoring
+- [ ] Start Nexus frontend (`npm run dev`)
+- [ ] Access `http://localhost:3000/graphql-tutor`
+- [ ] Start querying!
+
+---
+
+## ๐ฏ Conclusion
+
+GraphQ-LLM bridges the gap between complex GraphQL documentation and practical query writing. By combining AI-powered explanations, semantic search, and performance monitoring, it provides developers with an intelligent assistant that makes learning and optimizing GraphQL queries effortless.
+
+Whether you're a GraphQL beginner or an experienced developer looking to optimize queries, GraphQ-LLM offers the insights and recommendations you need to write better, faster, and more efficient queries for ResilientDB.
+
+**Ready to get started?** Follow the complete setup guide in `TEAM_SETUP.md` and begin exploring the power of AI-assisted GraphQL development!
+
+---
+
+*For detailed setup instructions, troubleshooting, and advanced configuration, see the complete documentation in the repository.*
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/cache-configuration.md b/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/cache-configuration.md
new file mode 100644
index 00000000..8175b52b
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/cache-configuration.md
@@ -0,0 +1,1227 @@
+# Apollo โ Cache Configuration
+
+> Source: [https://www.apollographql.com/docs/react/caching/cache-configuration/](https://www.apollographql.com/docs/react/caching/cache-configuration/)
+> Retrieved: 2025-11-19T07:03:02.935488Z
+
+[ Docs ](/docs)
+
+[ ](/docs)
+
+Search Apollo content (Cmd+K or /)
+
+[Launch GraphOS Studio ](https://studio.apollographql.com/signup?referrer=docs)
+
+[ Home Home ](/docs/)[ Schema Design Schema Design ](/docs/graphos/schema-design)[ Connectors Connectors ](/docs/graphos/connectors)[ GraphOS Platform GraphOS Platform ](/docs/graphos/platform)[ Routing Routing ](/docs/graphos/routing)[ Resources Resources ](/docs/graphos/resources)
+
+Apollo Client (Web) Apollo Client (Web)
+
+[Rover CLI](https://www.apollographql.com/docs/rover)[IDE Support](https://www.apollographql.com/docs/ide-support)[Apollo Client (Web)](https://www.apollographql.com/docs/react)[Apollo iOS](https://www.apollographql.com/docs/ios)[Apollo Kotlin](https://www.apollographql.com/docs/kotlin)[Apollo Server](https://www.apollographql.com/docs/apollo-server)[Apollo MCP Server](https://www.apollographql.com/docs/apollo-mcp-server)[Apollo Operator](https://www.apollographql.com/docs/apollo-operator)
+
+Apollo Client (Web) - v4 (latest)
+
+[Introduction](https://www.apollographql.com/docs/react)[Why Apollo Client?](https://www.apollographql.com/docs/react/why-apollo)[Get started](https://www.apollographql.com/docs/react/get-started)
+
+### Core concepts
+
+[Queries](https://www.apollographql.com/docs/react/data/queries)[Suspense](https://www.apollographql.com/docs/react/data/suspense)[Fragments](https://www.apollographql.com/docs/react/data/fragments)[Mutations](https://www.apollographql.com/docs/react/data/mutations)[TypeScript](https://www.apollographql.com/docs/react/data/typescript)[Refetching](https://www.apollographql.com/docs/react/data/refetching)[Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions)[Directive [...]
+
+### Caching
+
+[Overview](https://www.apollographql.com/docs/react/caching/overview)[Configuration](https://www.apollographql.com/docs/react/caching/cache-configuration)[Reading and writing](https://www.apollographql.com/docs/react/caching/cache-interaction)[Garbage collection and eviction](https://www.apollographql.com/docs/react/caching/garbage-collection)[Customizing field behavior](https://www.apollographql.com/docs/react/caching/cache-field-behavior)[Memory Management](https://www.apollographql.co [...]
+
+### Pagination
+
+[Overview](https://www.apollographql.com/docs/react/pagination/overview)[Core API](https://www.apollographql.com/docs/react/pagination/core-api)[Offset-based](https://www.apollographql.com/docs/react/pagination/offset-based)[Cursor-based](https://www.apollographql.com/docs/react/pagination/cursor-based)[keyArgs](https://www.apollographql.com/docs/react/pagination/key-args)
+
+### Local State
+
+[Overview](https://www.apollographql.com/docs/react/local-state/local-state-management)[Local-only fields](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies)[Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)[Local resolvers](https://www.apollographql.com/docs/react/local-state/local-resolvers)
+
+### Development & Testing
+
+[Developer tools](https://www.apollographql.com/docs/react/development-testing/developer-tooling)[GraphQL Codegen](https://www.apollographql.com/docs/react/development-testing/graphql-codegen)[Testing React components](https://www.apollographql.com/docs/react/development-testing/testing)[Schema-driven testing](https://www.apollographql.com/docs/react/development-testing/schema-driven-testing)[Mocking schema capabilities](https://www.apollographql.com/docs/react/development-testing/client [...]
+
+### Performance
+
+[Improving performance](https://www.apollographql.com/docs/react/performance/performance)[Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui)[Server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering)[Compiling queries with Babel](https://www.apollographql.com/docs/react/performance/babel)
+
+### Integrations
+
+[Using Apollo Client with your view layer](https://www.apollographql.com/docs/react/integrations/integrations)[Integrating with React Native](https://www.apollographql.com/docs/react/integrations/react-native)[Loading queries with Webpack](https://www.apollographql.com/docs/react/integrations/webpack)
+
+### Networking
+
+[Basic HTTP networking](https://www.apollographql.com/docs/react/networking/basic-http-networking)[Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking)[Authentication](https://www.apollographql.com/docs/react/networking/authentication)
+
+### API Reference
+
+### Core
+
+[ApolloClient](https://www.apollographql.com/docs/react/api/core/ApolloClient)[InMemoryCache](https://www.apollographql.com/docs/react/api/cache/InMemoryCache)[ObservableQuery](https://www.apollographql.com/docs/react/api/core/ObservableQuery)
+
+### Errors
+
+[CombinedGraphQLErrors](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors)[CombinedProtocolErrors](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors)[LinkError](https://www.apollographql.com/docs/react/api/errors/LinkError)[LocalStateError](https://www.apollographql.com/docs/react/api/errors/LocalStateError)[ServerError](https://www.apollographql.com/docs/react/api/errors/ServerError)[ServerParseError](https://www.apollographql.com/docs/re [...]
+
+### React
+
+[ApolloProvider](https://www.apollographql.com/docs/react/api/react/ApolloProvider)[useQuery](https://www.apollographql.com/docs/react/api/react/useQuery)[useLazyQuery](https://www.apollographql.com/docs/react/api/react/useLazyQuery)[useMutation](https://www.apollographql.com/docs/react/api/react/useMutation)[useSubscription](https://www.apollographql.com/docs/react/api/react/useSubscription)[useFragment](https://www.apollographql.com/docs/react/api/react/useFragment)[useApolloClient](ht [...]
+
+### Apollo Link
+
+[Overview](https://www.apollographql.com/docs/react/api/link/introduction)[ApolloLink](https://www.apollographql.com/docs/react/api/link/apollo-link)[BaseHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-http)[BaseBatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-batch-http)[BatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http)[BatchLink](https://www.apollographql.com/docs/react/api/link/apollo- [...]
+
+[Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)[Migrating to Apollo Client 4.0](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)[Versioning Policy](https://www.apollographql.com/docs/react/versioning-policy)
+
+Navigation controls
+
+## Schema Design
+
+[Overview](https://www.apollographql.com/docs/graphos/schema-design)
+
+### Federated Schemas
+
+[Overview](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/federation)[Schema Types](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/schema-types)[Schema Composition](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/composition)[Sharing Types (Value Types)](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/sharing-types)
+
+### Federation Reference
+
+[Federation Changelog](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/versions)[Federation Directives](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/directives)[Composition Rules](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/composition-rules)
+
+### Subgraph Reference
+
+[Federation Subgraphs Specification](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-spec)[Subgraph Specific Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-specific-fields)[Compatible Subgraph Libraries](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/compatible-subgraphs)
+
+### Development and Tooling
+
+[Query Plans](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/query-plans)[Composition Hints](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/hints)[Errors](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/errors)
+
+### From Federation 1 to 2
+
+[Upgrade Guide](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/moving-to-federation-2)[Federation 2 Backwards Compatibility](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/backward-compatibility)
+
+### Entities
+
+[Introduction](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/intro)
+
+### Entity Essentials
+
+[Entity Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/contribute-fields)[Advanced Keys](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/define-keys)[Entity Interfaces](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/interfaces)
+
+### Entity Guides
+
+[Entity Best Practices](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/best-practices)[Migrate Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/migrate-fields)[Resolve Another Subgraph's Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields)[Enforce Ownership](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entit [...]
+
+### Schema Design Guides
+
+### Schema Design Principles
+
+[Demand Oriented Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/demand-oriented-schema-design)[Naming Conventions](https://www.apollographql.com/docs/graphos/schema-design/guides/naming-conventions)[Namespacing](https://www.apollographql.com/docs/graphos/schema-design/guides/namespacing-by-separation-of-concerns)
+
+### Server-Driven UI
+
+[Basics](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/basics)[Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/schema-design)[Client Design](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/client-design)
+
+### Data Handling Techniques
+
+[Handling the N+1 Problem](https://www.apollographql.com/docs/graphos/schema-design/guides/handling-n-plus-one)[Nullability](https://www.apollographql.com/docs/graphos/schema-design/guides/nullability)[Interfaces](https://www.apollographql.com/docs/graphos/schema-design/guides/interfaces)[Response Type Pattern](https://www.apollographql.com/docs/graphos/schema-design/guides/response-type-pattern)[Errors as Data](https://www.apollographql.com/docs/graphos/schema-design/guides/errors-as-da [...]
+
+### Schema Development and Evolution
+
+[Mocking to Unblock Development](https://www.apollographql.com/docs/graphos/schema-design/guides/mocking)[Deprecations](https://www.apollographql.com/docs/graphos/schema-design/guides/deprecations)[Distributed Orchestration](https://www.apollographql.com/docs/graphos/schema-design/guides/distributed-orchestration)[Migrating from a Monolith](https://www.apollographql.com/docs/graphos/schema-design/guides/from-monolith)[Migrating from Schema Stitching](https://www.apollographql.com/docs/gr [...]
+
+## Connectors
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors)[Why use Connectors?](https://www.apollographql.com/docs/graphos/connectors/why-connectors)
+
+### Getting Started
+
+[Quickstart](https://www.apollographql.com/docs/graphos/connectors/getting-started)[API Requirements](https://www.apollographql.com/docs/graphos/connectors/getting-started/requirements)[Version Requirements](https://www.apollographql.com/docs/graphos/connectors/getting-started/version-requirements)
+
+### Connectors Library
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/library)
+
+### Prebuilt Connectors
+
+[Anthropic](https://www.apollographql.com/docs/graphos/connectors/library/anthropic)[Open AI](https://www.apollographql.com/docs/graphos/connectors/library/openai)[AWS DynamoDB](https://www.apollographql.com/docs/graphos/connectors/library/aws-dynamodb)[AWS Lambda](https://www.apollographql.com/docs/graphos/connectors/library/aws-lambda)[Strapi](https://www.apollographql.com/docs/graphos/connectors/library/strapi)[Stripe](https://www.apollographql.com/docs/graphos/connectors/library/stri [...]
+
+### Development and Tooling
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/tooling)[IDE Extensions](https://www.apollographql.com/docs/graphos/connectors/tooling/ide-extensions)[Using Rover](https://www.apollographql.com/docs/graphos/connectors/tooling/rover)[CLI Tools](https://www.apollographql.com/docs/graphos/connectors/tooling/cli-tools)[Mapping Playground](https://www.apollographql.com/docs/graphos/connectors/tooling/mapping-playground)
+
+### Making Requests
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/requests)[Request URLs](https://www.apollographql.com/docs/graphos/connectors/requests/url)[Request Headers](https://www.apollographql.com/docs/graphos/connectors/requests/headers)[Request Bodies](https://www.apollographql.com/docs/graphos/connectors/requests/body)[Batch Requests](https://www.apollographql.com/docs/graphos/connectors/requests/batching)[gRPC over JSON](https://www.apollographql.com/docs/graphos/connectors/re [...]
+
+### Handling Responses
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/responses)[Mapping Response Fields](https://www.apollographql.com/docs/graphos/connectors/responses/fields)[Error Handling](https://www.apollographql.com/docs/graphos/connectors/responses/error-handling)
+
+### Working with Entities
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/entities)[Common Patterns](https://www.apollographql.com/docs/graphos/connectors/entities/patterns)[Working Across Subgraphs](https://www.apollographql.com/docs/graphos/connectors/entities/across-subgraphs)
+
+### Mapping Language
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/mapping)[Handling Arrays](https://www.apollographql.com/docs/graphos/connectors/mapping/arrays)[Mapping Enums](https://www.apollographql.com/docs/graphos/connectors/mapping/enums)[Using Literal Values](https://www.apollographql.com/docs/graphos/connectors/mapping/literals)[Variable Reference](https://www.apollographql.com/docs/graphos/connectors/mapping/variables)[Method Reference](https://www.apollographql.com/docs/graphos [...]
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/deployment)[Configuration](https://www.apollographql.com/docs/graphos/connectors/deployment/configuration)
+
+### Deployment Configurations
+
+[Overriding Base URLs](https://www.apollographql.com/docs/graphos/connectors/deployment/overriding-base-urls)[Overriding Headers](https://www.apollographql.com/docs/graphos/connectors/deployment/overriding-headers)
+
+### Security Configurations
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/security)[Authentication](https://www.apollographql.com/docs/graphos/connectors/security/auth)[Request Limits](https://www.apollographql.com/docs/graphos/connectors/security/request-limits)[TLS](https://www.apollographql.com/docs/graphos/connectors/security/tls)
+
+### Performance Configurations
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/performance)[Traffic Shaping](https://www.apollographql.com/docs/graphos/connectors/performance/traffic-shaping)
+
+### Observability
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/observability)[Telemetry Configurations](https://www.apollographql.com/docs/graphos/connectors/observability/telemetry)
+
+### Testing
+
+[Testing Framework](https://www.apollographql.com/docs/graphos/connectors/testing)
+
+### Connectors Reference
+
+[Changelog](https://www.apollographql.com/docs/graphos/connectors/reference/changelog)[Directives](https://www.apollographql.com/docs/graphos/connectors/reference/directives)[Limitations](https://www.apollographql.com/docs/graphos/connectors/reference/limitations)
+
+[Troubleshooting](https://www.apollographql.com/docs/graphos/connectors/troubleshooting)
+
+## GraphOS Platform
+
+[Overview](https://www.apollographql.com/docs/graphos/platform)[Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox)
+
+### Schema Management
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management)
+
+### Schema Delivery
+
+### Publishing
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing)[Publish with Rover](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/rover)[Publish with the Platform API](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/platform-api)[Guide: Publish with GitHub Actions](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/guide-github)
+
+[Launches](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/launch)[Graph Artifacts](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/graph-artifacts)
+
+### Contracts
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/overview)[Create](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/create)[Usage Patterns](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/usage-patterns)[Reference](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/reference)
+
+### Schema Checks
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/checks)[Run Checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/run)[Custom Checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/custom)[Checks Configuration](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/configure)[GitHub Integration](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/gi [...]
+
+### Schema Linting
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/linting)[Linter Rules](https://www.apollographql.com/docs/graphos/platform/schema-management/linting/rules)
+
+### Schema Proposals
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals)[Configure](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/configure)[Create](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/create)[Review](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/review)[Implement](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/implement)
+
+### Explorer IDE
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/explorer)[Connect and Authenticate](https://www.apollographql.com/docs/graphos/platform/explorer/connect)[Operation Collections](https://www.apollographql.com/docs/graphos/platform/explorer/operation-collections)[Subscription Support](https://www.apollographql.com/docs/graphos/platform/explorer/subscription-support)[Embed](https://www.apollographql.com/docs/graphos/platform/explorer/embed)[Scripting](https://www.apollographql [...]
+
+### Graph Security
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/security/overview)[Persisted Queries](https://www.apollographql.com/docs/graphos/platform/security/persisted-queries)
+
+### Metrics and Insights
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/insights)
+
+### Metrics Collection and Forwarding
+
+[Sending Metrics to GraphOS](https://www.apollographql.com/docs/graphos/platform/insights/sending-operation-metrics)[Operation Signatures](https://www.apollographql.com/docs/graphos/platform/insights/operation-signatures)[Datadog Forwarding](https://www.apollographql.com/docs/graphos/platform/insights/datadog-forwarding)
+
+### Insights and Analysis
+
+[Operation Metrics](https://www.apollographql.com/docs/graphos/platform/insights/operation-metrics)[Field Usage](https://www.apollographql.com/docs/graphos/platform/insights/field-usage)[Error Diagnostics](https://www.apollographql.com/docs/graphos/platform/insights/errors)[Subgraph Metrics](https://www.apollographql.com/docs/graphos/platform/insights/subgraphs)[Segmenting by Client](https://www.apollographql.com/docs/graphos/platform/insights/client-segmentation)
+
+### Notifications and Alerts
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/insights/notifications)[Daily Reports](https://www.apollographql.com/docs/graphos/platform/insights/notifications/daily-reports)[Schema Changes](https://www.apollographql.com/docs/graphos/platform/insights/notifications/schema-changes)[Schema Proposals](https://www.apollographql.com/docs/graphos/platform/insights/notifications/schema-proposals)[Performance Alerts](https://www.apollographql.com/docs/graphos/platform/insights/n [...]
+
+### Access Management
+
+[Organizations](https://www.apollographql.com/docs/graphos/platform/access-management/org)[API Keys](https://www.apollographql.com/docs/graphos/platform/access-management/api-keys)[Members, Roles, and Permissions](https://www.apollographql.com/docs/graphos/platform/access-management/member-roles)[Audit Logs](https://www.apollographql.com/docs/graphos/platform/access-management/audit-log)
+
+### SSO
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/access-management/sso/overview)[Multi-Organization](https://www.apollographql.com/docs/graphos/platform/access-management/sso/multi-organization)
+
+### SAML
+
+[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-microsoft-entra-id)[Generic SAML Setup](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-integration-guide)
+
+### OIDC
+
+[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-microsoft-entra-id)[Generic OIDC Setup](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-integration-guide)
+
+### SCIM
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/access-management/scim)[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/scim/okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/scim/microsoft-entra-id)
+
+### Graph Management
+
+[Using Variants](https://www.apollographql.com/docs/graphos/platform/graph-management/variants)[Adding Subgraphs](https://www.apollographql.com/docs/graphos/platform/graph-management/add-subgraphs)[Managing Subgraphs](https://www.apollographql.com/docs/graphos/platform/graph-management/manage-subgraphs)[Updating Graph Components](https://www.apollographql.com/docs/graphos/platform/graph-management/updates)[Transferring Graphs](https://www.apollographql.com/docs/graphos/platform/graph-man [...]
+
+### Production Readiness
+
+[Production Readiness Checklist](https://www.apollographql.com/docs/graphos/platform/production-readiness/checklist)
+
+### Testing and Load Management
+
+[Overload Protection](https://www.apollographql.com/docs/graphos/platform/production-readiness/overload-protection)[Load Testing](https://www.apollographql.com/docs/graphos/platform/production-readiness/load-testing)[Testing with Federation](https://www.apollographql.com/docs/graphos/platform/production-readiness/testing-with-apollo-federation)
+
+### Environment and Deployment
+
+[Environment Best Practices](https://www.apollographql.com/docs/graphos/platform/production-readiness/environment-best-practices)[Schema Change Management](https://www.apollographql.com/docs/graphos/platform/production-readiness/change-management)[Updating Client Schema](https://www.apollographql.com/docs/graphos/platform/production-readiness/updating-client-schema)[Deployment Best Practices](https://www.apollographql.com/docs/graphos/platform/production-readiness/deployment-best-practices)
+
+[Platform Limits](https://www.apollographql.com/docs/graphos/platform/platform-limits)[GraphOS Platform API](https://www.apollographql.com/docs/graphos/platform/platform-api)[GraphOS MCP Tools](https://www.apollographql.com/docs/graphos/platform/graphos-mcp-tools)
+
+## Routing
+
+Apollo Router - v2 (latest)
+
+[Overview](https://www.apollographql.com/docs/graphos/routing)[Get Started](https://www.apollographql.com/docs/graphos/routing/get-started)[Request Lifecycle](https://www.apollographql.com/docs/graphos/routing/request-lifecycle)
+
+### Configuration
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/configuration/overview)[Environment Variable Reference](https://www.apollographql.com/docs/graphos/routing/configuration/envvars)[CLI Reference](https://www.apollographql.com/docs/graphos/routing/configuration/cli)[YAML Reference](https://www.apollographql.com/docs/graphos/routing/configuration/yaml)
+
+### Features
+
+### Security
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/security)[Persisted Queries](https://www.apollographql.com/docs/graphos/routing/security/persisted-queries)[Authorization](https://www.apollographql.com/docs/graphos/routing/security/authorization)
+
+### Authentication
+
+[JWT Authentication](https://www.apollographql.com/docs/graphos/routing/security/jwt)[Router Authentication](https://www.apollographql.com/docs/graphos/routing/security/router-authentication)[Subgraph Authentication](https://www.apollographql.com/docs/graphos/routing/security/subgraph-authentication)
+
+[CORS](https://www.apollographql.com/docs/graphos/routing/security/cors)[CSRF Prevention](https://www.apollographql.com/docs/graphos/routing/security/csrf)[TLS](https://www.apollographql.com/docs/graphos/routing/security/tls)[Request Limits](https://www.apollographql.com/docs/graphos/routing/security/request-limits)[Demand Control](https://www.apollographql.com/docs/graphos/routing/security/demand-control)
+
+### Observability
+
+### Studio Insights
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/graphos)[Operation Metrics Reporting](https://www.apollographql.com/docs/graphos/routing/observability/graphos/graphos-reporting)[Federated Trace Data](https://www.apollographql.com/docs/graphos/routing/observability/graphos/federated-trace-data)
+
+### Router Telemetry (OTEL)
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel)
+
+### Telemetry Data
+
+### Metrics
+
+[Instruments](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/instruments)[Standard Instruments](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/standard-instruments)
+
+[Events](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/events)
+
+### Traces
+
+[Spans](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/spans)[Standard Attributes](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/standard-attributes)
+
+[Conditions](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/conditions)[Selectors](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/selectors)
+
+### Usage Guides
+
+### Subgraph Observability
+
+[Subgraph Error Inclusion](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/subgraph-error-inclusion)[Debugging Subgraph Requests](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/debugging-subgraph-requests)[Instrumenting Subgraphs](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides [...]
+
+### Client Observability
+
+[Debugging Client Requests](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/debugging-client-requests)[Client ID Enforcement](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/client-id-enforcement)
+
+### Telemetry Exporters
+
+### Metrics Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/metrics-exporters/overview)[OTLP](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/metrics-exporters/otlp)
+
+### Log Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/log-exporters/overview)[Stdout](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/log-exporters/stdout)
+
+### Trace Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/trace-exporters/overview)[OTLP](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/trace-exporters/otlp)
+
+### APM Guides
+
+### Datadog
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog)
+
+### Connecting to Datadog
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog)[OpenTelemetry Collector](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/otel-collector)
+
+### Datadog Agent
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/datadog-agent/datadog-agent-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/datadog-agent/datadog-agent-traces)
+
+[Router Instrumentation](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/router-instrumentation)[Dashboard Template](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/observing-and-monitoring/dashboard-template)
+
+### New Relic
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/new-relic/new-relic-otlp-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/new-relic/new-relic-otlp-traces)
+
+### Prometheus
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/prometheus/prometheus-metrics)[Trace Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/prometheus/otel-traces-to-prometheus)
+
+### Zipkin
+
+[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/zipkin/zipkin-traces)
+
+### Jaeger
+
+[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/jaeger/jaeger-traces)
+
+### Dynatrace
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/dynatrace/dynatrace-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/dynatrace/dynatrace-traces)
+
+### Performance and Scaling
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/performance)
+
+### Response Caching
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/overview)[Quickstart](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/quickstart)[Invalidation](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/invalidation)[Customization](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/customization)[Observability](https://www.apollograp [...]
+
+[Traffic Shaping](https://www.apollographql.com/docs/graphos/routing/performance/traffic-shaping)[Query Batching](https://www.apollographql.com/docs/graphos/routing/performance/query-batching)
+
+### Client Features
+
+[APQ](https://www.apollographql.com/docs/graphos/routing/operations/apq)[HTTP Header Propagation](https://www.apollographql.com/docs/graphos/routing/header-propagation)[@defer](https://www.apollographql.com/docs/graphos/routing/operations/defer)
+
+### GraphQL Subscriptions
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/overview)[Configuration](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/configuration)[Callback Protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/callback-protocol)[Multipart Protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol)[Enable with API Gateway](https://www.apollographql.com/docs [...]
+
+[File Upload](https://www.apollographql.com/docs/graphos/routing/operations/file-upload)
+
+### Query Planning
+
+[Native Query Planner](https://www.apollographql.com/docs/graphos/routing/query-planning/native-query-planner)[Best Practices](https://www.apollographql.com/docs/graphos/routing/query-planning/query-planning-best-practices)[Caching](https://www.apollographql.com/docs/graphos/routing/query-planning/caching)
+
+### Customization
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/customization/overview)
+
+### Coprocessors
+
+[Coprocessor Configuration](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor)[Coprocessor Reference](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor/reference)
+
+### Rhai Scripts
+
+[Rhai Configuration](https://www.apollographql.com/docs/graphos/routing/customization/rhai)[Rhai API Reference](https://www.apollographql.com/docs/graphos/routing/customization/rhai/reference)
+
+### Custom Builds
+
+[Building a Binary](https://www.apollographql.com/docs/graphos/routing/customization/custom-binary)[Rust Plugins](https://www.apollographql.com/docs/graphos/routing/customization/native-plugins)
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/self-hosted)
+
+### Docker
+
+[Docker with the Apollo Runtime Container](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/docker)[Docker with Apollo Router](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/docker-router-only)
+
+### Kubernetes
+
+[Quickstart](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/quickstart)[Deploying with Extensibility](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/extensibility)[Enabling Metrics](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/metrics)[Other Considerations](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/other-con [...]
+
+### AWS
+
+[AWS ECS](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/aws)
+
+### Azure
+
+[Azure Container Apps](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/azure)
+
+### GCP
+
+[Google Cloud Run](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/gcp)
+
+### Managed Hosting
+
+[Railway](https://www.apollographql.com/docs/graphos/routing/self-hosted/managed-hosting/railway)[Render](https://www.apollographql.com/docs/graphos/routing/self-hosted/managed-hosting/render)
+
+### Apollo Cloud Routing
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/cloud)[Configuration](https://www.apollographql.com/docs/graphos/routing/cloud/configuration)[Secure Subgraphs](https://www.apollographql.com/docs/graphos/routing/cloud/secure-subgraphs)[Subscriptions](https://www.apollographql.com/docs/graphos/routing/cloud/subscriptions)[Serverless](https://www.apollographql.com/docs/graphos/routing/cloud/serverless)
+
+### Dedicated
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/cloud/dedicated)[Quickstart](https://www.apollographql.com/docs/graphos/routing/cloud/dedicated-quickstart)[Custom Domains](https://www.apollographql.com/docs/graphos/routing/cloud/custom-domains)[Throughput Guide](https://www.apollographql.com/docs/graphos/routing/cloud/throughput-guide)[Migrate to Dedicated](https://www.apollographql.com/docs/graphos/routing/cloud/migrate-to-dedicated)
+
+### AWS Lattice
+
+[Lattice Configuration](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-configuration)[Lattice Management](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-management)[Lattice Troubleshooting](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-troubleshooting)
+
+### Tools
+
+[Router Resource Estimator](https://www.apollographql.com/docs/graphos/routing/self-hosted/resource-estimator)[Health Checks](https://www.apollographql.com/docs/graphos/routing/self-hosted/health-checks)[Resource Management](https://www.apollographql.com/docs/graphos/routing/self-hosted/resource-management)
+
+### Releases
+
+[Changelogs](https://www.apollographql.com/docs/graphos/routing/changelog)[What's New in Router v2](https://www.apollographql.com/docs/graphos/routing/about-v2)[Upgrade from Router v1](https://www.apollographql.com/docs/graphos/routing/upgrade/from-router-v1)[Migrate from Gateway](https://www.apollographql.com/docs/graphos/routing/migration/from-gateway)[API Gateway Comparison](https://www.apollographql.com/docs/graphos/routing/router-api-gateway-comparison)
+
+### GraphOS Integration
+
+[GraphOS Plan License](https://www.apollographql.com/docs/graphos/routing/license)[GraphOS Plan Features](https://www.apollographql.com/docs/graphos/routing/graphos-features)[Apollo Uplink](https://www.apollographql.com/docs/graphos/routing/uplink)
+
+### Reference
+
+[Federation Version Support](https://www.apollographql.com/docs/graphos/routing/federation-version-support)[Errors](https://www.apollographql.com/docs/graphos/routing/errors)
+
+## Resources
+
+[Overview](https://www.apollographql.com/docs/graphos/resources)[Changelogs](https://www.apollographql.com/docs/graphos/resources/changelog)[Glossary](https://www.apollographql.com/docs/graphos/resources/glossary)[Examples](https://www.apollographql.com/docs/graphos/resources/solutions)
+
+### Release Policies
+
+[Apollo Feature Launch Stages](https://www.apollographql.com/docs/graphos/resources/feature-launch-stages)[GraphOS Router Release Lifecycle](https://www.apollographql.com/docs/graphos/resources/router-release-lifecycle)[Apollo Client Library Release Lifecycle](https://www.apollographql.com/docs/graphos/resources/client-library-release-lifecycle)
+
+### Architecture
+
+[Reference Architecture](https://www.apollographql.com/docs/graphos/resources/architecture)
+
+### Supergraph Architecture Framework
+
+[Overview](https://www.apollographql.com/docs/graphos/resources/saf)[Operational Excellence](https://www.apollographql.com/docs/graphos/resources/saf/operational-excellence)[Security](https://www.apollographql.com/docs/graphos/resources/saf/security)[Reliability](https://www.apollographql.com/docs/graphos/resources/saf/reliability)[Performance](https://www.apollographql.com/docs/graphos/resources/saf/performance)[Developer Experience](https://www.apollographql.com/docs/graphos/resources/ [...]
+
+### GraphQL Adoption Guides
+
+[GraphQL Adoption Patterns](https://www.apollographql.com/docs/graphos/resources/guides/graphql-adoption-patterns)[Using GraphQL for Abstraction](https://www.apollographql.com/docs/graphos/resources/guides/using-graphql-for-abstraction)[Supergraph Stewardship](https://www.apollographql.com/docs/graphos/resources/guides/supergraph-stewardship)
+
+## Rover CLI
+
+[Overview](https://www.apollographql.com/docs/rover)[Install](https://www.apollographql.com/docs/rover/getting-started)[Configure](https://www.apollographql.com/docs/rover/configuring)[Proxy Configuration](https://www.apollographql.com/docs/rover/proxy)[CI/CD](https://www.apollographql.com/docs/rover/ci-cd)[Conventions](https://www.apollographql.com/docs/rover/conventions)[Privacy and Data Collection](https://www.apollographql.com/docs/rover/privacy)[Contributing](https://www.apollograph [...]
+
+### Commands
+
+[api-key](https://www.apollographql.com/docs/rover/commands/api-key)[cloud](https://www.apollographql.com/docs/rover/commands/cloud)[config](https://www.apollographql.com/docs/rover/commands/config)[connector](https://www.apollographql.com/docs/rover/commands/connectors)[contract](https://www.apollographql.com/docs/rover/commands/contracts)[dev](https://www.apollographql.com/docs/rover/commands/dev)[explain](https://www.apollographql.com/docs/rover/commands/explain)[graph](https://www.ap [...]
+
+### The Apollo CLI (deprecated)
+
+[Installation](https://www.apollographql.com/docs/rover/apollo-cli)[Validating Client Operations](https://www.apollographql.com/docs/rover/validating-client-operations)[Moving to Rover](https://www.apollographql.com/docs/rover/migration)
+
+## IDE Support
+
+### IDE Support
+
+[Overview](https://www.apollographql.com/docs/ide-support)[Visual Studio Code](https://www.apollographql.com/docs/ide-support/vs-code)[JetBrains IDEs](https://www.apollographql.com/docs/ide-support/jetbrains)[Vim/NeoVim](https://www.apollographql.com/docs/ide-support/vim)
+
+## Apollo Client (Web)
+
+Apollo Client (Web) - v4 (latest)
+
+[Introduction](https://www.apollographql.com/docs/react)[Why Apollo Client?](https://www.apollographql.com/docs/react/why-apollo)[Get started](https://www.apollographql.com/docs/react/get-started)
+
+### Core concepts
+
+[Queries](https://www.apollographql.com/docs/react/data/queries)[Suspense](https://www.apollographql.com/docs/react/data/suspense)[Fragments](https://www.apollographql.com/docs/react/data/fragments)[Mutations](https://www.apollographql.com/docs/react/data/mutations)[TypeScript](https://www.apollographql.com/docs/react/data/typescript)[Refetching](https://www.apollographql.com/docs/react/data/refetching)[Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions)[Directive [...]
+
+### Caching
+
+[Overview](https://www.apollographql.com/docs/react/caching/overview)[Configuration](https://www.apollographql.com/docs/react/caching/cache-configuration)[Reading and writing](https://www.apollographql.com/docs/react/caching/cache-interaction)[Garbage collection and eviction](https://www.apollographql.com/docs/react/caching/garbage-collection)[Customizing field behavior](https://www.apollographql.com/docs/react/caching/cache-field-behavior)[Memory Management](https://www.apollographql.co [...]
+
+### Pagination
+
+[Overview](https://www.apollographql.com/docs/react/pagination/overview)[Core API](https://www.apollographql.com/docs/react/pagination/core-api)[Offset-based](https://www.apollographql.com/docs/react/pagination/offset-based)[Cursor-based](https://www.apollographql.com/docs/react/pagination/cursor-based)[keyArgs](https://www.apollographql.com/docs/react/pagination/key-args)
+
+### Local State
+
+[Overview](https://www.apollographql.com/docs/react/local-state/local-state-management)[Local-only fields](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies)[Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)[Local resolvers](https://www.apollographql.com/docs/react/local-state/local-resolvers)
+
+### Development & Testing
+
+[Developer tools](https://www.apollographql.com/docs/react/development-testing/developer-tooling)[GraphQL Codegen](https://www.apollographql.com/docs/react/development-testing/graphql-codegen)[Testing React components](https://www.apollographql.com/docs/react/development-testing/testing)[Schema-driven testing](https://www.apollographql.com/docs/react/development-testing/schema-driven-testing)[Mocking schema capabilities](https://www.apollographql.com/docs/react/development-testing/client [...]
+
+### Performance
+
+[Improving performance](https://www.apollographql.com/docs/react/performance/performance)[Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui)[Server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering)[Compiling queries with Babel](https://www.apollographql.com/docs/react/performance/babel)
+
+### Integrations
+
+[Using Apollo Client with your view layer](https://www.apollographql.com/docs/react/integrations/integrations)[Integrating with React Native](https://www.apollographql.com/docs/react/integrations/react-native)[Loading queries with Webpack](https://www.apollographql.com/docs/react/integrations/webpack)
+
+### Networking
+
+[Basic HTTP networking](https://www.apollographql.com/docs/react/networking/basic-http-networking)[Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking)[Authentication](https://www.apollographql.com/docs/react/networking/authentication)
+
+### API Reference
+
+### Core
+
+[ApolloClient](https://www.apollographql.com/docs/react/api/core/ApolloClient)[InMemoryCache](https://www.apollographql.com/docs/react/api/cache/InMemoryCache)[ObservableQuery](https://www.apollographql.com/docs/react/api/core/ObservableQuery)
+
+### Errors
+
+[CombinedGraphQLErrors](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors)[CombinedProtocolErrors](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors)[LinkError](https://www.apollographql.com/docs/react/api/errors/LinkError)[LocalStateError](https://www.apollographql.com/docs/react/api/errors/LocalStateError)[ServerError](https://www.apollographql.com/docs/react/api/errors/ServerError)[ServerParseError](https://www.apollographql.com/docs/re [...]
+
+### React
+
+[ApolloProvider](https://www.apollographql.com/docs/react/api/react/ApolloProvider)[useQuery](https://www.apollographql.com/docs/react/api/react/useQuery)[useLazyQuery](https://www.apollographql.com/docs/react/api/react/useLazyQuery)[useMutation](https://www.apollographql.com/docs/react/api/react/useMutation)[useSubscription](https://www.apollographql.com/docs/react/api/react/useSubscription)[useFragment](https://www.apollographql.com/docs/react/api/react/useFragment)[useApolloClient](ht [...]
+
+### Apollo Link
+
+[Overview](https://www.apollographql.com/docs/react/api/link/introduction)[ApolloLink](https://www.apollographql.com/docs/react/api/link/apollo-link)[BaseHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-http)[BaseBatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-batch-http)[BatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http)[BatchLink](https://www.apollographql.com/docs/react/api/link/apollo- [...]
+
+[Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)[Migrating to Apollo Client 4.0](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)[Versioning Policy](https://www.apollographql.com/docs/react/versioning-policy)
+
+## Apollo iOS
+
+Apollo iOS - v2 (latest)
+
+[Introduction](https://www.apollographql.com/docs/ios)[Get Started](https://www.apollographql.com/docs/ios/get-started)
+
+### Project Configuration
+
+[Introduction](https://www.apollographql.com/docs/ios/project-configuration/intro)[1\. Project Modularization](https://www.apollographql.com/docs/ios/project-configuration/modularization)[2\. Schema Types](https://www.apollographql.com/docs/ios/project-configuration/schema-types)[3\. Operation Models](https://www.apollographql.com/docs/ios/project-configuration/operation-models)[SDK components](https://www.apollographql.com/docs/ios/project-configuration/sdk-components)
+
+### Migration Guides
+
+[v2.0](https://www.apollographql.com/docs/ios/migrations/2.0)
+
+### Tutorial
+
+[Code Generation](https://www.apollographql.com/docs/ios/tutorial/codegen-getting-started)
+
+### Build a project with Apollo
+
+[Introduction](https://www.apollographql.com/docs/ios/tutorial/tutorial-introduction)[1\. Configure your project](https://www.apollographql.com/docs/ios/tutorial/tutorial-configure-project)[2\. Add the GraphQL schema](https://www.apollographql.com/docs/ios/tutorial/tutorial-add-graphql-schema)[3\. Write your first query](https://www.apollographql.com/docs/ios/tutorial/tutorial-write-your-first-query)[4\. Running code generation](https://www.apollographql.com/docs/ios/tutorial/tutorial-ru [...]
+
+[API Reference](https://www.apollographql.com/docs/ios/docc/documentation)
+
+### Code Generation
+
+[Introduction](https://www.apollographql.com/docs/ios/code-generation/introduction)[The Codegen CLI](https://www.apollographql.com/docs/ios/code-generation/codegen-cli)[Configuration](https://www.apollographql.com/docs/ios/code-generation/codegen-configuration)[Downloading a Schema](https://www.apollographql.com/docs/ios/code-generation/downloading-schema)[Running Code Generation in Swift Code](https://www.apollographql.com/docs/ios/code-generation/run-codegen-in-swift-code)[Code Generat [...]
+
+### Fetching
+
+[Fetching Data](https://www.apollographql.com/docs/ios/fetching/fetching-data)
+
+### Operations
+
+[Queries](https://www.apollographql.com/docs/ios/fetching/queries)[Mutations](https://www.apollographql.com/docs/ios/fetching/mutations)[Subscriptions](https://www.apollographql.com/docs/ios/fetching/subscriptions)[Fragments](https://www.apollographql.com/docs/ios/fetching/fragments)
+
+[Operation Arguments](https://www.apollographql.com/docs/ios/fetching/operation-arguments)[Error Handling](https://www.apollographql.com/docs/ios/fetching/error-handling)[Type Conditions](https://www.apollographql.com/docs/ios/fetching/type-conditions)[Custom Scalars](https://www.apollographql.com/docs/ios/custom-scalars)[Persisted Queries](https://www.apollographql.com/docs/ios/fetching/persisted-queries)[@defer support](https://www.apollographql.com/docs/ios/fetching/defer)
+
+### Caching
+
+[Introduction](https://www.apollographql.com/docs/ios/caching/introduction)[Setup](https://www.apollographql.com/docs/ios/caching/cache-setup)[Direct Cache Access](https://www.apollographql.com/docs/ios/caching/cache-transactions)[Custom Cache Keys](https://www.apollographql.com/docs/ios/caching/cache-key-resolution)[Programmatic Cache Keys](https://www.apollographql.com/docs/ios/caching/programmatic-cache-keys)
+
+### Networking
+
+[Creating a Client](https://www.apollographql.com/docs/ios/networking/client-creation)
+
+### Pagination
+
+[Introduction](https://www.apollographql.com/docs/ios/pagination/introduction)[Using Custom Response Models](https://www.apollographql.com/docs/ios/pagination/custom-types)[Directional Pagination](https://www.apollographql.com/docs/ios/pagination/directional-pagers)[Multi-query Pagination](https://www.apollographql.com/docs/ios/pagination/multi-query)
+
+### Development & Testing
+
+[Test Mocks](https://www.apollographql.com/docs/ios/testing/test-mocks)[Including Apollo as an XCFramework](https://www.apollographql.com/docs/ios/development/using-xcframework)
+
+### Advanced
+
+[File Uploads](https://www.apollographql.com/docs/ios/advanced/file-uploads)[Request Chain Customization](https://www.apollographql.com/docs/ios/advanced/request-chain)[Client Directives](https://www.apollographql.com/docs/ios/client-directives)
+
+## Apollo Kotlin
+
+Apollo Kotlin - v4 (latest)
+
+[Get Started](https://www.apollographql.com/docs/kotlin)[Migrating to v4](https://www.apollographql.com/docs/kotlin/migration/4.0)[Modules](https://www.apollographql.com/docs/kotlin/essentials/modules)[Evolution policy](https://www.apollographql.com/docs/kotlin/essentials/evolution)[Tutorial](https://www.apollographql.com/tutorials/apollo-kotlin-android-part1)[Kdoc](https://apollographql.github.io/apollo-kotlin/kdoc/older/4.2.0/)[Changelog](https://github.com/apollographql/apollo-kotlin/ [...]
+
+### Configuration
+
+[Gradle plugin configuration](https://www.apollographql.com/docs/kotlin/advanced/plugin-configuration)[Gradle plugin recipes](https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes)[Multi Modules](https://www.apollographql.com/docs/kotlin/advanced/multi-modules)[File types](https://www.apollographql.com/docs/kotlin/essentials/file-types)[Client Awareness](https://www.apollographql.com/docs/kotlin/advanced/client-awareness)
+
+### Fetching
+
+[Queries](https://www.apollographql.com/docs/kotlin/essentials/queries)[Mutations](https://www.apollographql.com/docs/kotlin/essentials/mutations)[Subscriptions](https://www.apollographql.com/docs/kotlin/essentials/subscriptions)[GraphQL variables](https://www.apollographql.com/docs/kotlin/advanced/operation-variables)[Error handling](https://www.apollographql.com/docs/kotlin/essentials/errors)[Custom scalars](https://www.apollographql.com/docs/kotlin/essentials/custom-scalars)[Fragments [...]
+
+### Caching
+
+[Introduction](https://www.apollographql.com/docs/kotlin/caching/introduction)[Normalized caches](https://www.apollographql.com/docs/kotlin/caching/normalized-cache)[Declarative cache IDs](https://www.apollographql.com/docs/kotlin/caching/declarative-ids)[Programmatic cache IDs](https://www.apollographql.com/docs/kotlin/caching/programmatic-ids)[Watching cached data](https://www.apollographql.com/docs/kotlin/caching/query-watchers)[ApolloStore](https://www.apollographql.com/docs/kotlin/c [...]
+
+### Networking
+
+[Interceptors](https://www.apollographql.com/docs/kotlin/advanced/interceptors-http)[Custom HTTP clients](https://www.apollographql.com/docs/kotlin/advanced/http-engine)[Using the models without apollo-runtime](https://www.apollographql.com/docs/kotlin/advanced/no-runtime)[Authentication](https://www.apollographql.com/docs/kotlin/advanced/authentication)[WebSocket errors](https://www.apollographql.com/docs/kotlin/advanced/websocket-errors)[Batching operations](https://www.apollographql.c [...]
+
+### Development & Testing
+
+[Testing overview](https://www.apollographql.com/docs/kotlin/testing/overview)[Mocking HTTP responses](https://www.apollographql.com/docs/kotlin/testing/mocking-http-responses)[Mocking GraphQL responses](https://www.apollographql.com/docs/kotlin/testing/mocking-graphql-responses)[Data builders](https://www.apollographql.com/docs/kotlin/testing/data-builders)[Android Studio plugin](https://www.apollographql.com/docs/kotlin/testing/android-studio-plugin)[Apollo Debug Server](https://www.ap [...]
+
+### Advanced
+
+[Uploading files](https://www.apollographql.com/docs/kotlin/advanced/upload)[Monitoring the network state](https://www.apollographql.com/docs/kotlin/advanced/network-connectivity)[Handling nullability](https://www.apollographql.com/docs/kotlin/advanced/nullability)[Experimental WebSockets](https://www.apollographql.com/docs/kotlin/advanced/experimental-websockets)[Using aliases](https://www.apollographql.com/docs/kotlin/advanced/using-aliases)[Using Java](https://www.apollographql.com/do [...]
+
+## Apollo Server
+
+Apollo Server - v4รขยยv5 (latest)
+
+[Introduction](https://www.apollographql.com/docs/apollo-server)[Get started](https://www.apollographql.com/docs/apollo-server/getting-started)
+
+### New in v4 and v5
+
+[Migrating from Apollo Server 4](https://www.apollographql.com/docs/apollo-server/migration)[Migrating from Apollo Server 3](https://www.apollographql.com/docs/apollo-server/migration-from-v3)[Previous versions](https://www.apollographql.com/docs/apollo-server/previous-versions)[Changelog](https://github.com/apollographql/apollo-server/blob/main/packages/server/CHANGELOG.md)
+
+### Defining a Schema
+
+[Schema basics](https://www.apollographql.com/docs/apollo-server/schema/schema)[Unions and interfaces](https://www.apollographql.com/docs/apollo-server/schema/unions-interfaces)[Custom scalars](https://www.apollographql.com/docs/apollo-server/schema/custom-scalars)[Directives](https://www.apollographql.com/docs/apollo-server/schema/directives)
+
+### Resolving Operations
+
+[Resolvers](https://www.apollographql.com/docs/apollo-server/data/resolvers)[Sharing context](https://www.apollographql.com/docs/apollo-server/data/context)[Error handling](https://www.apollographql.com/docs/apollo-server/data/errors)[Subscriptions](https://www.apollographql.com/docs/apollo-server/data/subscriptions)
+
+### Fetching Data
+
+[Overview](https://www.apollographql.com/docs/apollo-server/data/fetching-data)[REST APIs](https://www.apollographql.com/docs/apollo-server/data/fetching-rest)
+
+### Web Frameworks
+
+[Integrations](https://www.apollographql.com/docs/apollo-server/integrations/integration-index)[Building integrations](https://www.apollographql.com/docs/apollo-server/integrations/building-integrations)[MERN stack tutorial](https://www.apollographql.com/docs/apollo-server/integrations/mern)
+
+### Development Workflow
+
+[Build and run queries](https://www.apollographql.com/docs/apollo-server/workflow/build-run-queries)[Request format](https://www.apollographql.com/docs/apollo-server/workflow/requests)[Generating TS types](https://www.apollographql.com/docs/apollo-server/workflow/generate-types)[Mocking](https://www.apollographql.com/docs/apollo-server/testing/mocking)[Integration testing](https://www.apollographql.com/docs/apollo-server/testing/testing)[Apollo Studio Explorer](https://www.apollographql. [...]
+
+### Performance
+
+[Caching](https://www.apollographql.com/docs/apollo-server/performance/caching)[Cache backends](https://www.apollographql.com/docs/apollo-server/performance/cache-backends)[Response Cache Eviction](https://www.apollographql.com/docs/apollo-server/performance/response-cache-eviction)[Automatic persisted queries](https://www.apollographql.com/docs/apollo-server/performance/apq)
+
+### Security
+
+[Auth](https://www.apollographql.com/docs/apollo-server/security/authentication)[CORS](https://www.apollographql.com/docs/apollo-server/security/cors)[Terminating SSL](https://www.apollographql.com/docs/apollo-server/security/terminating-ssl)[Proxy configuration](https://www.apollographql.com/docs/apollo-server/security/proxy-configuration)
+
+### Deployment
+
+[Lambda](https://www.apollographql.com/docs/apollo-server/deployment/lambda)[Heroku](https://www.apollographql.com/docs/apollo-server/deployment/heroku)
+
+### Monitoring
+
+[Metrics and logging](https://www.apollographql.com/docs/apollo-server/monitoring/metrics)[Health checks](https://www.apollographql.com/docs/apollo-server/monitoring/health-checks)
+
+### API Reference
+
+[ApolloServer](https://www.apollographql.com/docs/apollo-server/api/apollo-server)[startStandaloneServer](https://www.apollographql.com/docs/apollo-server/api/standalone)[expressMiddleware](https://www.apollographql.com/docs/apollo-server/api/express-middleware)
+
+### Plugins
+
+[Overview](https://www.apollographql.com/docs/apollo-server/builtin-plugins)
+
+### Built-in
+
+[Usage reporting](https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting)[Schema reporting](https://www.apollographql.com/docs/apollo-server/api/plugin/schema-reporting)[Inline trace](https://www.apollographql.com/docs/apollo-server/api/plugin/inline-trace)[Drain HTTP server](https://www.apollographql.com/docs/apollo-server/api/plugin/drain-http-server)[Cache control](https://www.apollographql.com/docs/apollo-server/api/plugin/cache-control)[Landing pages](https://ww [...]
+
+### Custom
+
+[Creating plugins](https://www.apollographql.com/docs/apollo-server/integrations/plugins)[Event reference](https://www.apollographql.com/docs/apollo-server/integrations/plugins-event-reference)
+
+### Using with Federation
+
+### As a subgraph
+
+[Setup](https://www.apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup)[@apollo/subgraph reference](https://www.apollographql.com/docs/apollo-server/using-federation/api/apollo-subgraph)
+
+### As a gateway
+
+[Setup](https://www.apollographql.com/docs/apollo-server/using-federation/apollo-gateway-setup)[Gateway performance](https://www.apollographql.com/docs/apollo-server/using-federation/gateway-performance)[@apollo/gateway reference](https://www.apollographql.com/docs/apollo-server/using-federation/api/apollo-gateway)
+
+## Apollo MCP Server
+
+Apollo MCP Server - v1 (latest)
+
+[Overview](https://www.apollographql.com/docs/apollo-mcp-server)[Quickstart](https://www.apollographql.com/docs/apollo-mcp-server/quickstart)[Define tools](https://www.apollographql.com/docs/apollo-mcp-server/define-tools)
+
+### Configuration
+
+[YAML Config Reference](https://www.apollographql.com/docs/apollo-mcp-server/config-file)[Custom Scalars](https://www.apollographql.com/docs/apollo-mcp-server/custom-scalars)
+
+[Run the MCP Server](https://www.apollographql.com/docs/apollo-mcp-server/run)[Debugging](https://www.apollographql.com/docs/apollo-mcp-server/debugging)
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/apollo-mcp-server/deploy)[Health Checks](https://www.apollographql.com/docs/apollo-mcp-server/health-checks)[CORS](https://www.apollographql.com/docs/apollo-mcp-server/cors)
+
+[Authorization](https://www.apollographql.com/docs/apollo-mcp-server/auth)[Telemetry](https://www.apollographql.com/docs/apollo-mcp-server/telemetry)[Best Practices](https://www.apollographql.com/docs/apollo-mcp-server/best-practices)[Licensing](https://www.apollographql.com/docs/apollo-mcp-server/licensing)[Limitations](https://www.apollographql.com/docs/apollo-mcp-server/limitations)
+
+### Guides
+
+[Authorization with Auth0](https://www.apollographql.com/docs/apollo-mcp-server/guides/auth-auth0)
+
+## Apollo Operator
+
+[Overview](https://www.apollographql.com/docs/apollo-operator)
+
+### Getting Started
+
+[Install Operator](https://www.apollographql.com/docs/apollo-operator/get-started/install-operator)[Add Subgraphs](https://www.apollographql.com/docs/apollo-operator/get-started/add-subgraphs)[Deploy Supergraphs](https://www.apollographql.com/docs/apollo-operator/get-started/deploy-supergraph)
+
+### Kubernetes Resources
+
+### Supergraph
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/resources/supergraph)[Autoscaling your Supergraphs](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/autoscalers)[Supergraph podTemplate](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/pod_template)[Supergraph networking](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/networking)
+
+[SupergraphSchema](https://www.apollographql.com/docs/apollo-operator/resources/supergraphschema)[SupergraphSet](https://www.apollographql.com/docs/apollo-operator/resources/supergraphset)[Subgraph](https://www.apollographql.com/docs/apollo-operator/resources/subgraph)
+
+### Workflows
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/workflows)[Single Cluster Setup](https://www.apollographql.com/docs/apollo-operator/workflows/single-cluster)[Multi-Cluster & Hybrid Setup](https://www.apollographql.com/docs/apollo-operator/workflows/multi-cluster)[Deploy Only](https://www.apollographql.com/docs/apollo-operator/workflows/deploy-only)
+
+### Configuration
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/configuration)[Telemetry](https://www.apollographql.com/docs/apollo-operator/configuration/telemetry)[Controllers](https://www.apollographql.com/docs/apollo-operator/configuration/controllers)[OCI](https://www.apollographql.com/docs/apollo-operator/configuration/oci)[Private Registries](https://www.apollographql.com/docs/apollo-operator/configuration/private-registries)
+
+[Security Best Practices](https://www.apollographql.com/docs/apollo-operator/security-best-practices)
+
+[Apollo Client (Web)](react)
+
+##
+
+On this page
+
+Copy as MD
+
+ * Initialization
+
+ * Configuration options
+
+ * Customizing cache IDs
+
+ * Calculating an object's cache ID
+
+ * Customizing identifier generation globally
+
+ * Customizing Type Policies
+
+ * Disabling normalization
+
+ * TypePolicy fields
+
+ * Overriding root operation types (uncommon)
+
+ * The fields property
+
+
+
+
+[ Home ](/docs/)
+
+/ [ Apollo Client (Web) ](/docs/react)
+
+/ [ Caching ](/docs/react/caching/overview)
+
+/ [ Configuration ](/docs/react/caching/cache-configuration)
+
+[ Apollo Client (Web) / ](/docs/react)
+
+[ Caching ](/docs/react/caching/overview)
+
+# Configuring the Apollo Client cache
+
+Ask AI a question about this page
+
+Ask with ChatGPT
+
+Ask with ClaudeAsk with ChatGPT
+
+* * *
+
+This article describes cache setup and configuration. To learn how to interact with cached data, see [Reading and writing data to the cache](https://www.apollographql.com/docs/react/caching/cache-interaction).
+
+## Initialization
+
+Create an `InMemoryCache` object and provide it to the `ApolloClient` constructor, like so:
+
+TypeScript
+
+copy
+
+
+ 1import { InMemoryCache, ApolloClient } from "@apollo/client";
+ 2
+ 3const client = new ApolloClient({
+ 4 // ...other arguments...
+ 5 cache: new InMemoryCache(options),
+ 6});
+
+The `InMemoryCache` constructor accepts a variety of [configuration options](https://www.apollographql.com/docs/react/caching/cache-configuration#configuration-options).
+
+## Configuration options
+
+You can configure the cache's behavior to better suit your application. For example, you can:
+
+ * Customize the format of a particular type's [cache ID](https://www.apollographql.com/docs/react/caching/cache-configuration#customizing-cache-ids)
+
+ * Customize the storage and retrieval of [individual fields](https://www.apollographql.com/docs/react/caching/cache-field-behavior/)
+
+ * Define polymorphic type relationships for [fragment matching](https://www.apollographql.com/docs/react/caching/cache-configuration#possibletypes)
+
+ * Define patterns for [pagination](https://www.apollographql.com/docs/react/pagination/overview/)
+
+ * Manage client-side [local state](https://www.apollographql.com/docs/react/local-state/local-state-management/)
+
+
+
+
+To customize cache behavior, you provide a configuration object to the `InMemoryCache` constructor. This object supports the following fields:
+
+Name /
+Type | Description
+---|---
+
+###### `resultCaching`
+
+`Boolean`| If `true`, the cache returns an identical (`===`) response object for every execution of the same query, as long as the underlying data remains unchanged. This helps you detect changes to a query's result.The default value is `true`.
+
+###### `resultCacheMaxSize`
+
+`number`| The limit of the number of result objects that will be retained in memory to speed up repeated reads to the cache.The default value is `Math.pow(2, 16)`.
+
+###### `possibleTypes`
+
+`Object`| Include this object to define polymorphic relationships between your schema's types. Doing so enables you to look up cached data by interface or by union.Each key in the object is the `__typename` of an interface or union, and the corresponding value is an array of the `__typename`s of the types that belong to that union or implement that interface.For an example, see [Defining `possibleTypes` manually](https://www.apollographql.com/docs/react/data/fragments/#defining-possiblet [...]
+
+###### `typePolicies`
+
+`Object`| Include this object to customize the cache's behavior on a type-by-type basis.Each key in the object is the `__typename` of a type to customize, and the corresponding value is a [`TypePolicy` object](https://www.apollographql.com/docs/react/caching/cache-configuration#typepolicy-fields).
+
+###### `dataIdFromObject`
+
+`Function`| A function that takes a response object and returns a unique identifier to be used when normalizing the data in the store.For details, see [Customizing identifier generation globally](https://www.apollographql.com/docs/react/caching/cache-configuration#customizing-identifier-generation-globally).
+
+## Customizing cache IDs
+
+You can customize how the `InMemoryCache` generates cache IDs for individual types in your schema ([see the default behavior](https://www.apollographql.com/docs/react/caching/overview/#2-generate-cache-ids)). This is helpful especially if a type uses a field (or fields!) _besides_ `id` or `_id` as its unique identifier.
+
+To accomplish this, you define a `TypePolicy` for each type you want to customize. You specify all of your cache's `typePolicies` in [the `options` object you provide to the `InMemoryCache` constructor](https://www.apollographql.com/docs/react/caching/cache-configuration#configuration-options).
+
+Include a `keyFields` field in relevant `TypePolicy` objects, like so:
+
+TypeScript
+
+copy
+
+
+ 1const cache = new InMemoryCache({
+ 2 typePolicies: {
+ 3 Product: {
+ 4 // In an inventory management system, products might be identified
+ 5 // by their UPC.
+ 6 keyFields: ["upc"],
+ 7 },
+ 8 Person: {
+ 9 // In a user account system, the combination of a person's name AND email
+ 10 // address might uniquely identify them.
+ 11 keyFields: ["name", "email"],
+ 12 },
+ 13 Book: {
+ 14 // If one of the keyFields is an object with fields of its own, you can
+ 15 // include those nested keyFields by using a nested array of strings:
+ 16 keyFields: ["title", "author", ["name"]],
+ 17 },
+ 18 AllProducts: {
+ 19 // Singleton types that have no identifying field can use an empty
+ 20 // array for their keyFields.
+ 21 keyFields: [],
+ 22 },
+ 23 Store: {
+ 24 // If you need to disable normalization, set the keyFields to false
+ 25 // and the object will be embedded in the parent
+ 26 keyFields: false,
+ 27 },
+ 28 Location: {
+ 29 // You can also use a function to determine any of the values above.
+ 30 // The first argument is the reference to the record to be written, and the second is the runtime context
+ 31 keyFields: (location, context) => {
+ 32 if (context.readField("state")) {
+ 33 return ["city", "state", "country"];
+ 34 } else {
+ 35 return ["city", "country"];
+ 36 }
+ 37 },
+ 38 },
+ 39 },
+ 40});
+
+This example shows a variety of `typePolicies` with different `keyFields`:
+
+ * The `Product` type uses its `upc` field as its identifying field.
+
+ * The `Person` type uses the combination of both its `name` _and_ `email` fields.
+
+ * The `Book` type includes a _sub field_ as part of its cache ID.
+
+ * The `["name"]` item indicates that the `name` field of the _previous_ field in the array (`author`) is part of the cache ID. The `Book`'s `author` field must be an object that includes a `name` field for this to be valid.
+
+ * A valid cache ID for the `Book` type has the following structure:
+
+Text
+
+copy
+
+ 1Book:{"title":"Fahrenheit 451","author":{"name":"Ray Bradbury"}}
+
+ * The `AllProducts` type illustrates a special strategy for a **singleton** type. If the cache will only ever contain one `AllProducts` object and that object has _no_ identifying fields, you can provide an empty array for its `keyFields`.
+
+ * The `Store` type provides an example of how you can [disable normalization](https://www.apollographql.com/docs/react/caching/cache-configuration/#disabling-normalization) by setting the keyFields to `false`
+
+ * The `Location` type provides an example of using custom function given object and runtime context to calculate what fields should be used for the key field selection.
+
+ * Keep in mind that the first argument here is a reference to the record that will be written. As such, it does NOT include subselected fields, only scalar fields, and it contains aliases from the operation. If you need to read the real type you can use `context.storeObject`. To read even more indepth about how this function can work the best source will be our own [test cases for the cache policies](https://github.com/apollographql/apollo-client/blob/8bc7d4d406402962bf5151cdd2c5c75c [...]
+
+
+
+
+If an object has multiple `keyFields`, the cache ID always lists those fields in the same order to ensure uniqueness.
+
+Note that these `keyFields` strings always refer to the canonical field names defined in the schema. This means that ID computation is _not_ sensitive to field aliases.
+
+### Calculating an object's cache ID
+
+If you define a custom cache ID that uses multiple fields, it can be challenging to calculate and provide that ID to methods that require it (such as `cache.readFragment`).
+
+To help with this, you can use the `cache.identify` method to calculate the cache ID for any normalized object you fetch from your cache. See [Obtaining an object's custom ID](https://www.apollographql.com/docs/react/caching/cache-interaction/#obtaining-an-objects-cache-id).
+
+### Customizing identifier generation globally
+
+If you need to define a single fallback `keyFields` function that isn't specific to any particular `__typename`, you can use the `dataIdFromObject` function that was introduced in Apollo Client 2.x:
+
+TypeScript
+
+copy
+
+
+ 1import { defaultDataIdFromObject } from "@apollo/client";
+ 2
+ 3const cache = new InMemoryCache({
+ 4 dataIdFromObject(responseObject) {
+ 5 switch (responseObject.__typename) {
+ 6 case "Product":
+ 7 return `Product:${responseObject.upc}`;
+ 8 case "Person":
+ 9 return `Person:${responseObject.name}:${responseObject.email}`;
+ 10 default:
+ 11 return defaultDataIdFromObject(responseObject);
+ 12 }
+ 13 },
+ 14});
+
+> The `dataIdFromObject` API is included in Apollo Client 3 to ease the transition from Apollo Client 2.x.
+
+Notice that the above function still uses different logic to generate keys based on an object's `__typename`. In a case like this, you should almost always define `keyFields` arrays for the `Product` and `Person` types via `typePolicies`.
+
+This code also has the following drawbacks:
+
+ * It's sensitive to aliasing mistakes.
+
+ * It does nothing to protect against undefined object properties.
+
+ * Accidentally using different key fields at different times can cause inconsistencies in the cache.
+
+
+
+
+### Customizing Type Policies
+
+After creating an `InMemoryCache` instance, you can use the `addTypePolicies` method to add or modify type policies.
+
+Here is an example of how to use the `addTypePolicies` method:
+
+TypeScript
+
+copy
+
+
+ 1const cache = new InMemoryCache({
+ 2 typePolicies: {
+ 3 Person: {
+ 4 fields: {
+ 5 name: {
+ 6 read(name = "UNKNOWN NAME") {
+ 7 return name.toUpperCase();
+ 8 },
+ 9 },
+ 10 },
+ 11 },
+ 12 },
+ 13});
+ 14
+ 15// Add a type policy to the cache.
+ 16cache.policies.addTypePolicies({
+ 17 Person: {
+ 18 fields: {
+ 19 email: {
+ 20 read(email = "unknown@example.com") {
+ 21 return email;
+ 22 },
+ 23 },
+ 24 },
+ 25 },
+ 26});
+
+The code creates an `InMemoryCache` with a custom type policy for the `Person` type. The type policy specifies that if the `name` field is not available in the cache, it should return a default value of "UNKNOWN NAME" and converts it to uppercase.
+
+Then, the code adds an additional type policy to the cache using `cache.policies.addTypePolicies`. This new type policy is related to the `Person` type and its `email` field. The custom read function specifies that if the email field is not available in the cache, it should return a default value of "[unknown@example.com](mailto:unknown@example.com)".
+
+Overall, the code sets up caching behaviors for the `Person` type, ensuring that default values are provided for the `name` and `email` fields if they are not present in the cache.
+
+### Disabling normalization
+
+You can instruct the `InMemoryCache` _not_ to normalize objects of a particular type. This can be useful for metrics and other transient data that's identified by a timestamp and never receives updates.
+
+To disable normalization for a type, define a `TypePolicy` for the type (as shown in [Customizing cache IDs](https://www.apollographql.com/docs/react/caching/cache-configuration#customizing-cache-ids)) and set the policy's `keyFields` field to `false`.
+
+Objects that are not normalized are instead embedded within their _parent_ object in the cache. You can't access these objects directly, but you can access them via their parent.
+
+## `TypePolicy` fields
+
+To customize how the cache interacts with specific types in your schema, you can pass the `InMemoryCache` constructor an object that maps `__typename` strings to `TypePolicy` objects.
+
+A `TypePolicy` object can include the following fields:
+
+TypeScript
+
+copy
+
+
+ 1type TypePolicy = {
+ 2 // Allows defining the primary key fields for this type, either using an
+ 3 // array of field names, a function that returns an arbitrary string, or
+ 4 // false to disable normalization for objects of this type.
+ 5 keyFields?: KeySpecifier | KeyFieldsFunction | false;
+ 6
+ 7 // If your schema uses a custom __typename for any of the root Query,
+ 8 // Mutation, and/or Subscription types (rare), set the corresponding
+ 9 // field below to true to indicate that this type serves as that type.
+ 10 queryType?: true;
+ 11 mutationType?: true;
+ 12 subscriptionType?: true;
+ 13
+ 14 fields?: {
+ 15 [fieldName: string]:
+ 16 | FieldPolicy<StoreValue>
+ 17 | FieldReadFunction<StoreValue>;
+ 18 };
+ 19};
+ 20
+ 21// Recursive type aliases are coming in TypeScript 3.7, so this isn't the
+ 22// actual type we use, but it's what it should be:
+ 23type KeySpecifier = (string | KeySpecifier)[];
+ 24
+ 25type KeyFieldsFunction = (
+ 26 object: Readonly<StoreObject>,
+ 27 context: {
+ 28 typename: string;
+ 29 selectionSet?: SelectionSetNode;
+ 30 fragmentMap?: FragmentMap;
+ 31 }
+ 32) => string | null | void;
+
+### Overriding root operation types (uncommon)
+
+In addition to `keyFields`, a `TypePolicy` can indicate that its type represents the root query, mutation, or subscription type by setting `queryType`, `mutationType`, or `subscriptionType` to `true`:
+
+TypeScript
+
+copy
+
+
+ 1const cache = new InMemoryCache({
+ 2 typePolicies: {
+ 3 UnconventionalRootQuery: {
+ 4 // The RootQueryFragment can only match if the cache knows the __typename
+ 5 // of the root query object.
+ 6 queryType: true,
+ 7 },
+ 8 },
+ 9});
+ 10
+ 11const result = cache.readQuery({
+ 12 query: gql`
+ 13 query MyQuery {
+ 14 ...RootQueryFragment
+ 15 }
+ 16 fragment RootQueryFragment on UnconventionalRootQuery {
+ 17 field1
+ 18 field2 {
+ 19 subfield
+ 20 }
+ 21 }
+ 22 `,
+ 23});
+ 24
+ 25const equivalentResult = cache.readQuery({
+ 26 query: gql`
+ 27 query MyQuery {
+ 28 field1
+ 29 field2 {
+ 30 subfield
+ 31 }
+ 32 }
+ 33 `,
+ 34});
+
+The cache usually obtains `__typename` information by adding the `__typename` field to every query selection set it sends to the server. It could technically use this same method for the outermost selection set of every operation, but the `__typename`s of the root query and mutation are almost always `"Query"` and `"Mutation"`, so the cache assumes those common defaults unless instructed otherwise in a `TypePolicy`.
+
+For most objects in a graph, the `__typename` field is vital for proper identification and normalization. For the root query and mutation types, the `__typename` is not nearly as useful or important, because those types are singletons with only one instance per client.
+
+### The `fields` property
+
+The final property within `TypePolicy` is the `fields` property, which enables you to [customize the behavior of individual cached fields](https://www.apollographql.com/docs/react/caching/cache-field-behavior).
+
+[PreviousCaching in Apollo Client](/docs/react/caching/overview)
+
+[NextReading and writing data to the cache](/docs/react/caching/cache-interaction)
+
+Give FeedbackFeedback
+
+[ Edit on GitHub ](https://github.com/apollographql/apollo-client/blob/main/./docs/source/caching/cache-configuration.mdx) [ Ask Community ](https://community.apollographql.com/)
+
+[ ](https://www.apollographql.com)
+
+(C) 2025 Apollo Graph Inc., d/b/a Apollo GraphQL.
+
+[ Privacy Policy ](https://www.apollographql.com/privacy-policy)
+
+## Company
+
+ * [ About Apollo ](https://www.apollographql.com/about-us)
+ * [ Careers ](https://www.apollographql.com/careers)
+ * [ Partners ](https://www.apollographql.com/partners)
+
+
+
+## Resources
+
+ * [ Blog ](https://blog.apollographql.com)
+ * [ Tutorials ](https://www.apollographql.com/tutorials)
+ * [ Content Library ](https://www.apollographql.com/resources)
+
+
+
+## Get in touch
+
+ * [ Contact Sales ](https://www.apollographql.com/contact-sales)
+ * [ Contact Support ](https://www.apollographql.com/support)
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/mutations.md b/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/mutations.md
new file mode 100644
index 00000000..2b65ca24
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/mutations.md
@@ -0,0 +1,1554 @@
+# Apollo โ Mutations
+
+> Source: [https://www.apollographql.com/docs/react/data/mutations/](https://www.apollographql.com/docs/react/data/mutations/)
+> Retrieved: 2025-11-19T07:02:42.934383Z
+
+[ Docs ](/docs)
+
+[ ](/docs)
+
+Search Apollo content (Cmd+K or /)
+
+[Launch GraphOS Studio ](https://studio.apollographql.com/signup?referrer=docs)
+
+[ Home Home ](/docs/)[ Schema Design Schema Design ](/docs/graphos/schema-design)[ Connectors Connectors ](/docs/graphos/connectors)[ GraphOS Platform GraphOS Platform ](/docs/graphos/platform)[ Routing Routing ](/docs/graphos/routing)[ Resources Resources ](/docs/graphos/resources)
+
+Apollo Client (Web) Apollo Client (Web)
+
+[Rover CLI](https://www.apollographql.com/docs/rover)[IDE Support](https://www.apollographql.com/docs/ide-support)[Apollo Client (Web)](https://www.apollographql.com/docs/react)[Apollo iOS](https://www.apollographql.com/docs/ios)[Apollo Kotlin](https://www.apollographql.com/docs/kotlin)[Apollo Server](https://www.apollographql.com/docs/apollo-server)[Apollo MCP Server](https://www.apollographql.com/docs/apollo-mcp-server)[Apollo Operator](https://www.apollographql.com/docs/apollo-operator)
+
+Apollo Client (Web) - v4 (latest)
+
+[Introduction](https://www.apollographql.com/docs/react)[Why Apollo Client?](https://www.apollographql.com/docs/react/why-apollo)[Get started](https://www.apollographql.com/docs/react/get-started)
+
+### Core concepts
+
+[Queries](https://www.apollographql.com/docs/react/data/queries)[Suspense](https://www.apollographql.com/docs/react/data/suspense)[Fragments](https://www.apollographql.com/docs/react/data/fragments)[Mutations](https://www.apollographql.com/docs/react/data/mutations)[TypeScript](https://www.apollographql.com/docs/react/data/typescript)[Refetching](https://www.apollographql.com/docs/react/data/refetching)[Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions)[Directive [...]
+
+### Caching
+
+[Overview](https://www.apollographql.com/docs/react/caching/overview)[Configuration](https://www.apollographql.com/docs/react/caching/cache-configuration)[Reading and writing](https://www.apollographql.com/docs/react/caching/cache-interaction)[Garbage collection and eviction](https://www.apollographql.com/docs/react/caching/garbage-collection)[Customizing field behavior](https://www.apollographql.com/docs/react/caching/cache-field-behavior)[Memory Management](https://www.apollographql.co [...]
+
+### Pagination
+
+[Overview](https://www.apollographql.com/docs/react/pagination/overview)[Core API](https://www.apollographql.com/docs/react/pagination/core-api)[Offset-based](https://www.apollographql.com/docs/react/pagination/offset-based)[Cursor-based](https://www.apollographql.com/docs/react/pagination/cursor-based)[keyArgs](https://www.apollographql.com/docs/react/pagination/key-args)
+
+### Local State
+
+[Overview](https://www.apollographql.com/docs/react/local-state/local-state-management)[Local-only fields](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies)[Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)[Local resolvers](https://www.apollographql.com/docs/react/local-state/local-resolvers)
+
+### Development & Testing
+
+[Developer tools](https://www.apollographql.com/docs/react/development-testing/developer-tooling)[GraphQL Codegen](https://www.apollographql.com/docs/react/development-testing/graphql-codegen)[Testing React components](https://www.apollographql.com/docs/react/development-testing/testing)[Schema-driven testing](https://www.apollographql.com/docs/react/development-testing/schema-driven-testing)[Mocking schema capabilities](https://www.apollographql.com/docs/react/development-testing/client [...]
+
+### Performance
+
+[Improving performance](https://www.apollographql.com/docs/react/performance/performance)[Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui)[Server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering)[Compiling queries with Babel](https://www.apollographql.com/docs/react/performance/babel)
+
+### Integrations
+
+[Using Apollo Client with your view layer](https://www.apollographql.com/docs/react/integrations/integrations)[Integrating with React Native](https://www.apollographql.com/docs/react/integrations/react-native)[Loading queries with Webpack](https://www.apollographql.com/docs/react/integrations/webpack)
+
+### Networking
+
+[Basic HTTP networking](https://www.apollographql.com/docs/react/networking/basic-http-networking)[Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking)[Authentication](https://www.apollographql.com/docs/react/networking/authentication)
+
+### API Reference
+
+### Core
+
+[ApolloClient](https://www.apollographql.com/docs/react/api/core/ApolloClient)[InMemoryCache](https://www.apollographql.com/docs/react/api/cache/InMemoryCache)[ObservableQuery](https://www.apollographql.com/docs/react/api/core/ObservableQuery)
+
+### Errors
+
+[CombinedGraphQLErrors](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors)[CombinedProtocolErrors](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors)[LinkError](https://www.apollographql.com/docs/react/api/errors/LinkError)[LocalStateError](https://www.apollographql.com/docs/react/api/errors/LocalStateError)[ServerError](https://www.apollographql.com/docs/react/api/errors/ServerError)[ServerParseError](https://www.apollographql.com/docs/re [...]
+
+### React
+
+[ApolloProvider](https://www.apollographql.com/docs/react/api/react/ApolloProvider)[useQuery](https://www.apollographql.com/docs/react/api/react/useQuery)[useLazyQuery](https://www.apollographql.com/docs/react/api/react/useLazyQuery)[useMutation](https://www.apollographql.com/docs/react/api/react/useMutation)[useSubscription](https://www.apollographql.com/docs/react/api/react/useSubscription)[useFragment](https://www.apollographql.com/docs/react/api/react/useFragment)[useApolloClient](ht [...]
+
+### Apollo Link
+
+[Overview](https://www.apollographql.com/docs/react/api/link/introduction)[ApolloLink](https://www.apollographql.com/docs/react/api/link/apollo-link)[BaseHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-http)[BaseBatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-batch-http)[BatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http)[BatchLink](https://www.apollographql.com/docs/react/api/link/apollo- [...]
+
+[Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)[Migrating to Apollo Client 4.0](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)[Versioning Policy](https://www.apollographql.com/docs/react/versioning-policy)
+
+Navigation controls
+
+## Schema Design
+
+[Overview](https://www.apollographql.com/docs/graphos/schema-design)
+
+### Federated Schemas
+
+[Overview](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/federation)[Schema Types](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/schema-types)[Schema Composition](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/composition)[Sharing Types (Value Types)](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/sharing-types)
+
+### Federation Reference
+
+[Federation Changelog](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/versions)[Federation Directives](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/directives)[Composition Rules](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/composition-rules)
+
+### Subgraph Reference
+
+[Federation Subgraphs Specification](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-spec)[Subgraph Specific Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-specific-fields)[Compatible Subgraph Libraries](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/compatible-subgraphs)
+
+### Development and Tooling
+
+[Query Plans](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/query-plans)[Composition Hints](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/hints)[Errors](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/errors)
+
+### From Federation 1 to 2
+
+[Upgrade Guide](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/moving-to-federation-2)[Federation 2 Backwards Compatibility](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/backward-compatibility)
+
+### Entities
+
+[Introduction](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/intro)
+
+### Entity Essentials
+
+[Entity Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/contribute-fields)[Advanced Keys](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/define-keys)[Entity Interfaces](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/interfaces)
+
+### Entity Guides
+
+[Entity Best Practices](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/best-practices)[Migrate Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/migrate-fields)[Resolve Another Subgraph's Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields)[Enforce Ownership](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entit [...]
+
+### Schema Design Guides
+
+### Schema Design Principles
+
+[Demand Oriented Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/demand-oriented-schema-design)[Naming Conventions](https://www.apollographql.com/docs/graphos/schema-design/guides/naming-conventions)[Namespacing](https://www.apollographql.com/docs/graphos/schema-design/guides/namespacing-by-separation-of-concerns)
+
+### Server-Driven UI
+
+[Basics](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/basics)[Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/schema-design)[Client Design](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/client-design)
+
+### Data Handling Techniques
+
+[Handling the N+1 Problem](https://www.apollographql.com/docs/graphos/schema-design/guides/handling-n-plus-one)[Nullability](https://www.apollographql.com/docs/graphos/schema-design/guides/nullability)[Interfaces](https://www.apollographql.com/docs/graphos/schema-design/guides/interfaces)[Response Type Pattern](https://www.apollographql.com/docs/graphos/schema-design/guides/response-type-pattern)[Errors as Data](https://www.apollographql.com/docs/graphos/schema-design/guides/errors-as-da [...]
+
+### Schema Development and Evolution
+
+[Mocking to Unblock Development](https://www.apollographql.com/docs/graphos/schema-design/guides/mocking)[Deprecations](https://www.apollographql.com/docs/graphos/schema-design/guides/deprecations)[Distributed Orchestration](https://www.apollographql.com/docs/graphos/schema-design/guides/distributed-orchestration)[Migrating from a Monolith](https://www.apollographql.com/docs/graphos/schema-design/guides/from-monolith)[Migrating from Schema Stitching](https://www.apollographql.com/docs/gr [...]
+
+## Connectors
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors)[Why use Connectors?](https://www.apollographql.com/docs/graphos/connectors/why-connectors)
+
+### Getting Started
+
+[Quickstart](https://www.apollographql.com/docs/graphos/connectors/getting-started)[API Requirements](https://www.apollographql.com/docs/graphos/connectors/getting-started/requirements)[Version Requirements](https://www.apollographql.com/docs/graphos/connectors/getting-started/version-requirements)
+
+### Connectors Library
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/library)
+
+### Prebuilt Connectors
+
+[Anthropic](https://www.apollographql.com/docs/graphos/connectors/library/anthropic)[Open AI](https://www.apollographql.com/docs/graphos/connectors/library/openai)[AWS DynamoDB](https://www.apollographql.com/docs/graphos/connectors/library/aws-dynamodb)[AWS Lambda](https://www.apollographql.com/docs/graphos/connectors/library/aws-lambda)[Strapi](https://www.apollographql.com/docs/graphos/connectors/library/strapi)[Stripe](https://www.apollographql.com/docs/graphos/connectors/library/stri [...]
+
+### Development and Tooling
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/tooling)[IDE Extensions](https://www.apollographql.com/docs/graphos/connectors/tooling/ide-extensions)[Using Rover](https://www.apollographql.com/docs/graphos/connectors/tooling/rover)[CLI Tools](https://www.apollographql.com/docs/graphos/connectors/tooling/cli-tools)[Mapping Playground](https://www.apollographql.com/docs/graphos/connectors/tooling/mapping-playground)
+
+### Making Requests
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/requests)[Request URLs](https://www.apollographql.com/docs/graphos/connectors/requests/url)[Request Headers](https://www.apollographql.com/docs/graphos/connectors/requests/headers)[Request Bodies](https://www.apollographql.com/docs/graphos/connectors/requests/body)[Batch Requests](https://www.apollographql.com/docs/graphos/connectors/requests/batching)[gRPC over JSON](https://www.apollographql.com/docs/graphos/connectors/re [...]
+
+### Handling Responses
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/responses)[Mapping Response Fields](https://www.apollographql.com/docs/graphos/connectors/responses/fields)[Error Handling](https://www.apollographql.com/docs/graphos/connectors/responses/error-handling)
+
+### Working with Entities
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/entities)[Common Patterns](https://www.apollographql.com/docs/graphos/connectors/entities/patterns)[Working Across Subgraphs](https://www.apollographql.com/docs/graphos/connectors/entities/across-subgraphs)
+
+### Mapping Language
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/mapping)[Handling Arrays](https://www.apollographql.com/docs/graphos/connectors/mapping/arrays)[Mapping Enums](https://www.apollographql.com/docs/graphos/connectors/mapping/enums)[Using Literal Values](https://www.apollographql.com/docs/graphos/connectors/mapping/literals)[Variable Reference](https://www.apollographql.com/docs/graphos/connectors/mapping/variables)[Method Reference](https://www.apollographql.com/docs/graphos [...]
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/deployment)[Configuration](https://www.apollographql.com/docs/graphos/connectors/deployment/configuration)
+
+### Deployment Configurations
+
+[Overriding Base URLs](https://www.apollographql.com/docs/graphos/connectors/deployment/overriding-base-urls)[Overriding Headers](https://www.apollographql.com/docs/graphos/connectors/deployment/overriding-headers)
+
+### Security Configurations
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/security)[Authentication](https://www.apollographql.com/docs/graphos/connectors/security/auth)[Request Limits](https://www.apollographql.com/docs/graphos/connectors/security/request-limits)[TLS](https://www.apollographql.com/docs/graphos/connectors/security/tls)
+
+### Performance Configurations
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/performance)[Traffic Shaping](https://www.apollographql.com/docs/graphos/connectors/performance/traffic-shaping)
+
+### Observability
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/observability)[Telemetry Configurations](https://www.apollographql.com/docs/graphos/connectors/observability/telemetry)
+
+### Testing
+
+[Testing Framework](https://www.apollographql.com/docs/graphos/connectors/testing)
+
+### Connectors Reference
+
+[Changelog](https://www.apollographql.com/docs/graphos/connectors/reference/changelog)[Directives](https://www.apollographql.com/docs/graphos/connectors/reference/directives)[Limitations](https://www.apollographql.com/docs/graphos/connectors/reference/limitations)
+
+[Troubleshooting](https://www.apollographql.com/docs/graphos/connectors/troubleshooting)
+
+## GraphOS Platform
+
+[Overview](https://www.apollographql.com/docs/graphos/platform)[Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox)
+
+### Schema Management
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management)
+
+### Schema Delivery
+
+### Publishing
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing)[Publish with Rover](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/rover)[Publish with the Platform API](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/platform-api)[Guide: Publish with GitHub Actions](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/guide-github)
+
+[Launches](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/launch)[Graph Artifacts](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/graph-artifacts)
+
+### Contracts
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/overview)[Create](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/create)[Usage Patterns](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/usage-patterns)[Reference](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/reference)
+
+### Schema Checks
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/checks)[Run Checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/run)[Custom Checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/custom)[Checks Configuration](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/configure)[GitHub Integration](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/gi [...]
+
+### Schema Linting
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/linting)[Linter Rules](https://www.apollographql.com/docs/graphos/platform/schema-management/linting/rules)
+
+### Schema Proposals
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals)[Configure](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/configure)[Create](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/create)[Review](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/review)[Implement](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/implement)
+
+### Explorer IDE
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/explorer)[Connect and Authenticate](https://www.apollographql.com/docs/graphos/platform/explorer/connect)[Operation Collections](https://www.apollographql.com/docs/graphos/platform/explorer/operation-collections)[Subscription Support](https://www.apollographql.com/docs/graphos/platform/explorer/subscription-support)[Embed](https://www.apollographql.com/docs/graphos/platform/explorer/embed)[Scripting](https://www.apollographql [...]
+
+### Graph Security
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/security/overview)[Persisted Queries](https://www.apollographql.com/docs/graphos/platform/security/persisted-queries)
+
+### Metrics and Insights
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/insights)
+
+### Metrics Collection and Forwarding
+
+[Sending Metrics to GraphOS](https://www.apollographql.com/docs/graphos/platform/insights/sending-operation-metrics)[Operation Signatures](https://www.apollographql.com/docs/graphos/platform/insights/operation-signatures)[Datadog Forwarding](https://www.apollographql.com/docs/graphos/platform/insights/datadog-forwarding)
+
+### Insights and Analysis
+
+[Operation Metrics](https://www.apollographql.com/docs/graphos/platform/insights/operation-metrics)[Field Usage](https://www.apollographql.com/docs/graphos/platform/insights/field-usage)[Error Diagnostics](https://www.apollographql.com/docs/graphos/platform/insights/errors)[Subgraph Metrics](https://www.apollographql.com/docs/graphos/platform/insights/subgraphs)[Segmenting by Client](https://www.apollographql.com/docs/graphos/platform/insights/client-segmentation)
+
+### Notifications and Alerts
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/insights/notifications)[Daily Reports](https://www.apollographql.com/docs/graphos/platform/insights/notifications/daily-reports)[Schema Changes](https://www.apollographql.com/docs/graphos/platform/insights/notifications/schema-changes)[Schema Proposals](https://www.apollographql.com/docs/graphos/platform/insights/notifications/schema-proposals)[Performance Alerts](https://www.apollographql.com/docs/graphos/platform/insights/n [...]
+
+### Access Management
+
+[Organizations](https://www.apollographql.com/docs/graphos/platform/access-management/org)[API Keys](https://www.apollographql.com/docs/graphos/platform/access-management/api-keys)[Members, Roles, and Permissions](https://www.apollographql.com/docs/graphos/platform/access-management/member-roles)[Audit Logs](https://www.apollographql.com/docs/graphos/platform/access-management/audit-log)
+
+### SSO
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/access-management/sso/overview)[Multi-Organization](https://www.apollographql.com/docs/graphos/platform/access-management/sso/multi-organization)
+
+### SAML
+
+[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-microsoft-entra-id)[Generic SAML Setup](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-integration-guide)
+
+### OIDC
+
+[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-microsoft-entra-id)[Generic OIDC Setup](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-integration-guide)
+
+### SCIM
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/access-management/scim)[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/scim/okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/scim/microsoft-entra-id)
+
+### Graph Management
+
+[Using Variants](https://www.apollographql.com/docs/graphos/platform/graph-management/variants)[Adding Subgraphs](https://www.apollographql.com/docs/graphos/platform/graph-management/add-subgraphs)[Managing Subgraphs](https://www.apollographql.com/docs/graphos/platform/graph-management/manage-subgraphs)[Updating Graph Components](https://www.apollographql.com/docs/graphos/platform/graph-management/updates)[Transferring Graphs](https://www.apollographql.com/docs/graphos/platform/graph-man [...]
+
+### Production Readiness
+
+[Production Readiness Checklist](https://www.apollographql.com/docs/graphos/platform/production-readiness/checklist)
+
+### Testing and Load Management
+
+[Overload Protection](https://www.apollographql.com/docs/graphos/platform/production-readiness/overload-protection)[Load Testing](https://www.apollographql.com/docs/graphos/platform/production-readiness/load-testing)[Testing with Federation](https://www.apollographql.com/docs/graphos/platform/production-readiness/testing-with-apollo-federation)
+
+### Environment and Deployment
+
+[Environment Best Practices](https://www.apollographql.com/docs/graphos/platform/production-readiness/environment-best-practices)[Schema Change Management](https://www.apollographql.com/docs/graphos/platform/production-readiness/change-management)[Updating Client Schema](https://www.apollographql.com/docs/graphos/platform/production-readiness/updating-client-schema)[Deployment Best Practices](https://www.apollographql.com/docs/graphos/platform/production-readiness/deployment-best-practices)
+
+[Platform Limits](https://www.apollographql.com/docs/graphos/platform/platform-limits)[GraphOS Platform API](https://www.apollographql.com/docs/graphos/platform/platform-api)[GraphOS MCP Tools](https://www.apollographql.com/docs/graphos/platform/graphos-mcp-tools)
+
+## Routing
+
+Apollo Router - v2 (latest)
+
+[Overview](https://www.apollographql.com/docs/graphos/routing)[Get Started](https://www.apollographql.com/docs/graphos/routing/get-started)[Request Lifecycle](https://www.apollographql.com/docs/graphos/routing/request-lifecycle)
+
+### Configuration
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/configuration/overview)[Environment Variable Reference](https://www.apollographql.com/docs/graphos/routing/configuration/envvars)[CLI Reference](https://www.apollographql.com/docs/graphos/routing/configuration/cli)[YAML Reference](https://www.apollographql.com/docs/graphos/routing/configuration/yaml)
+
+### Features
+
+### Security
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/security)[Persisted Queries](https://www.apollographql.com/docs/graphos/routing/security/persisted-queries)[Authorization](https://www.apollographql.com/docs/graphos/routing/security/authorization)
+
+### Authentication
+
+[JWT Authentication](https://www.apollographql.com/docs/graphos/routing/security/jwt)[Router Authentication](https://www.apollographql.com/docs/graphos/routing/security/router-authentication)[Subgraph Authentication](https://www.apollographql.com/docs/graphos/routing/security/subgraph-authentication)
+
+[CORS](https://www.apollographql.com/docs/graphos/routing/security/cors)[CSRF Prevention](https://www.apollographql.com/docs/graphos/routing/security/csrf)[TLS](https://www.apollographql.com/docs/graphos/routing/security/tls)[Request Limits](https://www.apollographql.com/docs/graphos/routing/security/request-limits)[Demand Control](https://www.apollographql.com/docs/graphos/routing/security/demand-control)
+
+### Observability
+
+### Studio Insights
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/graphos)[Operation Metrics Reporting](https://www.apollographql.com/docs/graphos/routing/observability/graphos/graphos-reporting)[Federated Trace Data](https://www.apollographql.com/docs/graphos/routing/observability/graphos/federated-trace-data)
+
+### Router Telemetry (OTEL)
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel)
+
+### Telemetry Data
+
+### Metrics
+
+[Instruments](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/instruments)[Standard Instruments](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/standard-instruments)
+
+[Events](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/events)
+
+### Traces
+
+[Spans](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/spans)[Standard Attributes](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/standard-attributes)
+
+[Conditions](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/conditions)[Selectors](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/selectors)
+
+### Usage Guides
+
+### Subgraph Observability
+
+[Subgraph Error Inclusion](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/subgraph-error-inclusion)[Debugging Subgraph Requests](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/debugging-subgraph-requests)[Instrumenting Subgraphs](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides [...]
+
+### Client Observability
+
+[Debugging Client Requests](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/debugging-client-requests)[Client ID Enforcement](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/client-id-enforcement)
+
+### Telemetry Exporters
+
+### Metrics Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/metrics-exporters/overview)[OTLP](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/metrics-exporters/otlp)
+
+### Log Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/log-exporters/overview)[Stdout](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/log-exporters/stdout)
+
+### Trace Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/trace-exporters/overview)[OTLP](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/trace-exporters/otlp)
+
+### APM Guides
+
+### Datadog
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog)
+
+### Connecting to Datadog
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog)[OpenTelemetry Collector](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/otel-collector)
+
+### Datadog Agent
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/datadog-agent/datadog-agent-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/datadog-agent/datadog-agent-traces)
+
+[Router Instrumentation](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/router-instrumentation)[Dashboard Template](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/observing-and-monitoring/dashboard-template)
+
+### New Relic
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/new-relic/new-relic-otlp-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/new-relic/new-relic-otlp-traces)
+
+### Prometheus
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/prometheus/prometheus-metrics)[Trace Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/prometheus/otel-traces-to-prometheus)
+
+### Zipkin
+
+[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/zipkin/zipkin-traces)
+
+### Jaeger
+
+[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/jaeger/jaeger-traces)
+
+### Dynatrace
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/dynatrace/dynatrace-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/dynatrace/dynatrace-traces)
+
+### Performance and Scaling
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/performance)
+
+### Response Caching
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/overview)[Quickstart](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/quickstart)[Invalidation](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/invalidation)[Customization](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/customization)[Observability](https://www.apollograp [...]
+
+[Traffic Shaping](https://www.apollographql.com/docs/graphos/routing/performance/traffic-shaping)[Query Batching](https://www.apollographql.com/docs/graphos/routing/performance/query-batching)
+
+### Client Features
+
+[APQ](https://www.apollographql.com/docs/graphos/routing/operations/apq)[HTTP Header Propagation](https://www.apollographql.com/docs/graphos/routing/header-propagation)[@defer](https://www.apollographql.com/docs/graphos/routing/operations/defer)
+
+### GraphQL Subscriptions
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/overview)[Configuration](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/configuration)[Callback Protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/callback-protocol)[Multipart Protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol)[Enable with API Gateway](https://www.apollographql.com/docs [...]
+
+[File Upload](https://www.apollographql.com/docs/graphos/routing/operations/file-upload)
+
+### Query Planning
+
+[Native Query Planner](https://www.apollographql.com/docs/graphos/routing/query-planning/native-query-planner)[Best Practices](https://www.apollographql.com/docs/graphos/routing/query-planning/query-planning-best-practices)[Caching](https://www.apollographql.com/docs/graphos/routing/query-planning/caching)
+
+### Customization
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/customization/overview)
+
+### Coprocessors
+
+[Coprocessor Configuration](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor)[Coprocessor Reference](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor/reference)
+
+### Rhai Scripts
+
+[Rhai Configuration](https://www.apollographql.com/docs/graphos/routing/customization/rhai)[Rhai API Reference](https://www.apollographql.com/docs/graphos/routing/customization/rhai/reference)
+
+### Custom Builds
+
+[Building a Binary](https://www.apollographql.com/docs/graphos/routing/customization/custom-binary)[Rust Plugins](https://www.apollographql.com/docs/graphos/routing/customization/native-plugins)
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/self-hosted)
+
+### Docker
+
+[Docker with the Apollo Runtime Container](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/docker)[Docker with Apollo Router](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/docker-router-only)
+
+### Kubernetes
+
+[Quickstart](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/quickstart)[Deploying with Extensibility](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/extensibility)[Enabling Metrics](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/metrics)[Other Considerations](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/other-con [...]
+
+### AWS
+
+[AWS ECS](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/aws)
+
+### Azure
+
+[Azure Container Apps](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/azure)
+
+### GCP
+
+[Google Cloud Run](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/gcp)
+
+### Managed Hosting
+
+[Railway](https://www.apollographql.com/docs/graphos/routing/self-hosted/managed-hosting/railway)[Render](https://www.apollographql.com/docs/graphos/routing/self-hosted/managed-hosting/render)
+
+### Apollo Cloud Routing
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/cloud)[Configuration](https://www.apollographql.com/docs/graphos/routing/cloud/configuration)[Secure Subgraphs](https://www.apollographql.com/docs/graphos/routing/cloud/secure-subgraphs)[Subscriptions](https://www.apollographql.com/docs/graphos/routing/cloud/subscriptions)[Serverless](https://www.apollographql.com/docs/graphos/routing/cloud/serverless)
+
+### Dedicated
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/cloud/dedicated)[Quickstart](https://www.apollographql.com/docs/graphos/routing/cloud/dedicated-quickstart)[Custom Domains](https://www.apollographql.com/docs/graphos/routing/cloud/custom-domains)[Throughput Guide](https://www.apollographql.com/docs/graphos/routing/cloud/throughput-guide)[Migrate to Dedicated](https://www.apollographql.com/docs/graphos/routing/cloud/migrate-to-dedicated)
+
+### AWS Lattice
+
+[Lattice Configuration](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-configuration)[Lattice Management](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-management)[Lattice Troubleshooting](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-troubleshooting)
+
+### Tools
+
+[Router Resource Estimator](https://www.apollographql.com/docs/graphos/routing/self-hosted/resource-estimator)[Health Checks](https://www.apollographql.com/docs/graphos/routing/self-hosted/health-checks)[Resource Management](https://www.apollographql.com/docs/graphos/routing/self-hosted/resource-management)
+
+### Releases
+
+[Changelogs](https://www.apollographql.com/docs/graphos/routing/changelog)[What's New in Router v2](https://www.apollographql.com/docs/graphos/routing/about-v2)[Upgrade from Router v1](https://www.apollographql.com/docs/graphos/routing/upgrade/from-router-v1)[Migrate from Gateway](https://www.apollographql.com/docs/graphos/routing/migration/from-gateway)[API Gateway Comparison](https://www.apollographql.com/docs/graphos/routing/router-api-gateway-comparison)
+
+### GraphOS Integration
+
+[GraphOS Plan License](https://www.apollographql.com/docs/graphos/routing/license)[GraphOS Plan Features](https://www.apollographql.com/docs/graphos/routing/graphos-features)[Apollo Uplink](https://www.apollographql.com/docs/graphos/routing/uplink)
+
+### Reference
+
+[Federation Version Support](https://www.apollographql.com/docs/graphos/routing/federation-version-support)[Errors](https://www.apollographql.com/docs/graphos/routing/errors)
+
+## Resources
+
+[Overview](https://www.apollographql.com/docs/graphos/resources)[Changelogs](https://www.apollographql.com/docs/graphos/resources/changelog)[Glossary](https://www.apollographql.com/docs/graphos/resources/glossary)[Examples](https://www.apollographql.com/docs/graphos/resources/solutions)
+
+### Release Policies
+
+[Apollo Feature Launch Stages](https://www.apollographql.com/docs/graphos/resources/feature-launch-stages)[GraphOS Router Release Lifecycle](https://www.apollographql.com/docs/graphos/resources/router-release-lifecycle)[Apollo Client Library Release Lifecycle](https://www.apollographql.com/docs/graphos/resources/client-library-release-lifecycle)
+
+### Architecture
+
+[Reference Architecture](https://www.apollographql.com/docs/graphos/resources/architecture)
+
+### Supergraph Architecture Framework
+
+[Overview](https://www.apollographql.com/docs/graphos/resources/saf)[Operational Excellence](https://www.apollographql.com/docs/graphos/resources/saf/operational-excellence)[Security](https://www.apollographql.com/docs/graphos/resources/saf/security)[Reliability](https://www.apollographql.com/docs/graphos/resources/saf/reliability)[Performance](https://www.apollographql.com/docs/graphos/resources/saf/performance)[Developer Experience](https://www.apollographql.com/docs/graphos/resources/ [...]
+
+### GraphQL Adoption Guides
+
+[GraphQL Adoption Patterns](https://www.apollographql.com/docs/graphos/resources/guides/graphql-adoption-patterns)[Using GraphQL for Abstraction](https://www.apollographql.com/docs/graphos/resources/guides/using-graphql-for-abstraction)[Supergraph Stewardship](https://www.apollographql.com/docs/graphos/resources/guides/supergraph-stewardship)
+
+## Rover CLI
+
+[Overview](https://www.apollographql.com/docs/rover)[Install](https://www.apollographql.com/docs/rover/getting-started)[Configure](https://www.apollographql.com/docs/rover/configuring)[Proxy Configuration](https://www.apollographql.com/docs/rover/proxy)[CI/CD](https://www.apollographql.com/docs/rover/ci-cd)[Conventions](https://www.apollographql.com/docs/rover/conventions)[Privacy and Data Collection](https://www.apollographql.com/docs/rover/privacy)[Contributing](https://www.apollograph [...]
+
+### Commands
+
+[api-key](https://www.apollographql.com/docs/rover/commands/api-key)[cloud](https://www.apollographql.com/docs/rover/commands/cloud)[config](https://www.apollographql.com/docs/rover/commands/config)[connector](https://www.apollographql.com/docs/rover/commands/connectors)[contract](https://www.apollographql.com/docs/rover/commands/contracts)[dev](https://www.apollographql.com/docs/rover/commands/dev)[explain](https://www.apollographql.com/docs/rover/commands/explain)[graph](https://www.ap [...]
+
+### The Apollo CLI (deprecated)
+
+[Installation](https://www.apollographql.com/docs/rover/apollo-cli)[Validating Client Operations](https://www.apollographql.com/docs/rover/validating-client-operations)[Moving to Rover](https://www.apollographql.com/docs/rover/migration)
+
+## IDE Support
+
+### IDE Support
+
+[Overview](https://www.apollographql.com/docs/ide-support)[Visual Studio Code](https://www.apollographql.com/docs/ide-support/vs-code)[JetBrains IDEs](https://www.apollographql.com/docs/ide-support/jetbrains)[Vim/NeoVim](https://www.apollographql.com/docs/ide-support/vim)
+
+## Apollo Client (Web)
+
+Apollo Client (Web) - v4 (latest)
+
+[Introduction](https://www.apollographql.com/docs/react)[Why Apollo Client?](https://www.apollographql.com/docs/react/why-apollo)[Get started](https://www.apollographql.com/docs/react/get-started)
+
+### Core concepts
+
+[Queries](https://www.apollographql.com/docs/react/data/queries)[Suspense](https://www.apollographql.com/docs/react/data/suspense)[Fragments](https://www.apollographql.com/docs/react/data/fragments)[Mutations](https://www.apollographql.com/docs/react/data/mutations)[TypeScript](https://www.apollographql.com/docs/react/data/typescript)[Refetching](https://www.apollographql.com/docs/react/data/refetching)[Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions)[Directive [...]
+
+### Caching
+
+[Overview](https://www.apollographql.com/docs/react/caching/overview)[Configuration](https://www.apollographql.com/docs/react/caching/cache-configuration)[Reading and writing](https://www.apollographql.com/docs/react/caching/cache-interaction)[Garbage collection and eviction](https://www.apollographql.com/docs/react/caching/garbage-collection)[Customizing field behavior](https://www.apollographql.com/docs/react/caching/cache-field-behavior)[Memory Management](https://www.apollographql.co [...]
+
+### Pagination
+
+[Overview](https://www.apollographql.com/docs/react/pagination/overview)[Core API](https://www.apollographql.com/docs/react/pagination/core-api)[Offset-based](https://www.apollographql.com/docs/react/pagination/offset-based)[Cursor-based](https://www.apollographql.com/docs/react/pagination/cursor-based)[keyArgs](https://www.apollographql.com/docs/react/pagination/key-args)
+
+### Local State
+
+[Overview](https://www.apollographql.com/docs/react/local-state/local-state-management)[Local-only fields](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies)[Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)[Local resolvers](https://www.apollographql.com/docs/react/local-state/local-resolvers)
+
+### Development & Testing
+
+[Developer tools](https://www.apollographql.com/docs/react/development-testing/developer-tooling)[GraphQL Codegen](https://www.apollographql.com/docs/react/development-testing/graphql-codegen)[Testing React components](https://www.apollographql.com/docs/react/development-testing/testing)[Schema-driven testing](https://www.apollographql.com/docs/react/development-testing/schema-driven-testing)[Mocking schema capabilities](https://www.apollographql.com/docs/react/development-testing/client [...]
+
+### Performance
+
+[Improving performance](https://www.apollographql.com/docs/react/performance/performance)[Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui)[Server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering)[Compiling queries with Babel](https://www.apollographql.com/docs/react/performance/babel)
+
+### Integrations
+
+[Using Apollo Client with your view layer](https://www.apollographql.com/docs/react/integrations/integrations)[Integrating with React Native](https://www.apollographql.com/docs/react/integrations/react-native)[Loading queries with Webpack](https://www.apollographql.com/docs/react/integrations/webpack)
+
+### Networking
+
+[Basic HTTP networking](https://www.apollographql.com/docs/react/networking/basic-http-networking)[Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking)[Authentication](https://www.apollographql.com/docs/react/networking/authentication)
+
+### API Reference
+
+### Core
+
+[ApolloClient](https://www.apollographql.com/docs/react/api/core/ApolloClient)[InMemoryCache](https://www.apollographql.com/docs/react/api/cache/InMemoryCache)[ObservableQuery](https://www.apollographql.com/docs/react/api/core/ObservableQuery)
+
+### Errors
+
+[CombinedGraphQLErrors](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors)[CombinedProtocolErrors](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors)[LinkError](https://www.apollographql.com/docs/react/api/errors/LinkError)[LocalStateError](https://www.apollographql.com/docs/react/api/errors/LocalStateError)[ServerError](https://www.apollographql.com/docs/react/api/errors/ServerError)[ServerParseError](https://www.apollographql.com/docs/re [...]
+
+### React
+
+[ApolloProvider](https://www.apollographql.com/docs/react/api/react/ApolloProvider)[useQuery](https://www.apollographql.com/docs/react/api/react/useQuery)[useLazyQuery](https://www.apollographql.com/docs/react/api/react/useLazyQuery)[useMutation](https://www.apollographql.com/docs/react/api/react/useMutation)[useSubscription](https://www.apollographql.com/docs/react/api/react/useSubscription)[useFragment](https://www.apollographql.com/docs/react/api/react/useFragment)[useApolloClient](ht [...]
+
+### Apollo Link
+
+[Overview](https://www.apollographql.com/docs/react/api/link/introduction)[ApolloLink](https://www.apollographql.com/docs/react/api/link/apollo-link)[BaseHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-http)[BaseBatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-batch-http)[BatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http)[BatchLink](https://www.apollographql.com/docs/react/api/link/apollo- [...]
+
+[Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)[Migrating to Apollo Client 4.0](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)[Versioning Policy](https://www.apollographql.com/docs/react/versioning-policy)
+
+## Apollo iOS
+
+Apollo iOS - v2 (latest)
+
+[Introduction](https://www.apollographql.com/docs/ios)[Get Started](https://www.apollographql.com/docs/ios/get-started)
+
+### Project Configuration
+
+[Introduction](https://www.apollographql.com/docs/ios/project-configuration/intro)[1\. Project Modularization](https://www.apollographql.com/docs/ios/project-configuration/modularization)[2\. Schema Types](https://www.apollographql.com/docs/ios/project-configuration/schema-types)[3\. Operation Models](https://www.apollographql.com/docs/ios/project-configuration/operation-models)[SDK components](https://www.apollographql.com/docs/ios/project-configuration/sdk-components)
+
+### Migration Guides
+
+[v2.0](https://www.apollographql.com/docs/ios/migrations/2.0)
+
+### Tutorial
+
+[Code Generation](https://www.apollographql.com/docs/ios/tutorial/codegen-getting-started)
+
+### Build a project with Apollo
+
+[Introduction](https://www.apollographql.com/docs/ios/tutorial/tutorial-introduction)[1\. Configure your project](https://www.apollographql.com/docs/ios/tutorial/tutorial-configure-project)[2\. Add the GraphQL schema](https://www.apollographql.com/docs/ios/tutorial/tutorial-add-graphql-schema)[3\. Write your first query](https://www.apollographql.com/docs/ios/tutorial/tutorial-write-your-first-query)[4\. Running code generation](https://www.apollographql.com/docs/ios/tutorial/tutorial-ru [...]
+
+[API Reference](https://www.apollographql.com/docs/ios/docc/documentation)
+
+### Code Generation
+
+[Introduction](https://www.apollographql.com/docs/ios/code-generation/introduction)[The Codegen CLI](https://www.apollographql.com/docs/ios/code-generation/codegen-cli)[Configuration](https://www.apollographql.com/docs/ios/code-generation/codegen-configuration)[Downloading a Schema](https://www.apollographql.com/docs/ios/code-generation/downloading-schema)[Running Code Generation in Swift Code](https://www.apollographql.com/docs/ios/code-generation/run-codegen-in-swift-code)[Code Generat [...]
+
+### Fetching
+
+[Fetching Data](https://www.apollographql.com/docs/ios/fetching/fetching-data)
+
+### Operations
+
+[Queries](https://www.apollographql.com/docs/ios/fetching/queries)[Mutations](https://www.apollographql.com/docs/ios/fetching/mutations)[Subscriptions](https://www.apollographql.com/docs/ios/fetching/subscriptions)[Fragments](https://www.apollographql.com/docs/ios/fetching/fragments)
+
+[Operation Arguments](https://www.apollographql.com/docs/ios/fetching/operation-arguments)[Error Handling](https://www.apollographql.com/docs/ios/fetching/error-handling)[Type Conditions](https://www.apollographql.com/docs/ios/fetching/type-conditions)[Custom Scalars](https://www.apollographql.com/docs/ios/custom-scalars)[Persisted Queries](https://www.apollographql.com/docs/ios/fetching/persisted-queries)[@defer support](https://www.apollographql.com/docs/ios/fetching/defer)
+
+### Caching
+
+[Introduction](https://www.apollographql.com/docs/ios/caching/introduction)[Setup](https://www.apollographql.com/docs/ios/caching/cache-setup)[Direct Cache Access](https://www.apollographql.com/docs/ios/caching/cache-transactions)[Custom Cache Keys](https://www.apollographql.com/docs/ios/caching/cache-key-resolution)[Programmatic Cache Keys](https://www.apollographql.com/docs/ios/caching/programmatic-cache-keys)
+
+### Networking
+
+[Creating a Client](https://www.apollographql.com/docs/ios/networking/client-creation)
+
+### Pagination
+
+[Introduction](https://www.apollographql.com/docs/ios/pagination/introduction)[Using Custom Response Models](https://www.apollographql.com/docs/ios/pagination/custom-types)[Directional Pagination](https://www.apollographql.com/docs/ios/pagination/directional-pagers)[Multi-query Pagination](https://www.apollographql.com/docs/ios/pagination/multi-query)
+
+### Development & Testing
+
+[Test Mocks](https://www.apollographql.com/docs/ios/testing/test-mocks)[Including Apollo as an XCFramework](https://www.apollographql.com/docs/ios/development/using-xcframework)
+
+### Advanced
+
+[File Uploads](https://www.apollographql.com/docs/ios/advanced/file-uploads)[Request Chain Customization](https://www.apollographql.com/docs/ios/advanced/request-chain)[Client Directives](https://www.apollographql.com/docs/ios/client-directives)
+
+## Apollo Kotlin
+
+Apollo Kotlin - v4 (latest)
+
+[Get Started](https://www.apollographql.com/docs/kotlin)[Migrating to v4](https://www.apollographql.com/docs/kotlin/migration/4.0)[Modules](https://www.apollographql.com/docs/kotlin/essentials/modules)[Evolution policy](https://www.apollographql.com/docs/kotlin/essentials/evolution)[Tutorial](https://www.apollographql.com/tutorials/apollo-kotlin-android-part1)[Kdoc](https://apollographql.github.io/apollo-kotlin/kdoc/older/4.2.0/)[Changelog](https://github.com/apollographql/apollo-kotlin/ [...]
+
+### Configuration
+
+[Gradle plugin configuration](https://www.apollographql.com/docs/kotlin/advanced/plugin-configuration)[Gradle plugin recipes](https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes)[Multi Modules](https://www.apollographql.com/docs/kotlin/advanced/multi-modules)[File types](https://www.apollographql.com/docs/kotlin/essentials/file-types)[Client Awareness](https://www.apollographql.com/docs/kotlin/advanced/client-awareness)
+
+### Fetching
+
+[Queries](https://www.apollographql.com/docs/kotlin/essentials/queries)[Mutations](https://www.apollographql.com/docs/kotlin/essentials/mutations)[Subscriptions](https://www.apollographql.com/docs/kotlin/essentials/subscriptions)[GraphQL variables](https://www.apollographql.com/docs/kotlin/advanced/operation-variables)[Error handling](https://www.apollographql.com/docs/kotlin/essentials/errors)[Custom scalars](https://www.apollographql.com/docs/kotlin/essentials/custom-scalars)[Fragments [...]
+
+### Caching
+
+[Introduction](https://www.apollographql.com/docs/kotlin/caching/introduction)[Normalized caches](https://www.apollographql.com/docs/kotlin/caching/normalized-cache)[Declarative cache IDs](https://www.apollographql.com/docs/kotlin/caching/declarative-ids)[Programmatic cache IDs](https://www.apollographql.com/docs/kotlin/caching/programmatic-ids)[Watching cached data](https://www.apollographql.com/docs/kotlin/caching/query-watchers)[ApolloStore](https://www.apollographql.com/docs/kotlin/c [...]
+
+### Networking
+
+[Interceptors](https://www.apollographql.com/docs/kotlin/advanced/interceptors-http)[Custom HTTP clients](https://www.apollographql.com/docs/kotlin/advanced/http-engine)[Using the models without apollo-runtime](https://www.apollographql.com/docs/kotlin/advanced/no-runtime)[Authentication](https://www.apollographql.com/docs/kotlin/advanced/authentication)[WebSocket errors](https://www.apollographql.com/docs/kotlin/advanced/websocket-errors)[Batching operations](https://www.apollographql.c [...]
+
+### Development & Testing
+
+[Testing overview](https://www.apollographql.com/docs/kotlin/testing/overview)[Mocking HTTP responses](https://www.apollographql.com/docs/kotlin/testing/mocking-http-responses)[Mocking GraphQL responses](https://www.apollographql.com/docs/kotlin/testing/mocking-graphql-responses)[Data builders](https://www.apollographql.com/docs/kotlin/testing/data-builders)[Android Studio plugin](https://www.apollographql.com/docs/kotlin/testing/android-studio-plugin)[Apollo Debug Server](https://www.ap [...]
+
+### Advanced
+
+[Uploading files](https://www.apollographql.com/docs/kotlin/advanced/upload)[Monitoring the network state](https://www.apollographql.com/docs/kotlin/advanced/network-connectivity)[Handling nullability](https://www.apollographql.com/docs/kotlin/advanced/nullability)[Experimental WebSockets](https://www.apollographql.com/docs/kotlin/advanced/experimental-websockets)[Using aliases](https://www.apollographql.com/docs/kotlin/advanced/using-aliases)[Using Java](https://www.apollographql.com/do [...]
+
+## Apollo Server
+
+Apollo Server - v4รขยยv5 (latest)
+
+[Introduction](https://www.apollographql.com/docs/apollo-server)[Get started](https://www.apollographql.com/docs/apollo-server/getting-started)
+
+### New in v4 and v5
+
+[Migrating from Apollo Server 4](https://www.apollographql.com/docs/apollo-server/migration)[Migrating from Apollo Server 3](https://www.apollographql.com/docs/apollo-server/migration-from-v3)[Previous versions](https://www.apollographql.com/docs/apollo-server/previous-versions)[Changelog](https://github.com/apollographql/apollo-server/blob/main/packages/server/CHANGELOG.md)
+
+### Defining a Schema
+
+[Schema basics](https://www.apollographql.com/docs/apollo-server/schema/schema)[Unions and interfaces](https://www.apollographql.com/docs/apollo-server/schema/unions-interfaces)[Custom scalars](https://www.apollographql.com/docs/apollo-server/schema/custom-scalars)[Directives](https://www.apollographql.com/docs/apollo-server/schema/directives)
+
+### Resolving Operations
+
+[Resolvers](https://www.apollographql.com/docs/apollo-server/data/resolvers)[Sharing context](https://www.apollographql.com/docs/apollo-server/data/context)[Error handling](https://www.apollographql.com/docs/apollo-server/data/errors)[Subscriptions](https://www.apollographql.com/docs/apollo-server/data/subscriptions)
+
+### Fetching Data
+
+[Overview](https://www.apollographql.com/docs/apollo-server/data/fetching-data)[REST APIs](https://www.apollographql.com/docs/apollo-server/data/fetching-rest)
+
+### Web Frameworks
+
+[Integrations](https://www.apollographql.com/docs/apollo-server/integrations/integration-index)[Building integrations](https://www.apollographql.com/docs/apollo-server/integrations/building-integrations)[MERN stack tutorial](https://www.apollographql.com/docs/apollo-server/integrations/mern)
+
+### Development Workflow
+
+[Build and run queries](https://www.apollographql.com/docs/apollo-server/workflow/build-run-queries)[Request format](https://www.apollographql.com/docs/apollo-server/workflow/requests)[Generating TS types](https://www.apollographql.com/docs/apollo-server/workflow/generate-types)[Mocking](https://www.apollographql.com/docs/apollo-server/testing/mocking)[Integration testing](https://www.apollographql.com/docs/apollo-server/testing/testing)[Apollo Studio Explorer](https://www.apollographql. [...]
+
+### Performance
+
+[Caching](https://www.apollographql.com/docs/apollo-server/performance/caching)[Cache backends](https://www.apollographql.com/docs/apollo-server/performance/cache-backends)[Response Cache Eviction](https://www.apollographql.com/docs/apollo-server/performance/response-cache-eviction)[Automatic persisted queries](https://www.apollographql.com/docs/apollo-server/performance/apq)
+
+### Security
+
+[Auth](https://www.apollographql.com/docs/apollo-server/security/authentication)[CORS](https://www.apollographql.com/docs/apollo-server/security/cors)[Terminating SSL](https://www.apollographql.com/docs/apollo-server/security/terminating-ssl)[Proxy configuration](https://www.apollographql.com/docs/apollo-server/security/proxy-configuration)
+
+### Deployment
+
+[Lambda](https://www.apollographql.com/docs/apollo-server/deployment/lambda)[Heroku](https://www.apollographql.com/docs/apollo-server/deployment/heroku)
+
+### Monitoring
+
+[Metrics and logging](https://www.apollographql.com/docs/apollo-server/monitoring/metrics)[Health checks](https://www.apollographql.com/docs/apollo-server/monitoring/health-checks)
+
+### API Reference
+
+[ApolloServer](https://www.apollographql.com/docs/apollo-server/api/apollo-server)[startStandaloneServer](https://www.apollographql.com/docs/apollo-server/api/standalone)[expressMiddleware](https://www.apollographql.com/docs/apollo-server/api/express-middleware)
+
+### Plugins
+
+[Overview](https://www.apollographql.com/docs/apollo-server/builtin-plugins)
+
+### Built-in
+
+[Usage reporting](https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting)[Schema reporting](https://www.apollographql.com/docs/apollo-server/api/plugin/schema-reporting)[Inline trace](https://www.apollographql.com/docs/apollo-server/api/plugin/inline-trace)[Drain HTTP server](https://www.apollographql.com/docs/apollo-server/api/plugin/drain-http-server)[Cache control](https://www.apollographql.com/docs/apollo-server/api/plugin/cache-control)[Landing pages](https://ww [...]
+
+### Custom
+
+[Creating plugins](https://www.apollographql.com/docs/apollo-server/integrations/plugins)[Event reference](https://www.apollographql.com/docs/apollo-server/integrations/plugins-event-reference)
+
+### Using with Federation
+
+### As a subgraph
+
+[Setup](https://www.apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup)[@apollo/subgraph reference](https://www.apollographql.com/docs/apollo-server/using-federation/api/apollo-subgraph)
+
+### As a gateway
+
+[Setup](https://www.apollographql.com/docs/apollo-server/using-federation/apollo-gateway-setup)[Gateway performance](https://www.apollographql.com/docs/apollo-server/using-federation/gateway-performance)[@apollo/gateway reference](https://www.apollographql.com/docs/apollo-server/using-federation/api/apollo-gateway)
+
+## Apollo MCP Server
+
+Apollo MCP Server - v1 (latest)
+
+[Overview](https://www.apollographql.com/docs/apollo-mcp-server)[Quickstart](https://www.apollographql.com/docs/apollo-mcp-server/quickstart)[Define tools](https://www.apollographql.com/docs/apollo-mcp-server/define-tools)
+
+### Configuration
+
+[YAML Config Reference](https://www.apollographql.com/docs/apollo-mcp-server/config-file)[Custom Scalars](https://www.apollographql.com/docs/apollo-mcp-server/custom-scalars)
+
+[Run the MCP Server](https://www.apollographql.com/docs/apollo-mcp-server/run)[Debugging](https://www.apollographql.com/docs/apollo-mcp-server/debugging)
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/apollo-mcp-server/deploy)[Health Checks](https://www.apollographql.com/docs/apollo-mcp-server/health-checks)[CORS](https://www.apollographql.com/docs/apollo-mcp-server/cors)
+
+[Authorization](https://www.apollographql.com/docs/apollo-mcp-server/auth)[Telemetry](https://www.apollographql.com/docs/apollo-mcp-server/telemetry)[Best Practices](https://www.apollographql.com/docs/apollo-mcp-server/best-practices)[Licensing](https://www.apollographql.com/docs/apollo-mcp-server/licensing)[Limitations](https://www.apollographql.com/docs/apollo-mcp-server/limitations)
+
+### Guides
+
+[Authorization with Auth0](https://www.apollographql.com/docs/apollo-mcp-server/guides/auth-auth0)
+
+## Apollo Operator
+
+[Overview](https://www.apollographql.com/docs/apollo-operator)
+
+### Getting Started
+
+[Install Operator](https://www.apollographql.com/docs/apollo-operator/get-started/install-operator)[Add Subgraphs](https://www.apollographql.com/docs/apollo-operator/get-started/add-subgraphs)[Deploy Supergraphs](https://www.apollographql.com/docs/apollo-operator/get-started/deploy-supergraph)
+
+### Kubernetes Resources
+
+### Supergraph
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/resources/supergraph)[Autoscaling your Supergraphs](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/autoscalers)[Supergraph podTemplate](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/pod_template)[Supergraph networking](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/networking)
+
+[SupergraphSchema](https://www.apollographql.com/docs/apollo-operator/resources/supergraphschema)[SupergraphSet](https://www.apollographql.com/docs/apollo-operator/resources/supergraphset)[Subgraph](https://www.apollographql.com/docs/apollo-operator/resources/subgraph)
+
+### Workflows
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/workflows)[Single Cluster Setup](https://www.apollographql.com/docs/apollo-operator/workflows/single-cluster)[Multi-Cluster & Hybrid Setup](https://www.apollographql.com/docs/apollo-operator/workflows/multi-cluster)[Deploy Only](https://www.apollographql.com/docs/apollo-operator/workflows/deploy-only)
+
+### Configuration
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/configuration)[Telemetry](https://www.apollographql.com/docs/apollo-operator/configuration/telemetry)[Controllers](https://www.apollographql.com/docs/apollo-operator/configuration/controllers)[OCI](https://www.apollographql.com/docs/apollo-operator/configuration/oci)[Private Registries](https://www.apollographql.com/docs/apollo-operator/configuration/private-registries)
+
+[Security Best Practices](https://www.apollographql.com/docs/apollo-operator/security-best-practices)
+
+[Apollo Client (Web)](react)
+
+##
+
+On this page
+
+Copy as MD
+
+ * Prerequisites
+
+ * Executing a mutation
+
+ * Example
+
+ * Providing options
+
+ * Tracking mutation status
+
+ * Resetting mutation status
+
+ * Updating local data
+
+ * Supported methods
+
+ * Refetching queries
+
+ * Updating the cache directly
+
+ * Include modified objects in mutation responses
+
+ * The update function
+
+ * Refetching after update
+
+ * useMutation API
+
+ * Options
+
+ * Result
+
+ * Next steps
+
+
+
+
+[ Home ](/docs/)
+
+/ [ Apollo Client (Web) ](/docs/react)
+
+/ [ Core concepts ](/docs/react/data/queries)
+
+/ [ Mutations ](/docs/react/data/mutations)
+
+[ Apollo Client (Web) / ](/docs/react)
+
+[ Core concepts ](/docs/react/data/queries)
+
+# Mutations in Apollo Client
+
+Modify data with the useMutation hook
+
+Ask AI a question about this page
+
+Ask with ChatGPT
+
+Ask with ClaudeAsk with ChatGPT
+
+* * *
+
+Now that we've [learned how to query data](https://www.apollographql.com/docs/react/data/queries/) from our backend with Apollo Client, the natural next step is to learn how to _modify_ back-end data with **mutations**.
+
+This article demonstrates how to send updates to your GraphQL server with the `useMutation` hook. You'll also learn how to update the Apollo Client cache after executing a mutation, and how to track loading and error states.
+
+> To follow along with the examples below, open up our [starter project](https://codesandbox.io/s/mutations-example-app-start-gm7i5) and [sample GraphQL server](https://codesandbox.io/s/mutations-example-app-server-sxewr) on CodeSandbox. You can view the completed version of the app [here](https://codesandbox.io/s/mutations-example-app-final-tjoje).
+
+## Prerequisites
+
+**note**
+
+If your application is built using TypeScript, we recommend reading the [TypeScript guide](https://www.apollographql.com/docs/react/development-testing/static-typing) to learn how to use TypeScript with Apollo Client.
+
+This article assumes you're familiar with building basic GraphQL mutations. If you need a refresher, we recommend that you [read this guide](http://graphql.org/learn/queries/#mutations).
+
+This article also assumes that you've already set up Apollo Client and have wrapped your React app in an `ApolloProvider` component. For help with those steps, [get started](https://www.apollographql.com/docs/react/get-started/).
+
+## Executing a mutation
+
+The `useMutation` [React hook](https://react.dev/reference/react) is the primary API for executing mutations in an Apollo application.
+
+To execute a mutation, you first call `useMutation` within a React component and pass it the mutation you want to execute, like so:
+
+JavaScript
+
+my-component.jsx
+
+copy
+
+
+ 1import { gql } from "@apollo/client";
+ 2import { useMutation } from "@apollo/client/react";
+ 3
+ 4// Define mutation
+ 5const INCREMENT_COUNTER = gql`
+ 6 # Increments a back-end counter and gets its resulting value
+ 7 mutation IncrementCounter {
+ 8 incrementCounter {
+ 9 currentValue
+ 10 }
+ 11 }
+ 12`;
+ 13
+ 14function MyComponent() {
+ 15 const [mutate, { data, loading, error }] = useMutation(INCREMENT_COUNTER);
+ 16}
+
+As shown above, you use the `gql` function to parse the mutation string into a GraphQL document that you then pass to `useMutation`.
+
+When your component renders, `useMutation` returns a tuple that includes:
+
+ * A **mutate function** that you can call at any time to execute the mutation
+
+ * Unlike `useQuery`, `useMutation` _doesn't_ execute its operation automatically on render. Instead, call the `mutate` function to execute the mutation.
+
+ * An object with fields that represent the current status of the mutation's execution (`data`, `loading`, etc.)
+
+ * This object is similar to the object returned by the `useQuery` hook. For details, see [Result](https://www.apollographql.com/docs/react/data/mutations#result).
+
+
+
+
+### Example
+
+Let's say we're creating a to-do list application and we want the user to be able to add items to their list. First, we'll create a corresponding GraphQL mutation named `ADD_TODO`. Remember to wrap GraphQL strings in the `gql` function to parse them into query documents:
+
+JavaScript
+
+add-todo.jsx
+
+copy
+
+
+ 1import { gql } from "@apollo/client";
+ 2import { useMutation } from "@apollo/client/react";
+ 3
+ 4const ADD_TODO = gql`
+ 5 mutation AddTodo($type: String!) {
+ 6 addTodo(type: $type) {
+ 7 id
+ 8 type
+ 9 }
+ 10 }
+ 11`;
+
+Next, we'll create a component named `AddTodo` that represents the submission form for the to-do list. Inside it, we'll pass our `ADD_TODO` mutation to the `useMutation` hook:
+
+JavaScript
+
+add-todo.jsx
+
+copy
+
+
+ 1function AddTodo() {
+ 2 const [value, setValue] = useState("");
+ 3 const [addTodo, { data, loading, error }] = useMutation(ADD_TODO);
+ 4
+ 5 if (loading) return "Submitting...";
+ 6 if (error) return `Submission error! ${error.message}`;
+ 7
+ 8 return (
+ 9 <div>
+ 10 <form
+ 11 onSubmit={(e) => {
+ 12 e.preventDefault();
+ 13 addTodo({ variables: { type: value } });
+ 14 setValue("");
+ 15 }}
+ 16 >
+ 17 <input
+ 18 value={value}
+ 19 onChange={(e) => {
+ 20 setValue(e.target.value);
+ 21 }}
+ 22 />
+ 23 <button type="submit">Add Todo</button>
+ 24 </form>
+ 25 </div>
+ 26 );
+ 27}
+
+In this example, our form's `onSubmit` handler calls the **mutate function** (named `addTodo`) that's returned by the `useMutation` hook. This tells Apollo Client to execute the mutation by sending it to our GraphQL server.
+
+**note**
+
+`useMutation` behaves differently than [`useQuery`](https://www.apollographql.com/docs/react/data/queries/), which executes its operation as soon as its component renders. This is because mutations are more commonly executed in response to a user action (such as submitting a form in this case).
+
+### Providing options
+
+The `useMutation` hook accepts an `options` object as its second parameter. Here's an example that provides some default values for GraphQL `variables`:
+
+JavaScript
+
+copy
+
+
+ 1const [addTodo, { data, loading, error }] = useMutation(ADD_TODO, {
+ 2 variables: {
+ 3 type: "placeholder",
+ 4 someOtherVariable: 1234,
+ 5 },
+ 6});
+
+You can _also_ provide options directly to your mutate function, as demonstrated in this snippet from [the example above](https://www.apollographql.com/docs/react/data/mutations#example):
+
+JavaScript
+
+copy
+
+
+ 1addTodo({
+ 2 variables: {
+ 3 type: value,
+ 4 },
+ 5});
+
+Here, we use the `variables` option to provide the values of any GraphQL variables that our mutation requires (specifically, the `type` of the created to-do item).
+
+Learn more about the available options in [Options](https://www.apollographql.com/docs/react/data/mutations#options).
+
+#### Option precedence
+
+If you provide the same option to both `useMutation` _and_ your mutate function, the mutate function's value takes precedence. In the specific case of the `variables` option, the two objects are merged _shallowly_ , which means any variables provided only to `useMutation` are preserved in the resulting object. This helps you set default values for variables.
+
+In [the example snippets above](https://www.apollographql.com/docs/react/data/mutations#providing-options), `value` would override `"placeholder"` as the value of the `type` variable. The value of `someOtherVariable` (`1234`) would be preserved.
+
+**note**
+
+When using TypeScript, you might see an error related to a missing variable when a required variable is not provided to either the hook or the `mutate` function. Providing required variables to the hook makes them optional in the `mutate` function. If a required variable is not provided to the hook, it is required in the `mutate` function.
+
+### Tracking mutation status
+
+In addition to a mutate function, the `useMutation` hook returns an object that represents the current state of the mutation's execution. The fields of this object include booleans that indicate whether the mutate function has been `called` and whether the mutation's result is currently `loading`.
+
+[The example above](https://www.apollographql.com/docs/react/data/mutations#example) destructures the `loading` and `error` fields from this object to render the `AddTodo` component differently depending on the mutation's current status:
+
+JavaScript
+
+copy
+
+
+ 1if (loading) return "Submitting...";
+ 2if (error) return `Submission error! ${error.message}`;
+
+**note**
+
+The `useMutation` hook supports `onCompleted` and `onError` options if you need to perform side effects when the mutation completes. See the [API reference](https://www.apollographql.com/docs/react/api/react/useMutation) for more details.
+
+Learn more about result object in [Result](https://www.apollographql.com/docs/react/data/mutations#result).
+
+### Resetting mutation status
+
+The mutation result object returned by `useMutation` includes a [`reset` function](https://www.apollographql.com/docs/react/data/mutations#mutationresult-interface-reset):
+
+JavaScript
+
+copy
+
+
+ 1const [login, { reset }] = useMutation(LOGIN_MUTATION);
+
+Call `reset` to reset the mutation's result to its initial state (i.e., _before_ the mutate function was called). You can use this to enable users to dismiss mutation result data or errors in the UI.
+
+**note**
+
+Calling `reset` does _not_ remove any cached data returned by the mutation's execution. It only affects the state associated with the `useMutation` hook, causing the corresponding component to rerender.
+
+JavaScript
+
+copy
+
+
+ 1function LoginPage() {
+ 2 const [login, { error, reset }] = useMutation(LOGIN_MUTATION);
+ 3
+ 4 return (
+ 5 <>
+ 6 <form>
+ 7 <input class="login" />
+ 8 <input class="password" />
+ 9 <button onclick={login}>Login</button>
+ 10 </form>
+ 11 {error && (
+ 12 <LoginFailedMessageWindow
+ 13 message={error.message}
+ 14 onDismiss={() => reset()}
+ 15 />
+ 16 )}
+ 17 </>
+ 18 );
+ 19}
+
+## Updating local data
+
+When you execute a mutation, you modify back-end data. Usually, you then want to update your _locally cached_ data to reflect the back-end modification. For example, if you execute a mutation to add an item to your to-do list, you also want that item to appear in your cached copy of the list.
+
+### Supported methods
+
+The most straightforward way to update your local data is to [refetch any queries](https://www.apollographql.com/docs/react/data/mutations#refetching-queries) that might be affected by the mutation. However, this method requires additional network requests.
+
+If your mutation returns all of the objects and fields that it modified, you can [update your cache directly](https://www.apollographql.com/docs/react/data/mutations#updating-the-cache-directly) _without_ making any followup network requests.
+
+We recommend reading the guide on [Caching in Apollo Client](https://www.apollographql.com/docs/react/caching/overview) to understand how data is stored in the cache and how to perform updates to that data.
+
+## Refetching queries
+
+You can refetch queries after a mutation by providing a `refetchQueries` option to `useMutation`:
+
+JavaScript
+
+copy
+
+
+ 1// Refetches two queries after mutation completes
+ 2const [addTodo, { data, loading, error }] = useMutation(ADD_TODO, {
+ 3 refetchQueries: [
+ 4 GET_POST, // DocumentNode object parsed with gql
+ 5 "GetComments", // Query name
+ 6 ],
+ 7});
+
+You can provide one of the following values to `refetchQueries`:
+
+ * A `refetchQueries` array to refetch specific queries
+
+ * The shorthand `"active"` string to refetch all active queries
+
+ * The shorthand `"all"` string to refetch all active and inactive queries
+
+
+
+
+It is most common to provide a `refetchQueries` array when performing mutations. Learn more about active and inactive queries in the [Refetching](https://www.apollographql.com/docs/react/data/refetching) guide.
+
+When providing `refetchQueries` as an array, each element in the `refetchQueries` array is one of the following:
+
+ * A `DocumentNode` object parsed with the `gql` function
+
+ * The name of a query as a string (e.g., `GetComments`)
+
+ * To refer to queries by name, make sure each of your app's queries have a _unique_ name.
+
+
+
+
+**note**
+
+Each query in the `refetchQueries` array must be an _active_ query. If an inactive or unknown query is provided, a warning will be logged to the console.
+
+Each included query is executed with its most recently provided set of variables.
+
+You can provide the `refetchQueries` option either to `useMutation` or to the mutate function. For details, see [Option precedence](https://www.apollographql.com/docs/react/data/mutations#option-precedence).
+
+## Updating the cache directly
+
+### Include modified objects in mutation responses
+
+As a best practice, a mutation response should include any object(s) the mutation modified. This enables Apollo Client to normalize those objects and cache them according to their `__typename` and [`keyFields`](https://www.apollographql.com/docs/react/caching/cache-configuration/#customizing-cache-ids).
+
+[In the example above](https://www.apollographql.com/docs/react/data/mutations#example), our `ADD_TODO` mutation might return a `Todo` object with the following structure:
+
+JSON
+
+copy
+
+
+ 1{
+ 2 "__typename": "Todo",
+ 3 "id": "5",
+ 4 "type": "groceries"
+ 5}
+
+**note**
+
+Apollo Client automatically adds the `__typename` field to every object in your queries and mutations by default.
+
+Upon receiving this response object, Apollo Client caches it with key `Todo:5`. If a cached object _already_ exists with this key, Apollo Client overwrites any existing fields that are also included in the mutation response (other existing fields are preserved).
+
+Returning modified objects like this is a helpful first step to keeping your cache in sync with your backend. However, it isn't always sufficient. For example, a newly cached object isn't automatically added to any _list fields_ that should now include that object. To accomplish this, you can define an [`update` function](https://www.apollographql.com/docs/react/data/mutations#the-update-function).
+
+### The `update` function
+
+When a [mutation's response](https://www.apollographql.com/docs/react/data/mutations#include-modified-objects-in-mutation-responses) is insufficient to update _all_ modified fields in your cache (such as certain list fields), you can define an `update` function to apply manual changes to your cached data after a mutation.
+
+You provide an `update` function to `useMutation`, like so:
+
+JavaScript
+
+copy
+
+
+ 1const GET_TODOS = gql`
+ 2 query GetTodos {
+ 3 todos {
+ 4 id
+ 5 }
+ 6 }
+ 7`;
+ 8
+ 9function AddTodo() {
+ 10 let input;
+ 11 const [addTodo] = useMutation(ADD_TODO, {
+ 12 update(cache, { data: { addTodo } }) {
+ 13 cache.modify({
+ 14 fields: {
+ 15 todos(existingTodos = []) {
+ 16 const newTodoRef = cache.writeFragment({
+ 17 data: addTodo,
+ 18 fragment: gql`
+ 19 fragment NewTodo on Todo {
+ 20 id
+ 21 type
+ 22 }
+ 23 `,
+ 24 });
+ 25 return [...existingTodos, newTodoRef];
+ 26 },
+ 27 },
+ 28 });
+ 29 },
+ 30 });
+ 31
+ 32 return (
+ 33 <div>
+ 34 <form
+ 35 onSubmit={(e) => {
+ 36 e.preventDefault();
+ 37 addTodo({ variables: { type: input.value } });
+ 38 input.value = "";
+ 39 }}
+ 40 >
+ 41 <input
+ 42 ref={(node) => {
+ 43 input = node;
+ 44 }}
+ 45 />
+ 46 <button type="submit">Add Todo</button>
+ 47 </form>
+ 48 </div>
+ 49 );
+ 50}
+
+As shown, the `update` function is passed a `cache` object that represents the Apollo Client cache. This object provides access to cache API methods like `readQuery`/`writeQuery`, `readFragment`/`writeFragment`, `modify`, and `evict`. These methods enable you to execute GraphQL operations on the cache as though you're interacting with a GraphQL server.
+
+> Learn more about supported cache functions in [Interacting with cached data](https://www.apollographql.com/docs/react/caching/cache-interaction/).
+
+The `update` function is _also_ passed an object with a `data` property that contains the result of the mutation. You can use this value to update the cache with `cache.writeQuery`, `cache.writeFragment`, or `cache.modify`.
+
+**note**
+
+If your mutation specifies an [optimistic response](https://www.apollographql.com/docs/react/performance/optimistic-ui/), your `update` function is called **twice** : once with the optimistic result, and again with the actual result of the mutation when it returns.
+
+When the `ADD_TODO` mutation executes in the above example, the newly added and returned `addTodo` object is automatically saved into the cache _before_ the `update` function runs. However, the cached list of `ROOT_QUERY.todos` (which is watched by the `GET_TODOS` query) is _not_ automatically updated. This means that the `GET_TODOS` query isn't notified of the new `Todo` object, which in turn means that the query doesn't update to show the new item.
+
+To address this, we use `cache.modify` to surgically insert or delete items from the cache, by running "modifier" functions. In the example above, we know the results of the `GET_TODOS` query are stored in the `ROOT_QUERY.todos` array in the cache, so we use a `todos` modifier function to update the cached array to include a reference to the newly added `Todo`. With the help of `cache.writeFragment`, we get an internal reference to the added `Todo`, then append that reference to the `ROO [...]
+
+Any changes you make to cached data inside of an `update` function are automatically broadcast to queries that are listening for changes to that data. Consequently, your application's UI will update to reflect these updated cached values.
+
+### Refetching after `update`
+
+An `update` function attempts to replicate a mutation's back-end modifications in your client's local cache. These cache modifications are broadcast to all affected active queries, which updates your UI automatically. If the `update` function does this correctly, your users see the latest data immediately, without needing to await another network round trip.
+
+However, an `update` function might get this replication _wrong_ by setting a cached value incorrectly. You can "double check" your `update` function's modifications by refetching affected active queries. To do so, you first provide an `onQueryUpdated` callback function to your mutate function:
+
+JavaScript
+
+copy
+
+
+ 1addTodo({
+ 2 variables: { type: input.value },
+ 3 update(cache, result) {
+ 4 // Update the cache as an approximation of server-side mutation effects
+ 5 },
+ 6 onQueryUpdated(observableQuery) {
+ 7 // Define any custom logic for determining whether to refetch
+ 8 if (shouldRefetchQuery(observableQuery)) {
+ 9 return observableQuery.refetch();
+ 10 }
+ 11 },
+ 12});
+
+After your `update` function completes, Apollo Client calls `onQueryUpdated` _once for each active query with cached fields that were updated_. Within `onQueryUpdated`, you can use any custom logic to determine whether you want to refetch the associated query.
+
+To refetch a query from `onQueryUpdated`, call `return observableQuery.refetch()`, as shown above. Otherwise, no return value is required. If a refetched query's response differs from your `update` function's modifications, your cache and UI are both automatically updated again. Otherwise, your users see no change.
+
+Occasionally, it might be difficult to make your `update` function update all relevant queries. Not every mutation returns enough information for the `update` function to do its job effectively. To make absolutely sure a certain query is included, you can combine `onQueryUpdated` with `refetchQueries: [...]`:
+
+JavaScript
+
+copy
+
+
+ 1addTodo({
+ 2 variables: { type: input.value },
+ 3 update(cache, result) {
+ 4 // Update the cache as an approximation of server-side mutation effects.
+ 5 },
+ 6 // Force ReallyImportantQuery to be passed to onQueryUpdated.
+ 7 refetchQueries: ["ReallyImportantQuery"],
+ 8 onQueryUpdated(observableQuery) {
+ 9 // If ReallyImportantQuery is active, it will be passed to onQueryUpdated.
+ 10 // If no query with that name is active, a warning will be logged.
+ 11 },
+ 12});
+
+If `ReallyImportantQuery` was already going to be passed to `onQueryUpdated` thanks to your `update` function, then it will only be passed once. Using `refetchQueries: ["ReallyImportantQuery"]` just guarantees the query will be included.
+
+If you find you've included more queries than you expected, you can skip or ignore a query by returning `false` from `onQueryUpdated`, after examining the `ObservableQuery` to determine that it doesn't need refetching. Returning a `Promise` from `onQueryUpdated` causes the final `Promise<FetchResult<TData>>` for the mutation to await any promises returned from `onQueryUpdated`, eliminating the need for the legacy `awaitRefetchQueries: true` option.
+
+To use the `onQueryUpdated` API without performing a mutation, try the [`client.refetchQueries`](https://www.apollographql.com/docs/react/data/refetching/#clientrefetchqueries) method. In the standalone `client.refetchQueries` API, the `refetchQueries: [...]` mutation option is called `include: [...]`, and the `update` function is called `updateCache` for clarity. Otherwise, the same internal system powers both `client.refetchQueries` and refetching queries after a mutation.
+
+## `useMutation` API
+
+Supported options and result fields for the `useMutation` hook are listed below.
+
+Most calls to `useMutation` can omit the majority of these options, but it's useful to know they exist. To learn about the `useMutation` hook API in more detail with usage examples, see the [API reference](https://www.apollographql.com/docs/react/api/react/hooks/).
+
+### Options
+
+The `useMutation` hook accepts the following options:
+
+Operation options
+
+###### [`awaitRefetchQueries` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-awaitrefetchqueries)
+
+`boolean`
+
+If `true`, makes sure all queries included in `refetchQueries` are completed before the mutation is considered complete.
+
+The default value is `false` (queries are refetched asynchronously).
+
+###### [`errorPolicy` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-errorpolicy)
+
+`ErrorPolicy`
+
+Specifies how the mutation handles a response that returns both GraphQL errors and partial results.
+
+For details, see [GraphQL error policies](https://www.apollographql.com/docs/react/data/error-handling/#graphql-error-policies).
+
+The default value is `none`, meaning that the mutation result includes error details but _not_ partial results.
+
+###### [`onCompleted` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-oncompleted)
+
+`(data: MaybeMasked<TData>, clientOptions?: Options<TData, TVariables, TCache>) => void`
+
+A callback function that's called when your mutation successfully completes with zero errors (or if `errorPolicy` is `ignore` and partial data is returned).
+
+This function is passed the mutation's result `data` and any options passed to the mutation.
+
+###### [`onError` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-onerror)
+
+`(error: ErrorLike, clientOptions?: Options<TData, TVariables, TCache>) => void`
+
+A callback function that's called when the mutation encounters one or more errors (unless `errorPolicy` is `ignore`).
+
+This function is passed an [`ApolloError`](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/errors/index.ts#L36-L39) object that contains either a `networkError` object or a `graphQLErrors` array, depending on the error(s) that occurred, as well as any options passed the mutation.
+
+###### [`onQueryUpdated` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-onqueryupdated)
+
+`OnQueryUpdated<any>`
+
+Optional callback for intercepting queries whose cache data has been updated by the mutation, as well as any queries specified in the `refetchQueries: [...]` list passed to `client.mutate`.
+
+Returning a `Promise` from `onQueryUpdated` will cause the final mutation `Promise` to await the returned `Promise`. Returning `false` causes the query to be ignored.
+
+###### [`refetchQueries` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-refetchqueries)
+
+`((result: NormalizedExecutionResult<Unmasked<TData>>) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude`
+
+An array (or a function that _returns_ an array) that specifies which queries you want to refetch after the mutation occurs.
+
+Each array value can be either:
+
+ * An object containing the `query` to execute, along with any `variables`
+
+ * A string indicating the operation name of the query to refetch
+
+
+
+
+###### [`variables` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-variables)
+
+`Partial<TVariables> & TConfiguredVariables`
+
+An object containing all of the GraphQL variables your mutation requires to execute.
+
+Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
+
+Networking options
+
+###### [`client` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-client)
+
+`ApolloClient`
+
+The instance of `ApolloClient` to use to execute the mutation.
+
+By default, the instance that's passed down via context is used, but you can provide a different instance here.
+
+###### [`context` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-context)
+
+`DefaultContext`
+
+If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
+
+###### [`notifyOnNetworkStatusChange` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-notifyonnetworkstatuschange)
+
+`boolean`
+
+If `true`, the in-progress mutation's associated component re-renders whenever the network status changes or a network error occurs.
+
+The default value is `true`.
+
+Caching options
+
+###### [`fetchPolicy` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-fetchpolicy)
+
+`MutationFetchPolicy`
+
+Provide `no-cache` if the mutation's result should _not_ be written to the Apollo Client cache.
+
+The default value is `network-only` (which means the result _is_ written to the cache).
+
+Unlike queries, mutations _do not_ support [fetch policies](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy) besides `network-only` and `no-cache`.
+
+###### [`optimisticResponse` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-optimisticresponse)
+
+`Unmasked<NoInfer<TData>> | ((vars: TVariables, { IGNORE }: { IGNORE: IgnoreModifier; }) => Unmasked<NoInfer<TData>> | IgnoreModifier)`
+
+By providing either an object or a callback function that, when invoked after a mutation, allows you to return optimistic data and optionally skip updates via the `IGNORE` sentinel object, Apollo Client caches this temporary (and potentially incorrect) response until the mutation completes, enabling more responsive UI updates.
+
+For more information, see [Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui/).
+
+###### [`update` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-update)
+
+`MutationUpdaterFunction<TData, TVariables, TCache>`
+
+A function used to update the Apollo Client cache after the mutation completes.
+
+For more information, see [Updating the cache after a mutation](https://www.apollographql.com/docs/react/data/mutations#updating-the-cache-after-a-mutation).
+
+Other
+
+###### [`keepRootFields` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-keeprootfields)
+
+`boolean`
+
+To avoid retaining sensitive information from mutation root field arguments, Apollo Client v3.4+ automatically clears any `ROOT_MUTATION` fields from the cache after each mutation finishes. If you need this information to remain in the cache, you can prevent the removal by passing `keepRootFields: true` to the mutation. `ROOT_MUTATION` result data are also passed to the mutation `update` function, so we recommend obtaining the results that way, rather than using this option, if possible.
+
+###### [`updateQueries` _(optional)_](https://www.apollographql.com/docs/react/data/mutations#mutationhookoptions-interface-updatequeries)
+
+`MutationQueryReducersMap<TData>`
+
+A `MutationQueryReducersMap`, which is map from query names to mutation query reducers. Briefly, this map defines how to incorporate the results of the mutation into the results of queries that are currently being watched by your application.
+
+### Result
+
+The `useMutation` result is a tuple with a mutate function in the first position and an object representing the mutation result in the second position.
+
+You call the mutate function to trigger the mutation from your UI.
+
+###### [`called`](https://www.apollographql.com/docs/react/data/mutations#mutationresult-interface-called)
+
+`boolean`
+
+If `true`, the mutation's mutate function has been called.
+
+###### [`client`](https://www.apollographql.com/docs/react/data/mutations#mutationresult-interface-client)
+
+`ApolloClient`
+
+The instance of Apollo Client that executed the mutation.
+
+Can be useful for manually executing followup operations or writing data to the cache.
+
+###### [`data`](https://www.apollographql.com/docs/react/data/mutations#mutationresult-interface-data)
+
+`MaybeMasked<TData> | null | undefined`
+
+The data returned from your mutation. Can be `undefined` if the `errorPolicy` is `all` or `ignore` and the server returns a GraphQL response with `errors` but not `data` or a network error is returned.
+
+###### [`error`](https://www.apollographql.com/docs/react/data/mutations#mutationresult-interface-error)
+
+`ErrorLike | undefined`
+
+If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`.
+
+For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).
+
+###### [`loading`](https://www.apollographql.com/docs/react/data/mutations#mutationresult-interface-loading)
+
+`boolean`
+
+If `true`, the mutation is currently in flight.
+
+###### [`reset`](https://www.apollographql.com/docs/react/data/mutations#mutationresult-interface-reset)
+
+`() => void`
+
+A function that you can call to reset the mutation's result to its initial, uncalled state.
+
+## Next steps
+
+The `useQuery` and `useMutation` hooks together represent Apollo Client's core API for performing GraphQL operations. Now that you're familiar with both, you can begin to take advantage of Apollo Client's full feature set, including:
+
+ * [Optimistic UI](https://www.apollographql.com/docs/react/performance/optimistic-ui/): Learn how to improve perceived performance by returning an optimistic response before your mutation result comes back from the server.
+
+ * [Local state](https://www.apollographql.com/docs/react/local-state/local-state-management/): Use Apollo Client to manage the entirety of your application's local state by executing client-side mutations.
+
+ * [Caching in Apollo](https://www.apollographql.com/docs/react/caching/cache-configuration/): Dive deep into the Apollo Client cache and how it's normalized. Understanding the cache is helpful when writing `update` functions for your mutations!
+
+
+
+
+[PreviousFragments](/docs/react/data/fragments)
+
+[NextTypeScript with Apollo Client](/docs/react/data/typescript)
+
+Give FeedbackFeedback
+
+[ Edit on GitHub ](https://github.com/apollographql/apollo-client/blob/main/./docs/source/data/mutations.mdx) [ Ask Community ](https://community.apollographql.com/)
+
+[ ](https://www.apollographql.com)
+
+(C) 2025 Apollo Graph Inc., d/b/a Apollo GraphQL.
+
+[ Privacy Policy ](https://www.apollographql.com/privacy-policy)
+
+## Company
+
+ * [ About Apollo ](https://www.apollographql.com/about-us)
+ * [ Careers ](https://www.apollographql.com/careers)
+ * [ Partners ](https://www.apollographql.com/partners)
+
+
+
+## Resources
+
+ * [ Blog ](https://blog.apollographql.com)
+ * [ Tutorials ](https://www.apollographql.com/tutorials)
+ * [ Content Library ](https://www.apollographql.com/resources)
+
+
+
+## Get in touch
+
+ * [ Contact Sales ](https://www.apollographql.com/contact-sales)
+ * [ Contact Support ](https://www.apollographql.com/support)
diff --git a/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/queries.md b/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/queries.md
new file mode 100644
index 00000000..90481d29
--- /dev/null
+++ b/ecosystem/ai-tools/mcp/graphq-llm/docs/community-guides/apollo/queries.md
@@ -0,0 +1,2018 @@
+# Apollo โ Queries
+
+> Source: [https://www.apollographql.com/docs/react/data/queries/](https://www.apollographql.com/docs/react/data/queries/)
+> Retrieved: 2025-11-19T07:02:41.913342Z
+
+[ Docs ](/docs)
+
+[ ](/docs)
+
+Search Apollo content (Cmd+K or /)
+
+[Launch GraphOS Studio ](https://studio.apollographql.com/signup?referrer=docs)
+
+[ Home Home ](/docs/)[ Schema Design Schema Design ](/docs/graphos/schema-design)[ Connectors Connectors ](/docs/graphos/connectors)[ GraphOS Platform GraphOS Platform ](/docs/graphos/platform)[ Routing Routing ](/docs/graphos/routing)[ Resources Resources ](/docs/graphos/resources)
+
+Apollo Client (Web) Apollo Client (Web)
+
+[Rover CLI](https://www.apollographql.com/docs/rover)[IDE Support](https://www.apollographql.com/docs/ide-support)[Apollo Client (Web)](https://www.apollographql.com/docs/react)[Apollo iOS](https://www.apollographql.com/docs/ios)[Apollo Kotlin](https://www.apollographql.com/docs/kotlin)[Apollo Server](https://www.apollographql.com/docs/apollo-server)[Apollo MCP Server](https://www.apollographql.com/docs/apollo-mcp-server)[Apollo Operator](https://www.apollographql.com/docs/apollo-operator)
+
+Apollo Client (Web) - v4 (latest)
+
+[Introduction](https://www.apollographql.com/docs/react)[Why Apollo Client?](https://www.apollographql.com/docs/react/why-apollo)[Get started](https://www.apollographql.com/docs/react/get-started)
+
+### Core concepts
+
+[Queries](https://www.apollographql.com/docs/react/data/queries)[Suspense](https://www.apollographql.com/docs/react/data/suspense)[Fragments](https://www.apollographql.com/docs/react/data/fragments)[Mutations](https://www.apollographql.com/docs/react/data/mutations)[TypeScript](https://www.apollographql.com/docs/react/data/typescript)[Refetching](https://www.apollographql.com/docs/react/data/refetching)[Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions)[Directive [...]
+
+### Caching
+
+[Overview](https://www.apollographql.com/docs/react/caching/overview)[Configuration](https://www.apollographql.com/docs/react/caching/cache-configuration)[Reading and writing](https://www.apollographql.com/docs/react/caching/cache-interaction)[Garbage collection and eviction](https://www.apollographql.com/docs/react/caching/garbage-collection)[Customizing field behavior](https://www.apollographql.com/docs/react/caching/cache-field-behavior)[Memory Management](https://www.apollographql.co [...]
+
+### Pagination
+
+[Overview](https://www.apollographql.com/docs/react/pagination/overview)[Core API](https://www.apollographql.com/docs/react/pagination/core-api)[Offset-based](https://www.apollographql.com/docs/react/pagination/offset-based)[Cursor-based](https://www.apollographql.com/docs/react/pagination/cursor-based)[keyArgs](https://www.apollographql.com/docs/react/pagination/key-args)
+
+### Local State
+
+[Overview](https://www.apollographql.com/docs/react/local-state/local-state-management)[Local-only fields](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies)[Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)[Local resolvers](https://www.apollographql.com/docs/react/local-state/local-resolvers)
+
+### Development & Testing
+
+[Developer tools](https://www.apollographql.com/docs/react/development-testing/developer-tooling)[GraphQL Codegen](https://www.apollographql.com/docs/react/development-testing/graphql-codegen)[Testing React components](https://www.apollographql.com/docs/react/development-testing/testing)[Schema-driven testing](https://www.apollographql.com/docs/react/development-testing/schema-driven-testing)[Mocking schema capabilities](https://www.apollographql.com/docs/react/development-testing/client [...]
+
+### Performance
+
+[Improving performance](https://www.apollographql.com/docs/react/performance/performance)[Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui)[Server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering)[Compiling queries with Babel](https://www.apollographql.com/docs/react/performance/babel)
+
+### Integrations
+
+[Using Apollo Client with your view layer](https://www.apollographql.com/docs/react/integrations/integrations)[Integrating with React Native](https://www.apollographql.com/docs/react/integrations/react-native)[Loading queries with Webpack](https://www.apollographql.com/docs/react/integrations/webpack)
+
+### Networking
+
+[Basic HTTP networking](https://www.apollographql.com/docs/react/networking/basic-http-networking)[Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking)[Authentication](https://www.apollographql.com/docs/react/networking/authentication)
+
+### API Reference
+
+### Core
+
+[ApolloClient](https://www.apollographql.com/docs/react/api/core/ApolloClient)[InMemoryCache](https://www.apollographql.com/docs/react/api/cache/InMemoryCache)[ObservableQuery](https://www.apollographql.com/docs/react/api/core/ObservableQuery)
+
+### Errors
+
+[CombinedGraphQLErrors](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors)[CombinedProtocolErrors](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors)[LinkError](https://www.apollographql.com/docs/react/api/errors/LinkError)[LocalStateError](https://www.apollographql.com/docs/react/api/errors/LocalStateError)[ServerError](https://www.apollographql.com/docs/react/api/errors/ServerError)[ServerParseError](https://www.apollographql.com/docs/re [...]
+
+### React
+
+[ApolloProvider](https://www.apollographql.com/docs/react/api/react/ApolloProvider)[useQuery](https://www.apollographql.com/docs/react/api/react/useQuery)[useLazyQuery](https://www.apollographql.com/docs/react/api/react/useLazyQuery)[useMutation](https://www.apollographql.com/docs/react/api/react/useMutation)[useSubscription](https://www.apollographql.com/docs/react/api/react/useSubscription)[useFragment](https://www.apollographql.com/docs/react/api/react/useFragment)[useApolloClient](ht [...]
+
+### Apollo Link
+
+[Overview](https://www.apollographql.com/docs/react/api/link/introduction)[ApolloLink](https://www.apollographql.com/docs/react/api/link/apollo-link)[BaseHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-http)[BaseBatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-batch-http)[BatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http)[BatchLink](https://www.apollographql.com/docs/react/api/link/apollo- [...]
+
+[Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)[Migrating to Apollo Client 4.0](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)[Versioning Policy](https://www.apollographql.com/docs/react/versioning-policy)
+
+Navigation controls
+
+## Schema Design
+
+[Overview](https://www.apollographql.com/docs/graphos/schema-design)
+
+### Federated Schemas
+
+[Overview](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/federation)[Schema Types](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/schema-types)[Schema Composition](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/composition)[Sharing Types (Value Types)](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/sharing-types)
+
+### Federation Reference
+
+[Federation Changelog](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/versions)[Federation Directives](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/directives)[Composition Rules](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/composition-rules)
+
+### Subgraph Reference
+
+[Federation Subgraphs Specification](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-spec)[Subgraph Specific Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/subgraph-specific-fields)[Compatible Subgraph Libraries](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/compatible-subgraphs)
+
+### Development and Tooling
+
+[Query Plans](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/query-plans)[Composition Hints](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/hints)[Errors](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/errors)
+
+### From Federation 1 to 2
+
+[Upgrade Guide](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/moving-to-federation-2)[Federation 2 Backwards Compatibility](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/backward-compatibility)
+
+### Entities
+
+[Introduction](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/intro)
+
+### Entity Essentials
+
+[Entity Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/contribute-fields)[Advanced Keys](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/define-keys)[Entity Interfaces](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/interfaces)
+
+### Entity Guides
+
+[Entity Best Practices](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/best-practices)[Migrate Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/migrate-fields)[Resolve Another Subgraph's Fields](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields)[Enforce Ownership](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entit [...]
+
+### Schema Design Guides
+
+### Schema Design Principles
+
+[Demand Oriented Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/demand-oriented-schema-design)[Naming Conventions](https://www.apollographql.com/docs/graphos/schema-design/guides/naming-conventions)[Namespacing](https://www.apollographql.com/docs/graphos/schema-design/guides/namespacing-by-separation-of-concerns)
+
+### Server-Driven UI
+
+[Basics](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/basics)[Schema Design](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/schema-design)[Client Design](https://www.apollographql.com/docs/graphos/schema-design/guides/sdui/client-design)
+
+### Data Handling Techniques
+
+[Handling the N+1 Problem](https://www.apollographql.com/docs/graphos/schema-design/guides/handling-n-plus-one)[Nullability](https://www.apollographql.com/docs/graphos/schema-design/guides/nullability)[Interfaces](https://www.apollographql.com/docs/graphos/schema-design/guides/interfaces)[Response Type Pattern](https://www.apollographql.com/docs/graphos/schema-design/guides/response-type-pattern)[Errors as Data](https://www.apollographql.com/docs/graphos/schema-design/guides/errors-as-da [...]
+
+### Schema Development and Evolution
+
+[Mocking to Unblock Development](https://www.apollographql.com/docs/graphos/schema-design/guides/mocking)[Deprecations](https://www.apollographql.com/docs/graphos/schema-design/guides/deprecations)[Distributed Orchestration](https://www.apollographql.com/docs/graphos/schema-design/guides/distributed-orchestration)[Migrating from a Monolith](https://www.apollographql.com/docs/graphos/schema-design/guides/from-monolith)[Migrating from Schema Stitching](https://www.apollographql.com/docs/gr [...]
+
+## Connectors
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors)[Why use Connectors?](https://www.apollographql.com/docs/graphos/connectors/why-connectors)
+
+### Getting Started
+
+[Quickstart](https://www.apollographql.com/docs/graphos/connectors/getting-started)[API Requirements](https://www.apollographql.com/docs/graphos/connectors/getting-started/requirements)[Version Requirements](https://www.apollographql.com/docs/graphos/connectors/getting-started/version-requirements)
+
+### Connectors Library
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/library)
+
+### Prebuilt Connectors
+
+[Anthropic](https://www.apollographql.com/docs/graphos/connectors/library/anthropic)[Open AI](https://www.apollographql.com/docs/graphos/connectors/library/openai)[AWS DynamoDB](https://www.apollographql.com/docs/graphos/connectors/library/aws-dynamodb)[AWS Lambda](https://www.apollographql.com/docs/graphos/connectors/library/aws-lambda)[Strapi](https://www.apollographql.com/docs/graphos/connectors/library/strapi)[Stripe](https://www.apollographql.com/docs/graphos/connectors/library/stri [...]
+
+### Development and Tooling
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/tooling)[IDE Extensions](https://www.apollographql.com/docs/graphos/connectors/tooling/ide-extensions)[Using Rover](https://www.apollographql.com/docs/graphos/connectors/tooling/rover)[CLI Tools](https://www.apollographql.com/docs/graphos/connectors/tooling/cli-tools)[Mapping Playground](https://www.apollographql.com/docs/graphos/connectors/tooling/mapping-playground)
+
+### Making Requests
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/requests)[Request URLs](https://www.apollographql.com/docs/graphos/connectors/requests/url)[Request Headers](https://www.apollographql.com/docs/graphos/connectors/requests/headers)[Request Bodies](https://www.apollographql.com/docs/graphos/connectors/requests/body)[Batch Requests](https://www.apollographql.com/docs/graphos/connectors/requests/batching)[gRPC over JSON](https://www.apollographql.com/docs/graphos/connectors/re [...]
+
+### Handling Responses
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/responses)[Mapping Response Fields](https://www.apollographql.com/docs/graphos/connectors/responses/fields)[Error Handling](https://www.apollographql.com/docs/graphos/connectors/responses/error-handling)
+
+### Working with Entities
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/entities)[Common Patterns](https://www.apollographql.com/docs/graphos/connectors/entities/patterns)[Working Across Subgraphs](https://www.apollographql.com/docs/graphos/connectors/entities/across-subgraphs)
+
+### Mapping Language
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/mapping)[Handling Arrays](https://www.apollographql.com/docs/graphos/connectors/mapping/arrays)[Mapping Enums](https://www.apollographql.com/docs/graphos/connectors/mapping/enums)[Using Literal Values](https://www.apollographql.com/docs/graphos/connectors/mapping/literals)[Variable Reference](https://www.apollographql.com/docs/graphos/connectors/mapping/variables)[Method Reference](https://www.apollographql.com/docs/graphos [...]
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/deployment)[Configuration](https://www.apollographql.com/docs/graphos/connectors/deployment/configuration)
+
+### Deployment Configurations
+
+[Overriding Base URLs](https://www.apollographql.com/docs/graphos/connectors/deployment/overriding-base-urls)[Overriding Headers](https://www.apollographql.com/docs/graphos/connectors/deployment/overriding-headers)
+
+### Security Configurations
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/security)[Authentication](https://www.apollographql.com/docs/graphos/connectors/security/auth)[Request Limits](https://www.apollographql.com/docs/graphos/connectors/security/request-limits)[TLS](https://www.apollographql.com/docs/graphos/connectors/security/tls)
+
+### Performance Configurations
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/performance)[Traffic Shaping](https://www.apollographql.com/docs/graphos/connectors/performance/traffic-shaping)
+
+### Observability
+
+[Overview](https://www.apollographql.com/docs/graphos/connectors/observability)[Telemetry Configurations](https://www.apollographql.com/docs/graphos/connectors/observability/telemetry)
+
+### Testing
+
+[Testing Framework](https://www.apollographql.com/docs/graphos/connectors/testing)
+
+### Connectors Reference
+
+[Changelog](https://www.apollographql.com/docs/graphos/connectors/reference/changelog)[Directives](https://www.apollographql.com/docs/graphos/connectors/reference/directives)[Limitations](https://www.apollographql.com/docs/graphos/connectors/reference/limitations)
+
+[Troubleshooting](https://www.apollographql.com/docs/graphos/connectors/troubleshooting)
+
+## GraphOS Platform
+
+[Overview](https://www.apollographql.com/docs/graphos/platform)[Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox)
+
+### Schema Management
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management)
+
+### Schema Delivery
+
+### Publishing
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing)[Publish with Rover](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/rover)[Publish with the Platform API](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/platform-api)[Guide: Publish with GitHub Actions](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/publishing/guide-github)
+
+[Launches](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/launch)[Graph Artifacts](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/graph-artifacts)
+
+### Contracts
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/overview)[Create](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/create)[Usage Patterns](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/usage-patterns)[Reference](https://www.apollographql.com/docs/graphos/platform/schema-management/delivery/contracts/reference)
+
+### Schema Checks
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/checks)[Run Checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/run)[Custom Checks](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/custom)[Checks Configuration](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/configure)[GitHub Integration](https://www.apollographql.com/docs/graphos/platform/schema-management/checks/gi [...]
+
+### Schema Linting
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/linting)[Linter Rules](https://www.apollographql.com/docs/graphos/platform/schema-management/linting/rules)
+
+### Schema Proposals
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals)[Configure](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/configure)[Create](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/create)[Review](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/review)[Implement](https://www.apollographql.com/docs/graphos/platform/schema-management/proposals/implement)
+
+### Explorer IDE
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/explorer)[Connect and Authenticate](https://www.apollographql.com/docs/graphos/platform/explorer/connect)[Operation Collections](https://www.apollographql.com/docs/graphos/platform/explorer/operation-collections)[Subscription Support](https://www.apollographql.com/docs/graphos/platform/explorer/subscription-support)[Embed](https://www.apollographql.com/docs/graphos/platform/explorer/embed)[Scripting](https://www.apollographql [...]
+
+### Graph Security
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/security/overview)[Persisted Queries](https://www.apollographql.com/docs/graphos/platform/security/persisted-queries)
+
+### Metrics and Insights
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/insights)
+
+### Metrics Collection and Forwarding
+
+[Sending Metrics to GraphOS](https://www.apollographql.com/docs/graphos/platform/insights/sending-operation-metrics)[Operation Signatures](https://www.apollographql.com/docs/graphos/platform/insights/operation-signatures)[Datadog Forwarding](https://www.apollographql.com/docs/graphos/platform/insights/datadog-forwarding)
+
+### Insights and Analysis
+
+[Operation Metrics](https://www.apollographql.com/docs/graphos/platform/insights/operation-metrics)[Field Usage](https://www.apollographql.com/docs/graphos/platform/insights/field-usage)[Error Diagnostics](https://www.apollographql.com/docs/graphos/platform/insights/errors)[Subgraph Metrics](https://www.apollographql.com/docs/graphos/platform/insights/subgraphs)[Segmenting by Client](https://www.apollographql.com/docs/graphos/platform/insights/client-segmentation)
+
+### Notifications and Alerts
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/insights/notifications)[Daily Reports](https://www.apollographql.com/docs/graphos/platform/insights/notifications/daily-reports)[Schema Changes](https://www.apollographql.com/docs/graphos/platform/insights/notifications/schema-changes)[Schema Proposals](https://www.apollographql.com/docs/graphos/platform/insights/notifications/schema-proposals)[Performance Alerts](https://www.apollographql.com/docs/graphos/platform/insights/n [...]
+
+### Access Management
+
+[Organizations](https://www.apollographql.com/docs/graphos/platform/access-management/org)[API Keys](https://www.apollographql.com/docs/graphos/platform/access-management/api-keys)[Members, Roles, and Permissions](https://www.apollographql.com/docs/graphos/platform/access-management/member-roles)[Audit Logs](https://www.apollographql.com/docs/graphos/platform/access-management/audit-log)
+
+### SSO
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/access-management/sso/overview)[Multi-Organization](https://www.apollographql.com/docs/graphos/platform/access-management/sso/multi-organization)
+
+### SAML
+
+[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-microsoft-entra-id)[Generic SAML Setup](https://www.apollographql.com/docs/graphos/platform/access-management/sso/saml-integration-guide)
+
+### OIDC
+
+[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-microsoft-entra-id)[Generic OIDC Setup](https://www.apollographql.com/docs/graphos/platform/access-management/sso/oidc-integration-guide)
+
+### SCIM
+
+[Overview](https://www.apollographql.com/docs/graphos/platform/access-management/scim)[Okta](https://www.apollographql.com/docs/graphos/platform/access-management/scim/okta)[Microsoft Entra ID](https://www.apollographql.com/docs/graphos/platform/access-management/scim/microsoft-entra-id)
+
+### Graph Management
+
+[Using Variants](https://www.apollographql.com/docs/graphos/platform/graph-management/variants)[Adding Subgraphs](https://www.apollographql.com/docs/graphos/platform/graph-management/add-subgraphs)[Managing Subgraphs](https://www.apollographql.com/docs/graphos/platform/graph-management/manage-subgraphs)[Updating Graph Components](https://www.apollographql.com/docs/graphos/platform/graph-management/updates)[Transferring Graphs](https://www.apollographql.com/docs/graphos/platform/graph-man [...]
+
+### Production Readiness
+
+[Production Readiness Checklist](https://www.apollographql.com/docs/graphos/platform/production-readiness/checklist)
+
+### Testing and Load Management
+
+[Overload Protection](https://www.apollographql.com/docs/graphos/platform/production-readiness/overload-protection)[Load Testing](https://www.apollographql.com/docs/graphos/platform/production-readiness/load-testing)[Testing with Federation](https://www.apollographql.com/docs/graphos/platform/production-readiness/testing-with-apollo-federation)
+
+### Environment and Deployment
+
+[Environment Best Practices](https://www.apollographql.com/docs/graphos/platform/production-readiness/environment-best-practices)[Schema Change Management](https://www.apollographql.com/docs/graphos/platform/production-readiness/change-management)[Updating Client Schema](https://www.apollographql.com/docs/graphos/platform/production-readiness/updating-client-schema)[Deployment Best Practices](https://www.apollographql.com/docs/graphos/platform/production-readiness/deployment-best-practices)
+
+[Platform Limits](https://www.apollographql.com/docs/graphos/platform/platform-limits)[GraphOS Platform API](https://www.apollographql.com/docs/graphos/platform/platform-api)[GraphOS MCP Tools](https://www.apollographql.com/docs/graphos/platform/graphos-mcp-tools)
+
+## Routing
+
+Apollo Router - v2 (latest)
+
+[Overview](https://www.apollographql.com/docs/graphos/routing)[Get Started](https://www.apollographql.com/docs/graphos/routing/get-started)[Request Lifecycle](https://www.apollographql.com/docs/graphos/routing/request-lifecycle)
+
+### Configuration
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/configuration/overview)[Environment Variable Reference](https://www.apollographql.com/docs/graphos/routing/configuration/envvars)[CLI Reference](https://www.apollographql.com/docs/graphos/routing/configuration/cli)[YAML Reference](https://www.apollographql.com/docs/graphos/routing/configuration/yaml)
+
+### Features
+
+### Security
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/security)[Persisted Queries](https://www.apollographql.com/docs/graphos/routing/security/persisted-queries)[Authorization](https://www.apollographql.com/docs/graphos/routing/security/authorization)
+
+### Authentication
+
+[JWT Authentication](https://www.apollographql.com/docs/graphos/routing/security/jwt)[Router Authentication](https://www.apollographql.com/docs/graphos/routing/security/router-authentication)[Subgraph Authentication](https://www.apollographql.com/docs/graphos/routing/security/subgraph-authentication)
+
+[CORS](https://www.apollographql.com/docs/graphos/routing/security/cors)[CSRF Prevention](https://www.apollographql.com/docs/graphos/routing/security/csrf)[TLS](https://www.apollographql.com/docs/graphos/routing/security/tls)[Request Limits](https://www.apollographql.com/docs/graphos/routing/security/request-limits)[Demand Control](https://www.apollographql.com/docs/graphos/routing/security/demand-control)
+
+### Observability
+
+### Studio Insights
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/graphos)[Operation Metrics Reporting](https://www.apollographql.com/docs/graphos/routing/observability/graphos/graphos-reporting)[Federated Trace Data](https://www.apollographql.com/docs/graphos/routing/observability/graphos/federated-trace-data)
+
+### Router Telemetry (OTEL)
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel)
+
+### Telemetry Data
+
+### Metrics
+
+[Instruments](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/instruments)[Standard Instruments](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/standard-instruments)
+
+[Events](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/events)
+
+### Traces
+
+[Spans](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/spans)[Standard Attributes](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/standard-attributes)
+
+[Conditions](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/conditions)[Selectors](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/selectors)
+
+### Usage Guides
+
+### Subgraph Observability
+
+[Subgraph Error Inclusion](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/subgraph-error-inclusion)[Debugging Subgraph Requests](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/debugging-subgraph-requests)[Instrumenting Subgraphs](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides [...]
+
+### Client Observability
+
+[Debugging Client Requests](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/debugging-client-requests)[Client ID Enforcement](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/enabling-telemetry/usage-guides/client-id-enforcement)
+
+### Telemetry Exporters
+
+### Metrics Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/metrics-exporters/overview)[OTLP](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/metrics-exporters/otlp)
+
+### Log Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/log-exporters/overview)[Stdout](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/log-exporters/stdout)
+
+### Trace Exporters
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/trace-exporters/overview)[OTLP](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/telemetry-pipelines/trace-exporters/otlp)
+
+### APM Guides
+
+### Datadog
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog)
+
+### Connecting to Datadog
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog)[OpenTelemetry Collector](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/otel-collector)
+
+### Datadog Agent
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/datadog-agent/datadog-agent-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/connecting-to-datadog/datadog-agent/datadog-agent-traces)
+
+[Router Instrumentation](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/router-instrumentation)[Dashboard Template](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/datadog/observing-and-monitoring/dashboard-template)
+
+### New Relic
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/new-relic/new-relic-otlp-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/new-relic/new-relic-otlp-traces)
+
+### Prometheus
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/prometheus/prometheus-metrics)[Trace Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/prometheus/otel-traces-to-prometheus)
+
+### Zipkin
+
+[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/zipkin/zipkin-traces)
+
+### Jaeger
+
+[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/jaeger/jaeger-traces)
+
+### Dynatrace
+
+[Metrics](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/dynatrace/dynatrace-metrics)[Traces](https://www.apollographql.com/docs/graphos/routing/observability/router-telemetry-otel/apm-guides/dynatrace/dynatrace-traces)
+
+### Performance and Scaling
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/performance)
+
+### Response Caching
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/overview)[Quickstart](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/quickstart)[Invalidation](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/invalidation)[Customization](https://www.apollographql.com/docs/graphos/routing/performance/caching/response-caching/customization)[Observability](https://www.apollograp [...]
+
+[Traffic Shaping](https://www.apollographql.com/docs/graphos/routing/performance/traffic-shaping)[Query Batching](https://www.apollographql.com/docs/graphos/routing/performance/query-batching)
+
+### Client Features
+
+[APQ](https://www.apollographql.com/docs/graphos/routing/operations/apq)[HTTP Header Propagation](https://www.apollographql.com/docs/graphos/routing/header-propagation)[@defer](https://www.apollographql.com/docs/graphos/routing/operations/defer)
+
+### GraphQL Subscriptions
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/overview)[Configuration](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/configuration)[Callback Protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/callback-protocol)[Multipart Protocol](https://www.apollographql.com/docs/graphos/routing/operations/subscriptions/multipart-protocol)[Enable with API Gateway](https://www.apollographql.com/docs [...]
+
+[File Upload](https://www.apollographql.com/docs/graphos/routing/operations/file-upload)
+
+### Query Planning
+
+[Native Query Planner](https://www.apollographql.com/docs/graphos/routing/query-planning/native-query-planner)[Best Practices](https://www.apollographql.com/docs/graphos/routing/query-planning/query-planning-best-practices)[Caching](https://www.apollographql.com/docs/graphos/routing/query-planning/caching)
+
+### Customization
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/customization/overview)
+
+### Coprocessors
+
+[Coprocessor Configuration](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor)[Coprocessor Reference](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor/reference)
+
+### Rhai Scripts
+
+[Rhai Configuration](https://www.apollographql.com/docs/graphos/routing/customization/rhai)[Rhai API Reference](https://www.apollographql.com/docs/graphos/routing/customization/rhai/reference)
+
+### Custom Builds
+
+[Building a Binary](https://www.apollographql.com/docs/graphos/routing/customization/custom-binary)[Rust Plugins](https://www.apollographql.com/docs/graphos/routing/customization/native-plugins)
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/self-hosted)
+
+### Docker
+
+[Docker with the Apollo Runtime Container](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/docker)[Docker with Apollo Router](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/docker-router-only)
+
+### Kubernetes
+
+[Quickstart](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/quickstart)[Deploying with Extensibility](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/extensibility)[Enabling Metrics](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/metrics)[Other Considerations](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/kubernetes/other-con [...]
+
+### AWS
+
+[AWS ECS](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/aws)
+
+### Azure
+
+[Azure Container Apps](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/azure)
+
+### GCP
+
+[Google Cloud Run](https://www.apollographql.com/docs/graphos/routing/self-hosted/containerization/gcp)
+
+### Managed Hosting
+
+[Railway](https://www.apollographql.com/docs/graphos/routing/self-hosted/managed-hosting/railway)[Render](https://www.apollographql.com/docs/graphos/routing/self-hosted/managed-hosting/render)
+
+### Apollo Cloud Routing
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/cloud)[Configuration](https://www.apollographql.com/docs/graphos/routing/cloud/configuration)[Secure Subgraphs](https://www.apollographql.com/docs/graphos/routing/cloud/secure-subgraphs)[Subscriptions](https://www.apollographql.com/docs/graphos/routing/cloud/subscriptions)[Serverless](https://www.apollographql.com/docs/graphos/routing/cloud/serverless)
+
+### Dedicated
+
+[Overview](https://www.apollographql.com/docs/graphos/routing/cloud/dedicated)[Quickstart](https://www.apollographql.com/docs/graphos/routing/cloud/dedicated-quickstart)[Custom Domains](https://www.apollographql.com/docs/graphos/routing/cloud/custom-domains)[Throughput Guide](https://www.apollographql.com/docs/graphos/routing/cloud/throughput-guide)[Migrate to Dedicated](https://www.apollographql.com/docs/graphos/routing/cloud/migrate-to-dedicated)
+
+### AWS Lattice
+
+[Lattice Configuration](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-configuration)[Lattice Management](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-management)[Lattice Troubleshooting](https://www.apollographql.com/docs/graphos/routing/cloud/lattice-troubleshooting)
+
+### Tools
+
+[Router Resource Estimator](https://www.apollographql.com/docs/graphos/routing/self-hosted/resource-estimator)[Health Checks](https://www.apollographql.com/docs/graphos/routing/self-hosted/health-checks)[Resource Management](https://www.apollographql.com/docs/graphos/routing/self-hosted/resource-management)
+
+### Releases
+
+[Changelogs](https://www.apollographql.com/docs/graphos/routing/changelog)[What's New in Router v2](https://www.apollographql.com/docs/graphos/routing/about-v2)[Upgrade from Router v1](https://www.apollographql.com/docs/graphos/routing/upgrade/from-router-v1)[Migrate from Gateway](https://www.apollographql.com/docs/graphos/routing/migration/from-gateway)[API Gateway Comparison](https://www.apollographql.com/docs/graphos/routing/router-api-gateway-comparison)
+
+### GraphOS Integration
+
+[GraphOS Plan License](https://www.apollographql.com/docs/graphos/routing/license)[GraphOS Plan Features](https://www.apollographql.com/docs/graphos/routing/graphos-features)[Apollo Uplink](https://www.apollographql.com/docs/graphos/routing/uplink)
+
+### Reference
+
+[Federation Version Support](https://www.apollographql.com/docs/graphos/routing/federation-version-support)[Errors](https://www.apollographql.com/docs/graphos/routing/errors)
+
+## Resources
+
+[Overview](https://www.apollographql.com/docs/graphos/resources)[Changelogs](https://www.apollographql.com/docs/graphos/resources/changelog)[Glossary](https://www.apollographql.com/docs/graphos/resources/glossary)[Examples](https://www.apollographql.com/docs/graphos/resources/solutions)
+
+### Release Policies
+
+[Apollo Feature Launch Stages](https://www.apollographql.com/docs/graphos/resources/feature-launch-stages)[GraphOS Router Release Lifecycle](https://www.apollographql.com/docs/graphos/resources/router-release-lifecycle)[Apollo Client Library Release Lifecycle](https://www.apollographql.com/docs/graphos/resources/client-library-release-lifecycle)
+
+### Architecture
+
+[Reference Architecture](https://www.apollographql.com/docs/graphos/resources/architecture)
+
+### Supergraph Architecture Framework
+
+[Overview](https://www.apollographql.com/docs/graphos/resources/saf)[Operational Excellence](https://www.apollographql.com/docs/graphos/resources/saf/operational-excellence)[Security](https://www.apollographql.com/docs/graphos/resources/saf/security)[Reliability](https://www.apollographql.com/docs/graphos/resources/saf/reliability)[Performance](https://www.apollographql.com/docs/graphos/resources/saf/performance)[Developer Experience](https://www.apollographql.com/docs/graphos/resources/ [...]
+
+### GraphQL Adoption Guides
+
+[GraphQL Adoption Patterns](https://www.apollographql.com/docs/graphos/resources/guides/graphql-adoption-patterns)[Using GraphQL for Abstraction](https://www.apollographql.com/docs/graphos/resources/guides/using-graphql-for-abstraction)[Supergraph Stewardship](https://www.apollographql.com/docs/graphos/resources/guides/supergraph-stewardship)
+
+## Rover CLI
+
+[Overview](https://www.apollographql.com/docs/rover)[Install](https://www.apollographql.com/docs/rover/getting-started)[Configure](https://www.apollographql.com/docs/rover/configuring)[Proxy Configuration](https://www.apollographql.com/docs/rover/proxy)[CI/CD](https://www.apollographql.com/docs/rover/ci-cd)[Conventions](https://www.apollographql.com/docs/rover/conventions)[Privacy and Data Collection](https://www.apollographql.com/docs/rover/privacy)[Contributing](https://www.apollograph [...]
+
+### Commands
+
+[api-key](https://www.apollographql.com/docs/rover/commands/api-key)[cloud](https://www.apollographql.com/docs/rover/commands/cloud)[config](https://www.apollographql.com/docs/rover/commands/config)[connector](https://www.apollographql.com/docs/rover/commands/connectors)[contract](https://www.apollographql.com/docs/rover/commands/contracts)[dev](https://www.apollographql.com/docs/rover/commands/dev)[explain](https://www.apollographql.com/docs/rover/commands/explain)[graph](https://www.ap [...]
+
+### The Apollo CLI (deprecated)
+
+[Installation](https://www.apollographql.com/docs/rover/apollo-cli)[Validating Client Operations](https://www.apollographql.com/docs/rover/validating-client-operations)[Moving to Rover](https://www.apollographql.com/docs/rover/migration)
+
+## IDE Support
+
+### IDE Support
+
+[Overview](https://www.apollographql.com/docs/ide-support)[Visual Studio Code](https://www.apollographql.com/docs/ide-support/vs-code)[JetBrains IDEs](https://www.apollographql.com/docs/ide-support/jetbrains)[Vim/NeoVim](https://www.apollographql.com/docs/ide-support/vim)
+
+## Apollo Client (Web)
+
+Apollo Client (Web) - v4 (latest)
+
+[Introduction](https://www.apollographql.com/docs/react)[Why Apollo Client?](https://www.apollographql.com/docs/react/why-apollo)[Get started](https://www.apollographql.com/docs/react/get-started)
+
+### Core concepts
+
+[Queries](https://www.apollographql.com/docs/react/data/queries)[Suspense](https://www.apollographql.com/docs/react/data/suspense)[Fragments](https://www.apollographql.com/docs/react/data/fragments)[Mutations](https://www.apollographql.com/docs/react/data/mutations)[TypeScript](https://www.apollographql.com/docs/react/data/typescript)[Refetching](https://www.apollographql.com/docs/react/data/refetching)[Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions)[Directive [...]
+
+### Caching
+
+[Overview](https://www.apollographql.com/docs/react/caching/overview)[Configuration](https://www.apollographql.com/docs/react/caching/cache-configuration)[Reading and writing](https://www.apollographql.com/docs/react/caching/cache-interaction)[Garbage collection and eviction](https://www.apollographql.com/docs/react/caching/garbage-collection)[Customizing field behavior](https://www.apollographql.com/docs/react/caching/cache-field-behavior)[Memory Management](https://www.apollographql.co [...]
+
+### Pagination
+
+[Overview](https://www.apollographql.com/docs/react/pagination/overview)[Core API](https://www.apollographql.com/docs/react/pagination/core-api)[Offset-based](https://www.apollographql.com/docs/react/pagination/offset-based)[Cursor-based](https://www.apollographql.com/docs/react/pagination/cursor-based)[keyArgs](https://www.apollographql.com/docs/react/pagination/key-args)
+
+### Local State
+
+[Overview](https://www.apollographql.com/docs/react/local-state/local-state-management)[Local-only fields](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies)[Reactive variables](https://www.apollographql.com/docs/react/local-state/reactive-variables)[Local resolvers](https://www.apollographql.com/docs/react/local-state/local-resolvers)
+
+### Development & Testing
+
+[Developer tools](https://www.apollographql.com/docs/react/development-testing/developer-tooling)[GraphQL Codegen](https://www.apollographql.com/docs/react/development-testing/graphql-codegen)[Testing React components](https://www.apollographql.com/docs/react/development-testing/testing)[Schema-driven testing](https://www.apollographql.com/docs/react/development-testing/schema-driven-testing)[Mocking schema capabilities](https://www.apollographql.com/docs/react/development-testing/client [...]
+
+### Performance
+
+[Improving performance](https://www.apollographql.com/docs/react/performance/performance)[Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui)[Server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering)[Compiling queries with Babel](https://www.apollographql.com/docs/react/performance/babel)
+
+### Integrations
+
+[Using Apollo Client with your view layer](https://www.apollographql.com/docs/react/integrations/integrations)[Integrating with React Native](https://www.apollographql.com/docs/react/integrations/react-native)[Loading queries with Webpack](https://www.apollographql.com/docs/react/integrations/webpack)
+
+### Networking
+
+[Basic HTTP networking](https://www.apollographql.com/docs/react/networking/basic-http-networking)[Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking)[Authentication](https://www.apollographql.com/docs/react/networking/authentication)
+
+### API Reference
+
+### Core
+
+[ApolloClient](https://www.apollographql.com/docs/react/api/core/ApolloClient)[InMemoryCache](https://www.apollographql.com/docs/react/api/cache/InMemoryCache)[ObservableQuery](https://www.apollographql.com/docs/react/api/core/ObservableQuery)
+
+### Errors
+
+[CombinedGraphQLErrors](https://www.apollographql.com/docs/react/api/errors/CombinedGraphQLErrors)[CombinedProtocolErrors](https://www.apollographql.com/docs/react/api/errors/CombinedProtocolErrors)[LinkError](https://www.apollographql.com/docs/react/api/errors/LinkError)[LocalStateError](https://www.apollographql.com/docs/react/api/errors/LocalStateError)[ServerError](https://www.apollographql.com/docs/react/api/errors/ServerError)[ServerParseError](https://www.apollographql.com/docs/re [...]
+
+### React
+
+[ApolloProvider](https://www.apollographql.com/docs/react/api/react/ApolloProvider)[useQuery](https://www.apollographql.com/docs/react/api/react/useQuery)[useLazyQuery](https://www.apollographql.com/docs/react/api/react/useLazyQuery)[useMutation](https://www.apollographql.com/docs/react/api/react/useMutation)[useSubscription](https://www.apollographql.com/docs/react/api/react/useSubscription)[useFragment](https://www.apollographql.com/docs/react/api/react/useFragment)[useApolloClient](ht [...]
+
+### Apollo Link
+
+[Overview](https://www.apollographql.com/docs/react/api/link/introduction)[ApolloLink](https://www.apollographql.com/docs/react/api/link/apollo-link)[BaseHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-http)[BaseBatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-base-batch-http)[BatchHttpLink](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http)[BatchLink](https://www.apollographql.com/docs/react/api/link/apollo- [...]
+
+[Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)[Migrating to Apollo Client 4.0](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)[Versioning Policy](https://www.apollographql.com/docs/react/versioning-policy)
+
+## Apollo iOS
+
+Apollo iOS - v2 (latest)
+
+[Introduction](https://www.apollographql.com/docs/ios)[Get Started](https://www.apollographql.com/docs/ios/get-started)
+
+### Project Configuration
+
+[Introduction](https://www.apollographql.com/docs/ios/project-configuration/intro)[1\. Project Modularization](https://www.apollographql.com/docs/ios/project-configuration/modularization)[2\. Schema Types](https://www.apollographql.com/docs/ios/project-configuration/schema-types)[3\. Operation Models](https://www.apollographql.com/docs/ios/project-configuration/operation-models)[SDK components](https://www.apollographql.com/docs/ios/project-configuration/sdk-components)
+
+### Migration Guides
+
+[v2.0](https://www.apollographql.com/docs/ios/migrations/2.0)
+
+### Tutorial
+
+[Code Generation](https://www.apollographql.com/docs/ios/tutorial/codegen-getting-started)
+
+### Build a project with Apollo
+
+[Introduction](https://www.apollographql.com/docs/ios/tutorial/tutorial-introduction)[1\. Configure your project](https://www.apollographql.com/docs/ios/tutorial/tutorial-configure-project)[2\. Add the GraphQL schema](https://www.apollographql.com/docs/ios/tutorial/tutorial-add-graphql-schema)[3\. Write your first query](https://www.apollographql.com/docs/ios/tutorial/tutorial-write-your-first-query)[4\. Running code generation](https://www.apollographql.com/docs/ios/tutorial/tutorial-ru [...]
+
+[API Reference](https://www.apollographql.com/docs/ios/docc/documentation)
+
+### Code Generation
+
+[Introduction](https://www.apollographql.com/docs/ios/code-generation/introduction)[The Codegen CLI](https://www.apollographql.com/docs/ios/code-generation/codegen-cli)[Configuration](https://www.apollographql.com/docs/ios/code-generation/codegen-configuration)[Downloading a Schema](https://www.apollographql.com/docs/ios/code-generation/downloading-schema)[Running Code Generation in Swift Code](https://www.apollographql.com/docs/ios/code-generation/run-codegen-in-swift-code)[Code Generat [...]
+
+### Fetching
+
+[Fetching Data](https://www.apollographql.com/docs/ios/fetching/fetching-data)
+
+### Operations
+
+[Queries](https://www.apollographql.com/docs/ios/fetching/queries)[Mutations](https://www.apollographql.com/docs/ios/fetching/mutations)[Subscriptions](https://www.apollographql.com/docs/ios/fetching/subscriptions)[Fragments](https://www.apollographql.com/docs/ios/fetching/fragments)
+
+[Operation Arguments](https://www.apollographql.com/docs/ios/fetching/operation-arguments)[Error Handling](https://www.apollographql.com/docs/ios/fetching/error-handling)[Type Conditions](https://www.apollographql.com/docs/ios/fetching/type-conditions)[Custom Scalars](https://www.apollographql.com/docs/ios/custom-scalars)[Persisted Queries](https://www.apollographql.com/docs/ios/fetching/persisted-queries)[@defer support](https://www.apollographql.com/docs/ios/fetching/defer)
+
+### Caching
+
+[Introduction](https://www.apollographql.com/docs/ios/caching/introduction)[Setup](https://www.apollographql.com/docs/ios/caching/cache-setup)[Direct Cache Access](https://www.apollographql.com/docs/ios/caching/cache-transactions)[Custom Cache Keys](https://www.apollographql.com/docs/ios/caching/cache-key-resolution)[Programmatic Cache Keys](https://www.apollographql.com/docs/ios/caching/programmatic-cache-keys)
+
+### Networking
+
+[Creating a Client](https://www.apollographql.com/docs/ios/networking/client-creation)
+
+### Pagination
+
+[Introduction](https://www.apollographql.com/docs/ios/pagination/introduction)[Using Custom Response Models](https://www.apollographql.com/docs/ios/pagination/custom-types)[Directional Pagination](https://www.apollographql.com/docs/ios/pagination/directional-pagers)[Multi-query Pagination](https://www.apollographql.com/docs/ios/pagination/multi-query)
+
+### Development & Testing
+
+[Test Mocks](https://www.apollographql.com/docs/ios/testing/test-mocks)[Including Apollo as an XCFramework](https://www.apollographql.com/docs/ios/development/using-xcframework)
+
+### Advanced
+
+[File Uploads](https://www.apollographql.com/docs/ios/advanced/file-uploads)[Request Chain Customization](https://www.apollographql.com/docs/ios/advanced/request-chain)[Client Directives](https://www.apollographql.com/docs/ios/client-directives)
+
+## Apollo Kotlin
+
+Apollo Kotlin - v4 (latest)
+
+[Get Started](https://www.apollographql.com/docs/kotlin)[Migrating to v4](https://www.apollographql.com/docs/kotlin/migration/4.0)[Modules](https://www.apollographql.com/docs/kotlin/essentials/modules)[Evolution policy](https://www.apollographql.com/docs/kotlin/essentials/evolution)[Tutorial](https://www.apollographql.com/tutorials/apollo-kotlin-android-part1)[Kdoc](https://apollographql.github.io/apollo-kotlin/kdoc/older/4.2.0/)[Changelog](https://github.com/apollographql/apollo-kotlin/ [...]
+
+### Configuration
+
+[Gradle plugin configuration](https://www.apollographql.com/docs/kotlin/advanced/plugin-configuration)[Gradle plugin recipes](https://www.apollographql.com/docs/kotlin/advanced/plugin-recipes)[Multi Modules](https://www.apollographql.com/docs/kotlin/advanced/multi-modules)[File types](https://www.apollographql.com/docs/kotlin/essentials/file-types)[Client Awareness](https://www.apollographql.com/docs/kotlin/advanced/client-awareness)
+
+### Fetching
+
+[Queries](https://www.apollographql.com/docs/kotlin/essentials/queries)[Mutations](https://www.apollographql.com/docs/kotlin/essentials/mutations)[Subscriptions](https://www.apollographql.com/docs/kotlin/essentials/subscriptions)[GraphQL variables](https://www.apollographql.com/docs/kotlin/advanced/operation-variables)[Error handling](https://www.apollographql.com/docs/kotlin/essentials/errors)[Custom scalars](https://www.apollographql.com/docs/kotlin/essentials/custom-scalars)[Fragments [...]
+
+### Caching
+
+[Introduction](https://www.apollographql.com/docs/kotlin/caching/introduction)[Normalized caches](https://www.apollographql.com/docs/kotlin/caching/normalized-cache)[Declarative cache IDs](https://www.apollographql.com/docs/kotlin/caching/declarative-ids)[Programmatic cache IDs](https://www.apollographql.com/docs/kotlin/caching/programmatic-ids)[Watching cached data](https://www.apollographql.com/docs/kotlin/caching/query-watchers)[ApolloStore](https://www.apollographql.com/docs/kotlin/c [...]
+
+### Networking
+
+[Interceptors](https://www.apollographql.com/docs/kotlin/advanced/interceptors-http)[Custom HTTP clients](https://www.apollographql.com/docs/kotlin/advanced/http-engine)[Using the models without apollo-runtime](https://www.apollographql.com/docs/kotlin/advanced/no-runtime)[Authentication](https://www.apollographql.com/docs/kotlin/advanced/authentication)[WebSocket errors](https://www.apollographql.com/docs/kotlin/advanced/websocket-errors)[Batching operations](https://www.apollographql.c [...]
+
+### Development & Testing
+
+[Testing overview](https://www.apollographql.com/docs/kotlin/testing/overview)[Mocking HTTP responses](https://www.apollographql.com/docs/kotlin/testing/mocking-http-responses)[Mocking GraphQL responses](https://www.apollographql.com/docs/kotlin/testing/mocking-graphql-responses)[Data builders](https://www.apollographql.com/docs/kotlin/testing/data-builders)[Android Studio plugin](https://www.apollographql.com/docs/kotlin/testing/android-studio-plugin)[Apollo Debug Server](https://www.ap [...]
+
+### Advanced
+
+[Uploading files](https://www.apollographql.com/docs/kotlin/advanced/upload)[Monitoring the network state](https://www.apollographql.com/docs/kotlin/advanced/network-connectivity)[Handling nullability](https://www.apollographql.com/docs/kotlin/advanced/nullability)[Experimental WebSockets](https://www.apollographql.com/docs/kotlin/advanced/experimental-websockets)[Using aliases](https://www.apollographql.com/docs/kotlin/advanced/using-aliases)[Using Java](https://www.apollographql.com/do [...]
+
+## Apollo Server
+
+Apollo Server - v4รขยยv5 (latest)
+
+[Introduction](https://www.apollographql.com/docs/apollo-server)[Get started](https://www.apollographql.com/docs/apollo-server/getting-started)
+
+### New in v4 and v5
+
+[Migrating from Apollo Server 4](https://www.apollographql.com/docs/apollo-server/migration)[Migrating from Apollo Server 3](https://www.apollographql.com/docs/apollo-server/migration-from-v3)[Previous versions](https://www.apollographql.com/docs/apollo-server/previous-versions)[Changelog](https://github.com/apollographql/apollo-server/blob/main/packages/server/CHANGELOG.md)
+
+### Defining a Schema
+
+[Schema basics](https://www.apollographql.com/docs/apollo-server/schema/schema)[Unions and interfaces](https://www.apollographql.com/docs/apollo-server/schema/unions-interfaces)[Custom scalars](https://www.apollographql.com/docs/apollo-server/schema/custom-scalars)[Directives](https://www.apollographql.com/docs/apollo-server/schema/directives)
+
+### Resolving Operations
+
+[Resolvers](https://www.apollographql.com/docs/apollo-server/data/resolvers)[Sharing context](https://www.apollographql.com/docs/apollo-server/data/context)[Error handling](https://www.apollographql.com/docs/apollo-server/data/errors)[Subscriptions](https://www.apollographql.com/docs/apollo-server/data/subscriptions)
+
+### Fetching Data
+
+[Overview](https://www.apollographql.com/docs/apollo-server/data/fetching-data)[REST APIs](https://www.apollographql.com/docs/apollo-server/data/fetching-rest)
+
+### Web Frameworks
+
+[Integrations](https://www.apollographql.com/docs/apollo-server/integrations/integration-index)[Building integrations](https://www.apollographql.com/docs/apollo-server/integrations/building-integrations)[MERN stack tutorial](https://www.apollographql.com/docs/apollo-server/integrations/mern)
+
+### Development Workflow
+
+[Build and run queries](https://www.apollographql.com/docs/apollo-server/workflow/build-run-queries)[Request format](https://www.apollographql.com/docs/apollo-server/workflow/requests)[Generating TS types](https://www.apollographql.com/docs/apollo-server/workflow/generate-types)[Mocking](https://www.apollographql.com/docs/apollo-server/testing/mocking)[Integration testing](https://www.apollographql.com/docs/apollo-server/testing/testing)[Apollo Studio Explorer](https://www.apollographql. [...]
+
+### Performance
+
+[Caching](https://www.apollographql.com/docs/apollo-server/performance/caching)[Cache backends](https://www.apollographql.com/docs/apollo-server/performance/cache-backends)[Response Cache Eviction](https://www.apollographql.com/docs/apollo-server/performance/response-cache-eviction)[Automatic persisted queries](https://www.apollographql.com/docs/apollo-server/performance/apq)
+
+### Security
+
+[Auth](https://www.apollographql.com/docs/apollo-server/security/authentication)[CORS](https://www.apollographql.com/docs/apollo-server/security/cors)[Terminating SSL](https://www.apollographql.com/docs/apollo-server/security/terminating-ssl)[Proxy configuration](https://www.apollographql.com/docs/apollo-server/security/proxy-configuration)
+
+### Deployment
+
+[Lambda](https://www.apollographql.com/docs/apollo-server/deployment/lambda)[Heroku](https://www.apollographql.com/docs/apollo-server/deployment/heroku)
+
+### Monitoring
+
+[Metrics and logging](https://www.apollographql.com/docs/apollo-server/monitoring/metrics)[Health checks](https://www.apollographql.com/docs/apollo-server/monitoring/health-checks)
+
+### API Reference
+
+[ApolloServer](https://www.apollographql.com/docs/apollo-server/api/apollo-server)[startStandaloneServer](https://www.apollographql.com/docs/apollo-server/api/standalone)[expressMiddleware](https://www.apollographql.com/docs/apollo-server/api/express-middleware)
+
+### Plugins
+
+[Overview](https://www.apollographql.com/docs/apollo-server/builtin-plugins)
+
+### Built-in
+
+[Usage reporting](https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting)[Schema reporting](https://www.apollographql.com/docs/apollo-server/api/plugin/schema-reporting)[Inline trace](https://www.apollographql.com/docs/apollo-server/api/plugin/inline-trace)[Drain HTTP server](https://www.apollographql.com/docs/apollo-server/api/plugin/drain-http-server)[Cache control](https://www.apollographql.com/docs/apollo-server/api/plugin/cache-control)[Landing pages](https://ww [...]
+
+### Custom
+
+[Creating plugins](https://www.apollographql.com/docs/apollo-server/integrations/plugins)[Event reference](https://www.apollographql.com/docs/apollo-server/integrations/plugins-event-reference)
+
+### Using with Federation
+
+### As a subgraph
+
+[Setup](https://www.apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup)[@apollo/subgraph reference](https://www.apollographql.com/docs/apollo-server/using-federation/api/apollo-subgraph)
+
+### As a gateway
+
+[Setup](https://www.apollographql.com/docs/apollo-server/using-federation/apollo-gateway-setup)[Gateway performance](https://www.apollographql.com/docs/apollo-server/using-federation/gateway-performance)[@apollo/gateway reference](https://www.apollographql.com/docs/apollo-server/using-federation/api/apollo-gateway)
+
+## Apollo MCP Server
+
+Apollo MCP Server - v1 (latest)
+
+[Overview](https://www.apollographql.com/docs/apollo-mcp-server)[Quickstart](https://www.apollographql.com/docs/apollo-mcp-server/quickstart)[Define tools](https://www.apollographql.com/docs/apollo-mcp-server/define-tools)
+
+### Configuration
+
+[YAML Config Reference](https://www.apollographql.com/docs/apollo-mcp-server/config-file)[Custom Scalars](https://www.apollographql.com/docs/apollo-mcp-server/custom-scalars)
+
+[Run the MCP Server](https://www.apollographql.com/docs/apollo-mcp-server/run)[Debugging](https://www.apollographql.com/docs/apollo-mcp-server/debugging)
+
+### Deployment
+
+[Overview](https://www.apollographql.com/docs/apollo-mcp-server/deploy)[Health Checks](https://www.apollographql.com/docs/apollo-mcp-server/health-checks)[CORS](https://www.apollographql.com/docs/apollo-mcp-server/cors)
+
+[Authorization](https://www.apollographql.com/docs/apollo-mcp-server/auth)[Telemetry](https://www.apollographql.com/docs/apollo-mcp-server/telemetry)[Best Practices](https://www.apollographql.com/docs/apollo-mcp-server/best-practices)[Licensing](https://www.apollographql.com/docs/apollo-mcp-server/licensing)[Limitations](https://www.apollographql.com/docs/apollo-mcp-server/limitations)
+
+### Guides
+
+[Authorization with Auth0](https://www.apollographql.com/docs/apollo-mcp-server/guides/auth-auth0)
+
+## Apollo Operator
+
+[Overview](https://www.apollographql.com/docs/apollo-operator)
+
+### Getting Started
+
+[Install Operator](https://www.apollographql.com/docs/apollo-operator/get-started/install-operator)[Add Subgraphs](https://www.apollographql.com/docs/apollo-operator/get-started/add-subgraphs)[Deploy Supergraphs](https://www.apollographql.com/docs/apollo-operator/get-started/deploy-supergraph)
+
+### Kubernetes Resources
+
+### Supergraph
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/resources/supergraph)[Autoscaling your Supergraphs](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/autoscalers)[Supergraph podTemplate](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/pod_template)[Supergraph networking](https://www.apollographql.com/docs/apollo-operator/resources/supergraph/networking)
+
+[SupergraphSchema](https://www.apollographql.com/docs/apollo-operator/resources/supergraphschema)[SupergraphSet](https://www.apollographql.com/docs/apollo-operator/resources/supergraphset)[Subgraph](https://www.apollographql.com/docs/apollo-operator/resources/subgraph)
+
+### Workflows
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/workflows)[Single Cluster Setup](https://www.apollographql.com/docs/apollo-operator/workflows/single-cluster)[Multi-Cluster & Hybrid Setup](https://www.apollographql.com/docs/apollo-operator/workflows/multi-cluster)[Deploy Only](https://www.apollographql.com/docs/apollo-operator/workflows/deploy-only)
+
+### Configuration
+
+[Overview](https://www.apollographql.com/docs/apollo-operator/configuration)[Telemetry](https://www.apollographql.com/docs/apollo-operator/configuration/telemetry)[Controllers](https://www.apollographql.com/docs/apollo-operator/configuration/controllers)[OCI](https://www.apollographql.com/docs/apollo-operator/configuration/oci)[Private Registries](https://www.apollographql.com/docs/apollo-operator/configuration/private-registries)
+
+[Security Best Practices](https://www.apollographql.com/docs/apollo-operator/security-best-practices)
+
+[Apollo Client (Web)](react)
+
+##
+
+On this page
+
+Copy as MD
+
+ * Prerequisites
+
+ * Executing a query
+
+ * Caching query results
+
+ * Updating cached query results
+
+ * Polling
+
+ * Refetching
+
+ * Inspecting loading states
+
+ * Inspecting error states
+
+ * Fetching in response to user interaction
+
+ * Re-rendering with new options
+
+ * Working with variables
+
+ * Using the promise returned from the execution function
+
+ * Setting a fetch policy
+
+ * nextFetchPolicy
+
+ * Supported fetch policies
+
+ * Skipping queries with skipToken
+
+ * useQuery API
+
+ * Options
+
+ * Result
+
+ * Next steps
+
+
+
+
+[ Home ](/docs/)
+
+/ [ Apollo Client (Web) ](/docs/react)
+
+/ [ Core concepts ](/docs/react/data/queries)
+
+[ Apollo Client (Web) ](/docs/react)
+
+# Queries
+
+Fetch data with the useQuery hook
+
+Ask AI a question about this page
+
+Ask with ChatGPT
+
+Ask with ClaudeAsk with ChatGPT
+
+* * *
+
+This article shows how to fetch GraphQL data in React with the `useQuery` hook and attach the result to your UI. You'll also learn how Apollo Client simplifies data management code by tracking error and loading states for you.
+
+**note**
+
+This article shows how to use Apollo Client in a React application that doesn't make use of React's "Suspense" features. For modern React applications built around Suspense, suspense-enabled data fetching hooks are described in Apollo Client's [Suspense docs](https://www.apollographql.com/docs/react/data/suspense/).
+
+## Prerequisites
+
+**note**
+
+If your application is built using TypeScript, we recommend reading the [TypeScript guide](https://www.apollographql.com/docs/react/development-testing/static-typing) to learn how to use TypeScript with Apollo Client.
+
+This article assumes you're familiar with building basic GraphQL queries. If you need a refresher, we recommend [this guide](http://graphql.org/learn/queries/). You can also build example queries against Apollo's [full-stack tutorial server](https://apollo-fullstack-tutorial.herokuapp.com/graphql).
+
+This article also assumes that you've already set up Apollo Client and have wrapped your React app in an `ApolloProvider` component. For more information, see the [getting started guide](https://www.apollographql.com/docs/react/get-started/).
+
+> To follow along with the examples below, open up our [starter project](https://codesandbox.io/s/queries-example-app-start-nvp9z) and [sample GraphQL server](https://codesandbox.io/s/queries-example-app-server-71z1g) on CodeSandbox. You can view the completed version of the app [here](https://codesandbox.io/s/queries-example-app-final-nrlnl).
+
+## Executing a query
+
+The `useQuery` [React hook](https://react.dev/reference/react) is the primary API for executing queries in a non-suspenseful Apollo application (for information about using Apollo Client with suspenseful React, see [Suspense](https://www.apollographql.com/docs/react/data/suspense)). To run a query within a React component, call `useQuery` and pass it a GraphQL document. When your component renders, `useQuery` returns an object from Apollo Client that contains `loading`, `error`, `dataSta [...]
+
+Let's look at an example. First, we'll create a GraphQL query named `GET_DOGS`. Remember to wrap query strings in the `gql` function to parse them into query documents:
+
+JavaScript
+
+index.js
+
+copy
+
+
+ 1import { gql } from "@apollo/client";
+ 2import { useQuery } from "@apollo/client/react";
+ 3
+ 4const GET_DOGS = gql`
+ 5 query GetDogs {
+ 6 dogs {
+ 7 id
+ 8 breed
+ 9 }
+ 10 }
+ 11`;
+
+Next, we'll create a component named `Dogs`. Inside it, we'll pass our `GET_DOGS` query to the `useQuery` hook:
+
+JavaScript
+
+index.js
+
+copy
+
+
+ 1function Dogs({ onDogSelected }) {
+ 2 const { loading, error, data } = useQuery(GET_DOGS);
+ 3
+ 4 if (loading) return "Loading...";
+ 5 if (error) return `Error! ${error.message}`;
+ 6
+ 7 return (
+ 8 <select name="dog" onChange={onDogSelected}>
+ 9 {data.dogs.map((dog) => (
+ 10 <option key={dog.id} value={dog.breed}>
+ 11 {dog.breed}
+ 12 </option>
+ 13 ))}
+ 14 </select>
+ 15 );
+ 16}
+
+As our query executes and the values of `loading`, `error`, and `data` change, the `Dogs` component can intelligently render different UI elements according to the query's state:
+
+ * As long as `loading` is `true` (indicating the query is still in flight), the component presents a `Loading...` notice.
+
+ * When loading is `false` and there is no `error`, the query has completed. The component renders a dropdown menu that's populated with the list of dog breeds returned by the server.
+
+
+
+
+When the user selects a dog breed from the populated dropdown, the selection is sent to the parent component via the provided `onDogSelected` function.
+
+**note**
+
+If you are using TypeScript, `data` is typed as `unknown` when the query type is unknown. Accessing fields on `data` results in a TypeScript error. See the [TypeScript with Apollo Client](https://www.apollographql.com/docs/react/development-testing/static-typing) guide to learn how to add types for your queries.
+
+In the next step, we'll associate the dropdown with a more sophisticated query that uses GraphQL variables.
+
+## Caching query results
+
+Whenever Apollo Client fetches query results from your server, it automatically **caches** those results locally. This makes later executions of that same query extremely fast.
+
+To see this caching in action, let's build a new component called `DogPhoto`. `DogPhoto` accepts a prop called `breed` that reflects the current value of the dropdown menu in our `Dogs` component:
+
+JavaScript
+
+index.js
+
+copy
+
+
+ 1const GET_DOG_PHOTO = gql`
+ 2 query Dog($breed: String!) {
+ 3 dog(breed: $breed) {
+ 4 id
+ 5 displayImage
+ 6 }
+ 7 }
+ 8`;
+ 9
+ 10function DogPhoto({ breed }) {
+ 11 const { loading, error, data } = useQuery(GET_DOG_PHOTO, {
+ 12 variables: { breed },
+ 13 });
+ 14
+ 15 if (loading) return null;
+ 16 if (error) return `Error! ${error}`;
+ 17
+ 18 return (
+ 19 <img src={data.dog.displayImage} style={{ height: 100, width: 100 }} />
+ 20 );
+ 21}
+
+Notice that we're providing a configuration option (`variables`) to the `useQuery` hook this time. The `variables` option is an object that contains all of the variables we want to pass to our GraphQL query. In this case, we want to pass the currently selected `breed` from the dropdown.
+
+Select `bulldog` from the dropdown to see its photo appear. Then switch to another breed, and then switch _back_ to `bulldog`. You'll notice that the bulldog photo loads instantly the second time around. This is the cache at work!
+
+Next, let's learn some techniques for ensuring that our cached data is fresh.
+
+## Updating cached query results
+
+Sometimes, you want to make sure that your query's cached data is up to date with your _server's_ data. Apollo Client supports two strategies for this: **polling** and **refetching**.
+
+### Polling
+
+Polling provides near-real-time synchronization with your server by executing your query periodically at a specified interval. To enable polling for a query, pass a `pollInterval` configuration option to the `useQuery` hook with an interval in milliseconds:
+
+JavaScript
+
+index.js
+
+copy
+
+
+ 1function DogPhoto({ breed }) {
+ 2 const { loading, error, data } = useQuery(GET_DOG_PHOTO, {
+ 3 variables: { breed },
+ 4 pollInterval: 500,
+ 5 });
+ 6
+ 7 if (loading) return null;
+ 8 if (error) return `Error! ${error}`;
+ 9
+ 10 return (
+ 11 <img src={data.dog.displayImage} style={{ height: 100, width: 100 }} />
+ 12 );
+ 13}
+
+By setting `pollInterval` to 500, we fetch the current breed's image from the server every 0.5 seconds. Note that if you set `pollInterval` to `0`, the query does **not** poll.
+
+> You can also start and stop polling dynamically with the [`startPolling` and `stopPolling` functions](https://www.apollographql.com/docs/react/data/queries#startpolling) that are returned by the `useQuery` hook. When using these functions, set the `pollInterval` configuration option as a parameter of the `startPolling` function.
+
+### Refetching
+
+Refetching enables you to refresh query results in response to a particular user action, as opposed to using a fixed interval.
+
+Let's add a button to our `DogPhoto` component that calls our query's `refetch` function whenever it's clicked.
+
+You can optionally provide a new `variables` object to the `refetch` function. If you don't provide a `variables` object, the query uses the same `variables` object that it used in its previous execution.
+
+JavaScript
+
+index.js
+
+copy
+
+
+ 1function DogPhoto({ breed }) {
+ 2 const { loading, error, data, refetch } = useQuery(GET_DOG_PHOTO, {
+ 3 variables: { breed },
+ 4 });
+ 5
+ 6 if (loading) return null;
+ 7 if (error) return `Error! ${error}`;
+ 8
+ 9 return (
+ 10 <div>
+ 11 <img src={data.dog.displayImage} style={{ height: 100, width: 100 }} />
+ 12 <button onClick={() => refetch()}>Refetch new breed!</button>
+ 13 </div>
+ 14 );
+ 15}
+
+Click the button and notice that the UI updates with a new dog photo. Refetching is an excellent way to guarantee fresh data, but it introduces some complexity with loading state. In the next section, we'll cover strategies for handling complex loading and error state.
+
+#### Providing new variables to `refetch`
+
+You call `refetch` with a new set of variables like so:
+
+JavaScript
+
+copy
+
+
+ 1<button
+ 2 onClick={() =>
+ 3 refetch({
+ 4 breed: "dalmatian", // Always refetches a dalmatian instead of original breed
+ 5 })
+ 6 }
+ 7>
+ 8 Refetch!
+ 9</button>;
+
+If you provide new values for _some_ of your original query's variables but not _all_ of them, `refetch` uses each omitted variable's original value.
+
+## Inspecting loading states
+
+We've already seen that the `useQuery` hook exposes our query's current loading state. This is helpful when a query first loads, but what happens to our loading state when we're refetching or polling?
+
+Let's return to our refetching example from the previous section. If you click the refetch button, you'll see that the component re-renders while we're refetching the photo.
+
+The `useQuery` hook's result object provides fine-grained information about the status of the query via the `networkStatus` property. This allows us to indicate to the user that we're refetching the photo:
+
+JavaScript
+
+index.js
+
+copy
+
+
+ 1import { NetworkStatus } from "@apollo/client";
+ 2
+ 3function DogPhoto({ breed }) {
+ 4 const { loading, error, data, refetch, networkStatus } = useQuery(
+ 5 GET_DOG_PHOTO,
+ 6 {
+ 7 variables: { breed },
+ 8 }
+ 9 );
+ 10
+ 11 if (networkStatus === NetworkStatus.refetch) return "Refetching!";
+ 12 if (loading) return null;
+ 13 if (error) return `Error! ${error}`;
+ 14
+ 15 return (
+ 16 <div>
+ 17 <img src={data.dog.displayImage} style={{ height: 100, width: 100 }} />
+ 18 <button onClick={() => refetch()}>Refetch!</button>
+ 19 </div>
+ 20 );
+ 21}
+
+The value of `loading` also updates accordingly. Even if you don't use the more fine-grained information provided by the `networkStatus` property, the `loading` property indicates that the refetch is in progress.
+
+The `networkStatus` property is a `NetworkStatus` enum that represents different loading states. Refetch is represented by `NetworkStatus.refetch`. There are additional values for e.g. polling and pagination. For a full list of all the possible loading states, check out [this table](https://www.apollographql.com/docs/react/api/core/ObservableQuery#networkstatus).
+
+**note**
... 25038 lines suppressed ...