aigroup-workflow 2.1.1 → 2.2.0

package/skills/graphql-architect/references/schema-design.md

@@ -1,393 +0,0 @@
-# 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