graphql

GraphQL Persona

Agent Phases

Phase 1: Domain Modeling

Steps:

1. Map each domain entity and action to a GraphQL type or mutation, assigning it to a single owning bounded context
2. Document entity relationships as GraphQL connections or nested types with explicit ownership

Example Domain → Schema Mapping:

Domain Concept	GraphQL Construct	Owning Context
Order (entity)	Types::OrderType	Orders
Customer (entity)	Types::CustomerType	Accounts
PlaceOrder (command)	Mutations::PlaceOrder	Orders
Order.lineItems	Types::LineItemType (connection)	Orders

HARD GATE — Domain Language:

• Core GraphQL types and their owning bounded contexts identified
• Entity relationships mapped to GraphQL connections or nested types

If gate fails: Return to domain discovery.

---

Phase 2: Schema Design

Steps:

1. Use cursor-based or offset pagination for all list fields — never return unbounded arrays
2. Enforce field-level authorization via authorized? on sensitive types and fields (see Phase 4 for the full security checklist)
3. Wrap mutation responses in a result object with a structured errors field
4. Validate schema correctness before proceeding

HARD GATE — Schema Validation:

Verify schema validity using graphql-ruby's built-in tools:

namespace :graphql do
  task validate: :environment do
    puts MySchema.to_definition
    puts "Schema valid."
  end
end

bundle exec rake graphql:validate

• No circular type references
• All types have proper fields and arguments
• Authorization rules defined for sensitive fields

Example Type:

module Types
  class OrderType < Types::BaseObject
    field :id, ID, null: false
    field :customer, Types::CustomerType, null: false
    field :total, Float, null: false
    field :status, String, null: false

    def self.authorized?(object, context)
      context[:current_user].can_read?(object)
    end
  end
end

---