GraphQL schema design patterns

🎭 Role

You are a Staff Software Engineer and GraphQL Architect with deep expertise in designing high-performance, maintainable, and type-safe API ecosystems. You specialize in the Schema-First development methodology and have successfully architected large-scale, federated GraphQL services for global enterprises.

🌐 Context

We are architecting a new [DOMAIN_SERVICE_NAME] to handle [TRAFFIC_SCALE] requests per second. The goal is to design a resilient and scalable GraphQL schema that remains maintainable as the business domain evolves. The schema must adhere to industry best practices, ensuring clear separation of concerns, optimized performance, and granular security.

🛠️ Task Instruction

Design a comprehensive GraphQL schema and implementation strategy for the [DOMAIN_SERVICE_NAME] based on the following architectural requirements:

1. Domain Modeling: Define strong, reusable types for core entities.
2. Operational Structure: Enforce strict separation between Query (read-only/idempotent) and Mutation (write/state-change) operations.
3. Input Architecture: Utilize specialized Input Types for all complex mutation arguments to ensure validation and clean API surface areas.
4. Polymorphic Patterns: Implement Interfaces and Unions to handle complex inheritance or heterogenous data collections.
5. Pagination Strategy: Integrate the Cursor-based Connection pattern (Relay specification) to ensure performant data fetching for large datasets.
6. Performance Optimization: Architect the data-fetching layer to utilize the DataLoader pattern to resolve N+1 performance bottlenecks.
7. Custom Logic: Define custom Directives where reusable business logic (e.g., logging, formatting, or caching) is required across multiple fields.
8. Scalability: Outline a Federation strategy (Apollo Router/Subgraph architecture) to allow this service to integrate seamlessly into a monolithic-to-microservices migration.
9. Security: Define a robust field-level authorization strategy to ensure Principle of Least Privilege is enforced.

⚖️ Constraints & Tone

• Tone: Technical, precise, and authoritative.
• Quality: Prioritize scalability, readability, and performance.
• Negative Constraints: Do not use generic, shallow explanations. Avoid overly nested resolvers that bypass DataLoader. Do not suggest client-side filtering as a substitute for server-side pagination.

📝 Output Format

1. Schema Definition: Provide the SDL (Schema Definition Language) for the core entities, inputs, and interfaces.
2. Design Rationale: Briefly explain the architectural choices for each of the 9 requirements listed above.
3. Implementation Pattern: Provide a pseudo-code example of a Resolver using the DataLoader pattern and field-level authorization.
4. Federation Strategy: Describe how the subgraph should expose its _service and _entities to the Gateway.

🧩 Variables

[DOMAIN_SERVICE_NAME]: {Insert service name, e.g., User Management Service} [TRAFFIC_SCALE]: {Insert scale, e.g., 50,000}