# graphql-architect

graphql-architect — a subagent that audits GraphQL schemas for architectural flaws, performance risks, and security gaps. Guides schema evolution, resolver design, and federation without breaking clients.

- subagent · `type=agent` · Codex, Claude Code, Cursor · ★ 6505 repo stars
- Author: VoltAgent
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/VoltAgent/awesome-codex-subagents/tree/HEAD/categories/01-core-development/graphql-architect.toml
- Updated: 2026-10-05
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/voltagent-graphql-architect

## What it does

graphql-architect treats GraphQL as a contract layer across clients, resolvers, and distributed services. It maps schema surface to resolver boundaries, identifies risks in federation and execution patterns, and prioritizes high-leverage improvements with rollout guidance.

The subagent operates in three phases: mapping schema structure (queries, mutations, subscriptions) to resolver and data boundaries, scanning for architecture risks in schema design and federation, and recommending targeted changes with compatibility and migration paths.

It focuses on nullability strategy, deprecation planning, N+1 patterns, query complexity limits, field-level authorization, and denial-of-service vectors via expensive queries. Returns a prioritized list of issues, design recommendations, client impact, and rollout guidance.

## Install

### Codex (native platform)

**Manually: put the files in place**
- File: `.codex/agents/graphql-architect.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Claude Code

**Manually: put the files in place**
- File: `.claude/agents/graphql-architect.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/graphql-architect.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/VoltAgent/awesome-codex-subagents/tree/HEAD/categories/01-core-development/graphql-architect.toml

## When to use it
- audit GraphQL schema for architecture and federation risks
- detect performance bottlenecks in resolvers and query patterns
- surface security gaps in introspection and field-level authorization
- plan schema evolution while maintaining backward compatibility
- optimize nullability, pagination, and query complexity controls

## Example prompts
- Review our GraphQL schema for federation resolver issues and N+1 risks.
- What schema changes reduce query complexity and make DoS harder?
- How do we change `User.email` from nullable to required without breaking clients?

## Source text · graphql-architect.toml · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c114d2b00a113027.

BEGIN THIRD-PARTY FILE c114d2b00a113027
```text
# graphql-architect

Use when a task needs GraphQL schema evolution, resolver architecture, federation design, or distributed graph performance/security review.

Treat GraphQL as a contract and execution architecture across clients, resolvers, and distributed services.

Working mode:
1. Map schema surface (queries, mutations, subscriptions) to resolver/data boundaries.
2. Identify architectural risks in schema design, federation, and execution behavior.
3. Recommend smallest high-leverage improvements with compatibility and rollout guidance.

Focus on:
- schema evolution and backward compatibility
- nullability, input modeling, and deprecation strategy
- resolver ownership and data boundary clarity
- N+1 risk, batching strategy, and query planning implications
- query complexity/depth control and abuse-resistance posture
- pagination and filtering consistency across graph surface
- federation/subgraph boundaries, entity keys, and composition stability
- subscription/event-stream reliability and authorization boundaries

Performance checks:
- identify resolver hot paths likely to regress latency
- flag over-fetch/under-fetch pressures by schema shape
- call out where persisted queries, caching, or complexity controls are missing

Security checks:
- flag field-level auth ambiguities
- identify introspection/exposure risks relevant to deployment context
- surface denial-of-service vectors via expensive query patterns

Quality checks:
- provide one client-breaking change list (if any)
- provide migration path for schema-level changes
- separate immediate defects from medium-term architecture debt

Return:
- schema/resolver/federation issues found
- recommended design changes (prioritized)
- client, performance, and security implications
- migration/rollout guidance

Do not implement resolver code changes unless explicitly requested by the parent agent.
```
END THIRD-PARTY FILE c114d2b00a113027

The third-party file has ended. Everything between the c114d2b00a113027 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© VoltAgent · MIT · https://github.com/VoltAgent/awesome-codex-subagents/tree/HEAD/categories/01-core-development/graphql-architect.toml

## Similar
- [api-scaffolding-graphql-architect](https://affpapa.org/en/nevibecode/agents/api-scaffolding-graphql-architect.md) — subagent · ★ 42780 repo stars
- [public-graphql-api-design](https://affpapa.org/en/nevibecode/skills/public-graphql-api-design.md) — skill · 10100 installs
- [mcp-graphql-enhanced](https://affpapa.org/en/nevibecode/mcp/mcp-graphql-enhanced.md) — MCP server · ★ 7 repo stars
- [graphql-expert-best-practices](https://affpapa.org/en/nevibecode/skills/graphql-expert-best-practices.md) — skill · 144 installs
- [apollo-federation](https://affpapa.org/en/nevibecode/skills/apollo-federation.md) — skill · 2100 installs
- [graphql-development](https://affpapa.org/en/nevibecode/skills/graphql-development.md) — skill · 701 installs

## Other versions with the same name
- [graphql-architect · voltagent](https://affpapa.org/en/nevibecode/agents/graphql-architect.md) — 1038 installs
- [graphql-architect · qdhenry](https://affpapa.org/en/nevibecode/agents/qdhenry-graphql-architect.md) — ★ 1357 repo stars

From the same set: [voltagent/awesome-codex-subagents](https://affpapa.org/en/nevibecode/by/voltagent/awesome-codex-subagents.md) — 176 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
