Skip to content

Jeffallan/claude-skills / skills/graphql-architect

graphql-architect

Verified

Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives.

FileKindSize
SKILL.mdskill md5.1 KB
references/federation.mdmarkdown9.0 KB
references/migration-from-rest.mdmarkdown24.4 KB
references/resolvers.mdmarkdown10.0 KB
references/schema-design.mdmarkdown6.4 KB
references/security.mdmarkdown12.9 KB
references/subscriptions.mdmarkdown11.9 KB

references/schema-design.md

View on GitHub
# GraphQL Schema Design

## Object Types

```graphql
"""
User account with authentication and profile information.
All users must have a unique email address.
"""
type User {
  "Unique user identifier"
  id: ID!
  "User's email address (unique)"
  email: String!
  "Display name (optional)"
  username: String
  "Account creation timestamp"
  createdAt: DateTime!
  "User's posts (paginated)"
  posts(first: Int = 10, after: String): PostConnection!
  "User's profile (nullable if not completed)"
  profile: Profile
}

type Profile {
  id: ID!
  bio: String
  avatarUrl: URL
  website: URL
  location: String
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  publishedAt: DateTime
  status: PostStatus!
  tags: [Tag!]!
  comments(first: Int, after: String): CommentConnection!
}
```

## Interfaces

```graphql
"""
Common interface for all content that can be timestamped
"""
interface Timestamped {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
}

"""
Interface for searchable content
"""
interface Searchable {
  id: ID!
  title: String!
  description: String
}

type Article implements Timestamped & Searchable {
  id: ID!
  title: String!
  description: String
  content: String!
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User!
}

type Video implements Timestamped & Searchable {
  id: ID!
  title: String!
  description: String
  url: URL!
  duration: Int!
  createdAt: DateTime!
  updatedAt: DateTime!
  uploader: User!
}

# Query returning interface
type Query {
  search(query: String!): [Searchable!]!
}
```

## Union Types

```graphql
"""
Result of a content search - can be Article, Video, or Podcast
"""
union SearchResult = Article | Video | Podcast

"""
Notification types that users can receive
"""
union Notification = CommentNotification | LikeNotification | FollowNotification

type CommentNotification {
  id: ID!
  comment: Comment!
  post: Post!
  createdAt: DateTime!
}

type LikeNotification {
  id: ID!
  liker: User!
  post: Post!
  createdAt: DateTime!
}

type Query {
  searchContent(query: String!): [SearchResult!]!
  notifications(first: Int): [Notification!]!
}
```

## Enums

```graphql
"""
Post publication status
"""
enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
  DELETED
}

"""
User role for authorization
"""
enum UserRole {
  ADMIN
  MODERATOR
  USER
  GUEST
}

"""
Sort direction for queries
"""
enum SortOrder {
  ASC
  DESC
}

type Query {
  posts(
    status: PostStatus
    orderBy: SortOrder = DESC
  ): [Post!]!
}
```

## Input Types

```graphql
"""
Input for creating a new user
"""
input CreateUserInput {
  email: String!
  password: String!
  username: String
  profile: ProfileInput
}

input ProfileInput {
  bio: String
  avatarUrl: URL
  website: URL
  location: String
}

"""
Input for updating a post
"""
input UpdatePostInput {
  title: String
  content: String
  status: PostStatus
  tags: [ID!]
}

"""
Pagination and filtering input
"""
input PostFilterInput {
  status: PostStatus
  authorId: ID
  tags: [String!]
  search: String
  createdAfter: DateTime
  createdBefore: DateTime
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updatePost(id: ID!, input: UpdatePostInput!): Post!
}

type Query {
  posts(filter: PostFilterInput, first: Int, after: String): PostConnection!
}
```

## Custom Scalars

```graphql
"""
ISO 8601 date-time string
"""
scalar DateTime

"""
Valid URL string
"""
scalar URL

"""
Valid email address
"""
scalar Email

"""
JSON object
"""
scalar JSON

"""
Positive integer
"""
scalar PositiveInt

type User {
  id: ID!
  email: Email!
  createdAt: DateTime!
  website: URL
  metadata: JSON
  age: PositiveInt
}
```

## Pagination Patterns

```graphql
"""
Cursor-based pagination (Relay specification)
"""
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type PostEdge {
  node: Post!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

type Query {
  posts(
    first: Int
    after: String
    last: Int
    before: String
  ): PostConnection!
}
```

## Nullable vs Non-Nullable Best Practices

```graphql
type User {
  # Non-nullable: guaranteed to exist
  id: ID!
  email: String!
  createdAt: DateTime!

  # Nullable: optional or may not exist yet
  username: String
  bio: String
  avatarUrl: URL

  # Non-null list of nullable items
  # List always exists but can be empty, items can be null
  tags: [String]!

  # Non-null list of non-null items
  # List always exists, all items guaranteed non-null
  roles: [UserRole!]!

  # Nullable list of non-null items
  # List may be null, but if exists, all items non-null
  posts: [Post!]
}

type Query {
  # Non-null: query always returns result (empty list if none)
  users: [User!]!

  # Nullable: may return null if not found
  user(id: ID!): User

  # Non-null: guaranteed to return result or error
  currentUser: User!
}
```

## Field Deprecation

```graphql
type User {
  id: ID!
  email: String!

  # Deprecated field with migration path
  name: String @deprecated(reason: "Use 'username' instead")
  username: String

  # Deprecated with specific date
  legacyId: String @deprecated(
    reason: "Migrating to UUID. Will be removed 2025-06-01"
  )
}
```

## Schema Documentation

```graphql
"""
User represents an authenticated account in the system.
Users can create posts, comments, and interact with content.

Example query:
```
query GetUser {
  user(id: "123") {
    email
    username
    posts(first: 10) {
      edges {
        node {
          title
        }
      }
    }
  }
}
```
"""
type User {
  "Unique identifier for the user"
  id: ID!

  "Email address (must be unique across all users)"
  email: String!

  "Optional display name (defaults to email if not set)"
  username: String
}
```

## Design Principles

1. **Nullable Fields**: Make fields nullable by default unless guaranteed to exist
2. **List Fields**: Use `[Type!]!` for lists that always exist with non-null items
3. **Documentation**: Document all types and fields with descriptions
4. **Naming**: Use camelCase for fields, PascalCase for types
5. **Interfaces**: Use interfaces for shared fields across types
6. **Unions**: Use unions for polymorphic return types
7. **Input Types**: Create separate input types for mutations
8. **Scalars**: Use custom scalars for domain-specific types
9. **Deprecation**: Mark deprecated fields, provide migration path
10. **Examples**: Include example queries in documentation
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall