Advanced

Domain-Driven Design (DDD)

Core Concepts

Fundamentals

DDD Concept	Definition	Characteristics	Considerations	Example
Ubiquitous Language	A common language shared between domain experts and developers, reflected in code and schema	Type names must use domain terminology, not technical terms Field names should match business vocabulary exactly Descriptions should use domain language	All type names use business terminology Field names match domain expert vocabulary Schema descriptions use ubiquitous language No technical jargon in public schema Consistent terminology across all types	# ✅ Good - Uses domain language type Order { orderNumber: String! customer: Customer! lineItems: [LineItem!]! totalAmount: Money! status: OrderStatus! } # ❌ Bad - Uses technical language type OrderRecord { id: ID! customerId: ID! items: [OrderItemRecord!]! total: Float! statusCode: Int! }
Bounded Contexts	Explicit boundaries within which a domain model is defined and applicable	Each subgraph represents one bounded context Types within a context have consistent meaning Cross-context references use federation	Each subgraph maps to exactly one bounded context No overlapping responsibilities between subgraphs Clear ownership boundaries defined Context boundaries align with team boundaries Minimal coupling between contexts	Consider separate bounded contexts when applicable: Does this concept have different meanings in different parts of the business? Do different teams own different aspects of this concept? Would changes to this concept affect different business capabilities?
Entities	Objects with distinct identity that persists over time	Always have an id field Identity is stable across operations Can be referenced from other contexts Support federation @key directive	All entities have stable identity fields Identity fields are immutable Entities can be federated across subgraphs Entity boundaries respect aggregate boundaries Identity generation strategy is consistent	type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! # Entity-specific behavior orders: [Order!]! }
Value Objects	Objects that describe characteristics but have no conceptual identity	No id field Immutable by design Compared by value, not identity Often embedded within entities	Value objects have no identity fields All fields are non-nullable where appropriate Value objects are immutable Validation rules are embedded in type design Consistent representation across contexts	type Money { amount: Decimal! currency: Currency! } type Address { street: String! city: String! postalCode: String! country: Country! }
Aggregates	Clusters of entities and value objects that are treated as a single unit for data changes	Root entity serves as aggregate root Internal consistency maintained within aggregate External references only to aggregate root Mutations operate on entire aggregate	Aggregate root is clearly identified Internal entities not exposed as top-level types Mutations target aggregate roots only Aggregate boundaries respect business invariants Cross-aggregate references use IDs only	# Aggregate Root type Order @key(fields: "id") { id: ID! orderNumber: String! customer: Customer! # External reference lineItems: [LineItem!]! # Internal entities shippingAddress: Address! # Value object totalAmount: Money! # Value object status: OrderStatus! } # Internal Entity (not directly accessible) type LineItem { productId: ID! quantity: Int! unitPrice: Money! lineTotal: Money! }
Domain Services	Operations that don't naturally belong to entities or value objects	Implemented as mutations or queries Operate across multiple aggregates Encapsulate complex business logic	Domain services have clear business purpose Services operate on domain concepts, not data structures Complex business rules encapsulated in services Services maintain aggregate boundaries Input/output types use domain language	type Mutation { # Domain Service: Order Processing processOrder(input: ProcessOrderInput!): ProcessOrderPayload! # Domain Service: Inventory Allocation allocateInventory(input: AllocateInventoryInput!): AllocationResult! } type Query { # Domain Service: Pricing Calculation calculateShipping(input: ShippingCalculationInput!): ShippingQuote! }
Domain Events	Something that happened in the domain that domain experts care about	Modeled as types for event sourcing Used in subscriptions for real-time updates Enable loose coupling between contexts	Events represent business-significant occurrences Event names use past tense Events are immutable Events include necessary context data Event versioning strategy defined	type OrderPlaced implements DomainEvent { eventId: ID! aggregateId: ID! occurredAt: DateTime! version: Int! # Event-specific data orderNumber: String! customerId: ID! totalAmount: Money! } type Subscription { orderEvents(customerId: ID): OrderEvent! } union OrderEvent = OrderPlaced | OrderShipped | OrderCancelled

Federation

DDD Concept	Definition	Characteristics	Considerations	Example
Subgraph as Bounded Context	A subgraph represents a bounded context in a federated architecture, owned by a domain-specific team	One subgraph per bounded context Autonomous deployment and ownership Minimal external dependencies	Align subgraphs with team responsibilities Ensure clear boundaries and independence	# Customer Subgraph type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! contactInformation: ContactInfo! }
Entity Ownership and Extension	Entities are defined in their owning context and extended elsewhere with relevant data only	Primary definition includes full business meaning Extensions only add context-specific info	Respect ownership boundaries Mark external fields properly	# Primary (Customer Subgraph) type Customer @key(fields: "id") { id: ID! customerNumber: String! } # Extension (Order Subgraph) extend type Customer @key(fields: "id") { id: ID! @external orders: [Order!]! }
Cross-Context References	Reference external entities via ID or use federated references for richer linking across subgraphs	Use stable identifiers Maintain referential integrity	Avoid embedding external data Resolve federated references correctly	type Order @key(fields: "id") { id: ID! customerId: ID! } # Federated reference type Order @key(fields: "id") { id: ID! customer: Customer! }
Aggregate-Centric Design	Subgraphs encapsulate domain aggregates, exposing root and child entities along with behavior (mutations)	Encapsulates full aggregate Mutations scoped to aggregate boundaries	Maintain invariants within subgraph Ensure ownership and isolation	# Order Aggregate type Order @key(fields: "id") { id: ID! lineItems: [LineItem!]! } type Mutation { placeOrder(input: PlaceOrderInput!): PlaceOrderPayload! }
Capability-Centric Subgraph	Organize subgraphs around business capabilities such as pricing, inventory, or promotions	Focused service interfaces Minimal external data access	Boundaries must be clearly defined Keep internal logic self-contained	# Pricing Subgraph type Query { calculatePrice(input: PriceCalculationInput!): PriceQuote! }
Event-Driven Subgraph	Subgraphs that publish or consume domain events for reactive architectures	Implements event types Subscription-based updates	Ensure schema stability for events Preserve event order	# Inventory Events type Subscription { inventoryUpdates(productIds: [ID!]): InventoryUpdate! }
Federation Directives	Directives like @key, @external, @requires, and @provides support cross-subgraph coordination	@key defines identity @external marks fields from other contexts @requires declares data dependencies @provides exposes computed fields	Use keys that are stable and immutable Track data ownership and resolution logic	extend type Customer @key(fields: "id") { id: ID! @external email: String! @external preferences: Preferences! @requires(fields: "email") }
Schema Composition Strategy	Ensure consistent and valid schema composition across all subgraphs	No conflicting definitions External references resolvable	Detect circular dependencies early Validate supergraph composition regularly
Query Planning Optimization	Optimize how queries are planned and resolved across subgraphs in the federated graph	Batch calls to reduce latency Cache federation metadata	Monitor performance and plan cost Limit query complexity

DDD

Bounded Context

DDD Concept	Definition	Characteristics	Considerations	Example
Bounded Context Mapping	A strategic design practice that defines explicit boundaries between different parts of a domain model	In GraphQL federation, these boundaries directly translate to subgraph boundaries	Crucial for successful federated architecture
Context Identification Strategy: Business Capability Analysis	Identify distinct business capabilities and their boundaries	Delivers independent business value Can be owned by a single team Has its own data and business rules	Each capability delivers independent value Clear ownership boundaries defined Minimal overlap between capabilities Capabilities align with organizational structure Data ownership clearly defined	E-commerce Domain: ├── Customer Management │ ├── Customer Registration │ ├── Profile Management │ └── Customer Support ├── Product Catalog │ ├── Product Information │ ├── Inventory Management │ └── Pricing ├── Order Management │ ├── Order Processing │ ├── Payment Processing │ └── Fulfillment └── Marketing ├── Promotions ├── Recommendations └── Analytics
Context Identification Strategy: Data Ownership Analysis	Identify which parts of the domain model are owned by which contexts	Single context creates data Single context has authority to change data	Each data element has single owner Ownership aligns with business authority Cross-context references use IDs No shared mutable state Data consistency responsibilities clear	type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! contactInfo: ContactInfo! } # Order Context - Owns order data, references customer type Order @key(fields: "id") { id: ID! customerId: ID! # Reference, not ownership orderNumber: String! lineItems: [LineItem!]! # Owns line items } # Product Context - Owns product information type Product @key(fields: "id") { id: ID! sku: String! name: String! description: String! }
Context Identification Strategy: Team Boundary Analysis	Align context boundaries with team structure and expertise	One team per bounded context Team has domain expertise for their context Team can make independent decisions	One team per bounded context Team has domain expertise for their context Team can make independent decisions Minimal coordination required between teams Clear escalation paths for cross-context issues	Team Structure → Context Mapping: Frontend Team → Customer Experience Context ├── User Interface ├── User Experience └── Client-side State Backend Teams: ├── Customer Team → Customer Management Context ├── Catalog Team → Product Catalog Context ├── Order Team → Order Management Context └── Platform Team → Shared Infrastructure Context
Context Relationship Pattern: Shared Kernel	Two contexts share a common subset of the domain model	Common value objects across contexts Shared business rules Small, stable shared model	Shared model is small and stable Changes require coordination Shared types are value objects No shared entities Clear governance for shared model	scalar Money scalar DateTime enum Currency { USD EUR GBP } type Address { street: String! city: String! postalCode: String! country: String! }
Context Relationship Pattern: Customer-Supplier	One context (supplier) provides services to another context (customer)	Clear supplier-customer relationship Supplier provides stable interface Customer adapts to supplier changes	Clear supplier-customer relationship Supplier provides stable interface Customer adapts to supplier changes Service level agreements defined Backward compatibility maintained	type Product @key(fields: "id") { id: ID! sku: String! name: String! price: Money! } # Customer Context (Order Management) extend type Product @key(fields: "id") { id: ID! @external # Uses product data for order processing } type LineItem { product: Product! quantity: Int! unitPrice: Money! }
Context Relationship Pattern: Conformist	Customer context conforms to supplier's model without translation	Supplier has strong domain expertise Customer has limited influence Integration cost is high	Supplier model fits customer needs Customer accepts supplier changes No translation layer needed Clear dependency management Supplier stability assessed	# Supplier defines the model type PaymentMethod { id: ID! type: PaymentType! details: PaymentDetails! } # Customer uses model as-is type Order { id: ID! paymentMethod: PaymentMethod! # Direct usage }
Context Relationship Pattern: Anti-Corruption Layer	Customer context translates supplier's model to protect its own model	Supplier model doesn't fit domain Legacy system integration External service integration	Translation layer implemented Internal model protected Translation logic tested Performance impact considered Error handling for translation failures	# External Supplier Model (legacy system) type LegacyCustomer { custId: String! custName: String! custAddr: String! } # Internal Domain Model type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! address: Address! } # Translation in resolver layer (not shown in schema)
Context Relationship Pattern: Open Host Service	Context provides a well-defined service interface for multiple customers	Stable, well-documented interface Multiple consumer contexts Versioning strategy defined	Stable, well-documented interface Multiple consumer contexts Versioning strategy defined Service level agreements Consumer feedback incorporated	# Open Host Service - Product Catalog type Query { product(id: ID!): Product products(filter: ProductFilter): [Product!]! searchProducts(query: String!): ProductSearchResult! } type Product @key(fields: "id") { id: ID! sku: String! name: String! description: String! category: Category! price: Money! availability: Availability! } # Well-defined, stable interface for multiple consumers
Context Relationship Pattern: Published Language	Shared language for integration between contexts	Common language defined Event schemas documented Versioning strategy in place	Common language defined Event schemas documented Versioning strategy in place Consumer compatibility maintained Schema evolution managed	# Published Language - Domain Events interface DomainEvent { eventId: ID! aggregateId: ID! eventType: String! occurredAt: DateTime! version: Int! } type CustomerRegistered implements DomainEvent { eventId: ID! aggregateId: ID! eventType: String! occurredAt: DateTime! version: Int! # Event-specific data customerId: ID! customerNumber: String! email: String! }
Context Mapping in Federation: Subgraph Boundary Definition	Mapping Bounded Contexts to Subgraphs in a federated GraphQL architecture	Represents a single bounded context Can be owned by a single team Entities and operations are cohesive	One bounded context per subgraph Clear entity ownership Cohesive operations Minimal cross-subgraph dependencies Team ownership aligned	Bounded Context → Subgraph Mapping: Customer Management Context → Customer Subgraph ├── Customer entity (primary) ├── Customer profile management ├── Customer authentication └── Customer preferences Product Catalog Context → Product Subgraph ├── Product entity (primary) ├── Product categories ├── Product attributes └── Product search Order Management Context → Order Subgraph ├── Order entity (primary) ├── Order processing ├── Order status tracking └── Order history
Cross-Context Integration Pattern: Event-Driven Integration	Use domain events for loose coupling between contexts	Events represent business occurrences Event schemas are stable Eventual consistency acceptable	Events represent business occurrences Event schemas are stable Eventual consistency acceptable Error handling for event processing Event ordering considerations	# Publishing Context type Mutation { placeOrder(input: PlaceOrderInput!): PlaceOrderPayload! } type Subscription { orderEvents: OrderEvent! } union OrderEvent = OrderPlaced | OrderShipped | OrderCancelled # Consuming Context type Subscription { # Subscribe to events from other contexts customerOrderEvents(customerId: ID!): OrderEvent! }
Cross-Context Integration Pattern: Synchronous Integration	Direct federation for immediate consistency needs	Immediate consistency required Performance implications understood Fallback strategies defined	Immediate consistency required Performance implications understood Fallback strategies defined Circuit breaker patterns implemented Monitoring and alerting in place	# Customer Context type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! } # Order Context extend type Customer @key(fields: "id") { id: ID! @external orders: [Order!]! # Real-time access to orders currentOrder: Order # Immediate consistency needed }
Context Evolution Strategy: Context Splitting	Dividing a large or complex context into smaller, more manageable ones	Context becomes too large Multiple teams need ownership Different change frequencies Distinct business capabilities emerge	Clear split rationale New boundaries defined Data migration planned Interface contracts established Rollback strategy prepared
Context Evolution Strategy: Context Merging	Consolidating smaller or highly coupled contexts into a single, unified context	Contexts are too small High coupling between contexts Single team ownership Shared data model	Merge benefits clear Unified model designed Migration strategy defined Team alignment achieved Monitoring during transition

Entity Aggregate

DDD Concept	Definition	Characteristics	Considerations	Example
Ubiquitous Language	A common language shared between domain experts and developers, reflected in code and schema	Type names must use domain terminology, not technical terms	All type names use business terminology	# ✅ Good - Uses domain language type Order { orderNumber: String! customer: Customer! lineItems: [LineItem!]! totalAmount: Money! status: OrderStatus! } # ❌ Bad - Uses technical language type OrderRecord { id: ID! customerId: ID! items: [OrderItemRecord!]! total: Float! statusCode: Int! }
Entity Identity Design	Every entity must have a stable, unique identity that persists throughout its lifecycle	Identity fields are immutable Identity fields are unique across all instances Identity generation strategy is consistent Identity fields are suitable for federation keys Business meaning of identity is clear	Is there a natural business identifier? (Yes → Business key; No → Technical identifier) Is the business identifier immutable? (No → Technical identifier; Yes → Business key) Do external systems need specific identifier format? (Yes → Multiple keys; No → Single key)	# UUID-based identity type Customer @key(fields: "id") { id: ID! # UUID: "550e8400-e29b-41d4-a716-446655440000" customerNumber: String! profile: CustomerProfile! } # Business key identity type Product @key(fields: "sku") { sku: String! # Business key: "LAPTOP-DELL-XPS13" name: String! description: String! } # Composite identity type OrderLineItem @key(fields: "orderId productSku") { orderId: ID! productSku: String! quantity: Int! unitPrice: Money! } # Multiple identity options type Customer @key(fields: "id") @key(fields: "customerNumber") { id: ID! customerNumber: String! # Alternative key for legacy systems email: String! }
Entity Lifecycle Modeling	Model entity states and transitions explicitly in the schema	All possible states explicitly modeled State transitions are clear Lifecycle timestamps included State-dependent fields identified Invalid state combinations prevented	Explicitly define all possible states Ensure clear transitions between states Include timestamps for key lifecycle events Identify fields that are dependent on the entity's state	type Order @key(fields: "id") { id: ID! orderNumber: String! status: OrderStatus! createdAt: DateTime! updatedAt: DateTime! # Lifecycle-specific fields placedAt: DateTime shippedAt: DateTime deliveredAt: DateTime cancelledAt: DateTime # State-dependent data trackingNumber: String # Only available when shipped cancellationReason: String # Only available when cancelled } enum OrderStatus { DRAFT PLACED CONFIRMED SHIPPED DELIVERED CANCELLED RETURNED }
Owned Relationships	Entity owns and manages related entities within aggregate boundary	Owned entities not exposed as top-level types Owned entities have no independent identity Lifecycle tied to owning entity Consistency maintained within aggregate No external references to owned entities	Are the related entities always accessed and managed through the owning entity? Do the related entities lack independent meaning outside the owner? Is their lifecycle directly dependent on the owning entity's lifecycle?	type Order @key(fields: "id") { id: ID! # Owned entities - managed within aggregate lineItems: [LineItem!]! # Order owns line items shippingAddress: Address! # Order owns shipping address billingAddress: Address! # Order owns billing address } type LineItem { # No @key directive - not independently accessible productSku: String! quantity: Int! unitPrice: Money! lineTotal: Money! }
Referenced Relationships	Entity references other entities by identity	References use stable identifiers Referenced entities defined in appropriate contexts Federation directives correctly applied Circular dependencies avoided Reference integrity handled at application level	Are the referenced entities independent and can exist without the referencing entity? Do the referenced entities have their own lifecycle and management? Is data consistency across these entities handled at a higher level (e.g., eventual consistency)?	type Order @key(fields: "id") { id: ID! customerId: ID! # Reference to Customer entity # Federated reference - resolved across subgraphs customer: Customer! } # Customer defined in different subgraph extend type Customer @key(fields: "id") { id: ID! @external orders: [Order!]! # Back-reference }
Aggregate Root Design	Each aggregate has exactly one root entity that serves as the entry point	Single aggregate root identified Root entity has clear identity All aggregate components accessible through root Business invariants maintained at aggregate level Aggregate boundaries respect consistency requirements	What is the primary entity that all other entities within the aggregate depend on? Does this root encapsulate all changes to its internal entities? Are all business rules and invariants applied at the root level?	# Aggregate Root type Order @key(fields: "id") { id: ID! orderNumber: String! customerId: ID! # Aggregate components lineItems: [LineItem!]! shippingAddress: Address! billingAddress: Address! # Aggregate-level computed fields totalAmount: Money! itemCount: Int! status: OrderStatus! # Aggregate behavior canBeCancelled: Boolean! canBeModified: Boolean! } # Internal entities - not directly accessible type LineItem { productSku: String! productName: String! quantity: Int! unitPrice: Money! lineTotal: Money! } # Value objects type Address { street: String! city: String! postalCode: String! country: String! }
Aggregate Boundary Definition	Defines the scope of consistency and transactional integrity	Aggregate boundaries respect business invariants Entities within aggregate are highly cohesive Cross-aggregate references use IDs Aggregate size is manageable Consistency requirements clearly defined	Do these entities need to be consistent together? (Yes → Same aggregate; No → Different aggregates) Do these entities change together? (Yes → Same aggregate; No → Different aggregates) Can these entities exist independently? (No → Same aggregate; Yes → Different aggregates) Is the relationship ownership or reference? (Ownership → Same aggregate; Reference → Different aggregates)	# Single Aggregate: Order + LineItems + Addresses type Order @key(fields: "id") { id: ID! # These must be consistent together lineItems: [LineItem!]! # Owned - same aggregate shippingAddress: Address! # Owned - same aggregate totalAmount: Money! # Computed from line items } # Separate Aggregate: Customer type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! # Orders reference customer but are separate aggregates } # Reference between aggregates type Order @key(fields: "id") { customerId: ID! # Reference, not ownership customer: Customer! # Federated reference }
Aggregate Operations	Design mutations that operate on complete aggregates	Mutations target aggregate roots Input types include all necessary data Business rules validated in mutations Aggregate consistency maintained Error handling for business rule violations	Do the mutations only modify one aggregate at a time? Are all necessary inputs for a complete aggregate operation provided in a single mutation? Are business rules for the aggregate enforced within the mutation?	type Mutation { # Aggregate creation createOrder(input: CreateOrderInput!): CreateOrderPayload! # Aggregate modification updateOrder(input: UpdateOrderInput!): UpdateOrderPayload! addLineItem(input: AddLineItemInput!): AddLineItemPayload! removeLineItem(input: RemoveLineItemInput!): RemoveLineItemPayload! # Aggregate state transitions confirmOrder(orderId: ID!): ConfirmOrderPayload! cancelOrder(input: CancelOrderInput!): CancelOrderPayload! } input CreateOrderInput { customerId: ID! lineItems: [LineItemInput!]! shippingAddress: AddressInput! billingAddress: AddressInput! } input LineItemInput { productSku: String! quantity: Int! } type CreateOrderPayload { order: Order errors: [Error!]! }
Entity Inheritance and Polymorphism	Model entity hierarchies using GraphQL interfaces and unions	Interface defines common entity contract Concrete types implement interface completely Type-specific fields clearly separated Federation keys consistent across types Polymorphic queries supported	Are there shared behaviors or attributes across different entity types? Do client applications need to query or operate on these entities polymorphically? Is the hierarchy stable and unlikely to change frequently?	# Base entity interface interface Product @key(fields: "id") { id: ID! sku: String! name: String! description: String! price: Money! } # Concrete entity types type PhysicalProduct implements Product @key(fields: "id") { id: ID! sku: String! name: String! description: String! price: Money! # Physical product specific fields weight: Weight! dimensions: Dimensions! shippingClass: ShippingClass! } type DigitalProduct implements Product @key(fields: "id") { id: ID! sku: String! name: String! description: String! price: Money! # Digital product specific fields downloadUrl: String! licenseType: LicenseType! fileSize: Int! } # Union for polymorphic queries union ProductVariant = PhysicalProduct | DigitalProduct
Entity Versioning Patterns	Handle entity evolution over time	Version fields for optimistic locking Deprecated fields properly marked Migration path documented Schema version tracking Backward compatibility maintained	Do you need to prevent concurrent updates to the same entity? Do you need to track changes to an entity's structure or data over time? Is backward compatibility a significant concern for your clients?	type Customer @key(fields: "id") { id: ID! version: Int! # Optimistic locking # Core fields customerNumber: String! profile: CustomerProfile! # Versioned fields with deprecation email: String! @deprecated(reason: "Use profile.contactInfo.email") phone: String @deprecated(reason: "Use profile.contactInfo.phone") # Evolution tracking createdAt: DateTime! updatedAt: DateTime! schemaVersion: String! # Track schema evolution } type CustomerProfile { personalInfo: PersonalInfo! contactInfo: ContactInfo! preferences: CustomerPreferences! }
Soft Delete Patterns	Handle entity deletion without data loss	Soft delete flags included Deletion metadata captured Queries filter deleted entities by default Conditional field resolution based on deletion status Data retention policies considered	Is there a business requirement to retain deleted data for auditing or recovery? Do you need to differentiate between truly deleted entities and logically deleted ones? How should queries behave when encountering soft-deleted entities?	type Customer @key(fields: "id") { id: ID! customerNumber: String! # Soft delete fields isActive: Boolean! deletedAt: DateTime deletionReason: String # Conditional fields based on deletion status profile: CustomerProfile # Null when deleted orders: [Order!]! # Empty when deleted } type Query { # Active customers only by default customers(includeDeleted: Boolean = false): [Customer!]! customer(id: ID!, includeDeleted: Boolean = false): Customer }
Nested Aggregates (Anti-Pattern)	Avoid aggregates within aggregates	No aggregates nested within other aggregates Cross-aggregate references use IDs Federation used for cross-aggregate navigation Aggregate boundaries clearly defined Consistency boundaries respected	Does one aggregate truly "own" another, or does it merely reference it? Would modifying the "inner" aggregate require modifying the "outer" aggregate's invariants? Are the consistency requirements distinct for each potential aggregate?	# ❌ Bad - Nested aggregates type Order @key(fields: "id") { id: ID! customer: Customer! # Customer is separate aggregate lineItems: [LineItem!]! } # ✅ Good - Reference to separate aggregate type Order @key(fields: "id") { id: ID! customerId: ID! # Reference only customer: Customer! # Federated reference lineItems: [LineItem!]! }
Aggregate Collaboration Patterns	Model how aggregates work together	Aggregates remain independent Collaboration through events or services Eventual consistency between aggregates Compensation patterns for failures Clear responsibility boundaries	How do independent aggregates interact without violating their boundaries? What mechanisms (e.g., domain events) facilitate communication and data synchronization? How are eventual consistency and potential failures handled?	# Order aggregate type Order @key(fields: "id") { id: ID! customerId: ID! status: OrderStatus! } # Inventory aggregate type InventoryItem @key(fields: "productSku") { productSku: String! quantityAvailable: Int! quantityReserved: Int! } # Collaboration through domain events type Mutation { placeOrder(input: PlaceOrderInput!): PlaceOrderPayload! # This triggers InventoryReserved event } type Subscription { inventoryEvents: InventoryEvent! } union InventoryEvent = InventoryReserved | InventoryReleased
Aggregate Factories	Encapsulate complex aggregate creation logic	Complex creation logic encapsulated Factory methods have clear purpose Input validation comprehensive Business rules enforced during creation Error handling for creation failures	Is the creation process for an aggregate complex, involving multiple steps or external dependencies? Do you need to ensure that an aggregate is always created in a valid state? Can the creation logic be reused across different parts of the application?	type Mutation { # Factory method for complex order creation createOrderFromCart(input: CreateOrderFromCartInput!): CreateOrderPayload! # Factory method for subscription orders createSubscriptionOrder(input: CreateSubscriptionInput!): CreateOrderPayload! } input CreateOrderFromCartInput { cartId: ID! shippingAddressId: ID! paymentMethodId: ID! promotionCodes: [String!] } type CreateOrderPayload { order: Order warnings: [Warning!]! errors: [Error!]! }
Entity Distribution Strategies	Distribute entity data across appropriate subgraphs	Entity data distributed by business capability Core entity in primary subgraph Extensions in relevant subgraphs No data duplication across subgraphs Clear ownership boundaries	Which business domain is primarily responsible for managing a given entity? How can different subgraphs extend an entity without duplicating core data? How do you ensure a single source of truth for critical entity data?	# Customer subgraph - Core customer data type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! registrationDate: DateTime! } # Order subgraph - Order-related customer data extend type Customer @key(fields: "id") { id: ID! @external orders: [Order!]! orderHistory: OrderHistory! loyaltyPoints: Int! } # Marketing subgraph - Marketing-related customer data extend type Customer @key(fields: "id") { id: ID! @external marketingPreferences: MarketingPreferences! campaignHistory: [Campaign!]! segmentMemberships: [Segment!]! }
Cross-Subgraph Entity Consistency	Maintain consistency across distributed entity data	Consistency strategy defined Event-driven updates implemented Version tracking for consistency checks Conflict resolution strategies Monitoring for consistency issues	What level of consistency (e.g., strong, eventual) is required between subgraphs? How are changes to an entity propagated across subgraphs? How are conflicts resolved when multiple subgraphs modify the same entity's state?	# Event-driven consistency type Subscription { customerEvents: CustomerEvent! } union CustomerEvent = CustomerUpdated | CustomerDeleted type CustomerUpdated implements DomainEvent { eventId: ID! customerId: ID! updatedFields: [String!]! occurredAt: DateTime! } # Eventual consistency handling type Customer @key(fields: "id") { id: ID! # Include version for consistency checks version: Int! lastSyncedAt: DateTime! }

Value Object

DDD Concept	Definition	Characteristics	Considerations	Example
Value Object Representation	Immutable objects that describe characteristics or attributes but have no conceptual identity	Immutability: Cannot be modified after creation; operations return new instance Value Equality: Equal if all their attributes are equal Self-Validation: Validate their own invariants	No mutation operations on value object fields All fields are non-nullable where appropriate Equality based on all attributes, with comparison operations available Validation rules embedded in type design; invalid instances cannot be created	# Immutable value object type Money { amount: Decimal! # Cannot be changed currency: Currency! # Cannot be changed } # Value Equality - Two Money objects are equal if amount and currency match type Money { amount: Decimal! currency: Currency! isZero: Boolean! } # Self-Validation - Email value object with validation type Email { address: String! # Always valid email format domain: String! isValid: Boolean! # Always true for existing instances }
Money Pattern	Represent monetary values with currency information	Includes amount and currency Can have computed properties like formattedAmount, displayValue, minorUnits Supports arithmetic operations (add, subtract, multiply)	Currency always specified Decimal precision appropriate for currency Arithmetic operations handle currency compatibility Display formatting included	type Money { amount: Decimal! currency: Currency! formattedAmount: String! displayValue: String! } enum Currency { USD EUR }
Address Pattern	Represent physical or mailing addresses	Includes street, city, state, postalCode, country Can have computed properties like formattedAddress, isValid, coordinates Supports validation services	Country-specific validation rules Standardized formatting Geocoding integration considered International address support	type Address { street: String! city: String! state: String postalCode: String! country: Country! formattedAddress: String! isValid: Boolean! }
Date Range Pattern	Represent periods or ranges of time	Includes startDate and endDate Can have computed properties like duration, isActive, isEmpty Supports business logic like contains and overlaps	Start date before or equal to end date Timezone considerations handled Overlap detection implemented Duration calculations accurate	type DateRange { startDate: Date! endDate: Date! duration: Duration! isActive: Boolean! } type Duration { days: Int! hours: Int! }
Measurement Pattern	Represent quantities with units	Includes value and unit Supports unit conversions (e.g., inGrams, inKilograms) Can be composed for complex measurements (e.g., Dimensions)	Unit conversions available Precision appropriate for use case Standard units supported Arithmetic operations handle unit compatibility	type Weight { value: Decimal! unit: WeightUnit! inGrams: Decimal! inKilograms: Decimal! } enum WeightUnit { GRAM KILOGRAM }
Composite Value Objects	Value objects composed of other value objects	Combines multiple value objects (e.g., ContactInfo combines Email, PhoneNumber, Address) Computed properties can leverage components	Component value objects properly modeled Composition relationships clear Validation cascades to components Immutability maintained throughout composition	type ContactInfo { email: Email! phone: PhoneNumber address: Address! isComplete: Boolean! }
Polymorphic Value Objects	Different value object types for similar concepts	Uses interfaces to define common contracts (e.g., Identifier) Specific types implement the interface and add relevant behavior (e.g., CustomerNumber, ProductSKU) Unions can be used for polymorphic usage	Interface defines common contract Specific types add relevant behavior Type discrimination clear Validation rules type-specific	interface Identifier { value: String! type: IdentifierType! isValid: Boolean! } type CustomerNumber implements Identifier { value: String! region: String! }
Enumeration Value Objects	Rich enumerations with behavior and data	Enum provides type safety for a core concept (e.g., OrderStatusCode) Associated rich type adds behavior and metadata (e.g., OrderStatus with canTransitionTo, isTerminal)	Enum provides type safety Rich type adds behavior and metadata State transitions clearly defined Business rules embedded	type OrderStatus { code: OrderStatusCode! name: String! canTransitionTo: [OrderStatusCode!]! isTerminal: Boolean! } enum OrderStatusCode { DRAFT CONFIRMED }
Collection Value Objects	Immutable collections with domain behavior	Encapsulates a collection of other objects (e.g., LineItems containing LineItem) Provides collection-level behavior (e.g., totalQuantity, totalAmount, hasProduct)	Collection operations available Aggregation functions provided Business logic encapsulated Immutability maintained	type LineItems { items: [LineItem!]! totalQuantity: Int! totalAmount: Money! itemCount: Int! }
Format Validation	Validate value object format and structure	Embedded validation rules to ensure correct format (e.g., email address format) Can include validation metadata (e.g., validationRules, isDisposable)	Format validation rules defined Standard formats used where applicable Validation metadata exposed International standards followed	type Email { address: String! # Always valid format localPart: String! domain: String! validationRules: [ValidationRule!]! }
Business Rule Validation	Embed business rules in value object validation	Validation ensures adherence to domain constraints (e.g., ProductSKU has isDiscontinued, isRestricted) Includes business metadata (e.g., category, manufacturer, riskLevel)	Business rules embedded in validation Domain constraints enforced Business metadata included Compliance requirements met	type ProductSKU { value: String! isValid: Boolean! category: ProductCategory! isDiscontinued: Boolean! }
Scalar Serialization	Serialize simple value objects as scalars	Defines custom GraphQL scalars for simple value objects (e.g., Money, Email, PhoneNumber) Validation happens during deserialization	Scalar serialization format documented Validation happens during deserialization Error handling for invalid formats Client libraries support custom scalars	scalar Money scalar Email type Customer { id: ID! email: Email! # Serialized as string, validated as email creditLimit: Money! # Serialized with currency info }
Object Serialization	Serialize complex value objects as objects	Represents value objects as GraphQL types with their fields (e.g., Address, Money) Input types mirror output types for consistency	Input types mirror output types Nested objects properly structured Optional fields clearly marked Validation rules consistent	type Address { street: String! city: String! postalCode: String! country: Country! } input AddressInput { street: String! city: String! }
Shared Value Objects	Share common value objects across subgraphs in a federated architecture	Common value objects like Money, Email, Address are defined once Used consistently across different subgraphs (e.g., Customer subgraph and Order subgraph)	Shared value objects consistently defined No conflicting definitions across subgraphs Shared types documented Version compatibility maintained	scalar Money type Address { street: String! city: String! postalCode: String! } # Customer subgraph type Customer @key(fields: "id") { id: ID! address: Address! }
Context-Specific Value Objects	Allow context-specific interpretations of value objects in a federated architecture	Value objects can have different fields or behaviors based on the specific domain context (e.g., Address in customer context vs. ShippingAddress in shipping context)	Context-specific needs addressed No unnecessary coupling between contexts Clear mapping between contexts Context boundaries respected	# Customer context - full address type Address { street: String! city: String! state: String! isVerified: Boolean! } # Shipping context - shipping-focused address type ShippingAddress { street: String! city: String! deliveryInstructions: String isResidential: Boolean! }

Domain Event

DDD Concept	Definition	Characteristics	Considerations	Example
Ubiquitous Language	A common language shared between domain experts and developers, reflected in code and schema	Type names must use domain terminology, not technical terms	All type names use business terminology	# ✅ Good - Uses domain language type Order { orderNumber: String! customer: Customer! lineItems: [LineItem!]! totalAmount: Money! status: OrderStatus! } # ❌ Bad - Uses technical language type OrderRecord { id: ID! customerId: ID! items: [OrderItemRecord!]! total: Float! statusCode: Int! }
Business Significance (Domain Event Modeling)	Events represent occurrences that domain experts care about	Events use business language Events represent business state changes Events are meaningful to domain experts Events capture business context Events avoid technical implementation details	Ensure events directly reflect business processes Avoid creating events for mere technical operations	# ✅ Good - Business significant events type CustomerRegistered implements DomainEvent { eventId: ID! aggregateId: ID! occurredAt: DateTime! version: Int! # Business-relevant data customerId: ID! customerNumber: String! email: String! registrationChannel: RegistrationChannel! } type OrderPlaced implements DomainEvent { eventId: ID! aggregateId: ID! occurredAt: DateTime! version: Int! # Business context orderNumber: String! customerId: ID! totalAmount: Money! orderSource: OrderSource! } # ❌ Bad - Technical events type DatabaseRecordUpdated implements DomainEvent { eventId: ID! tableName: String! recordId: String! changedFields: [String!]! }
Immutability (Domain Event Modeling)	Events cannot be changed once created	No mutation operations on events Event data is immutable Event history preserved Append-only event store Compensation events for corrections	Design systems to append events, not alter them Use compensation events for error correction instead of modifying past events	interface DomainEvent { eventId: ID! # Immutable identifier aggregateId: ID! # Source aggregate occurredAt: DateTime! # When it happened version: Int! # Event version for evolution eventType: String! # Event type identifier } # Events are append-only type Mutation { # Events are published, not updated publishEvent(event: DomainEventInput!): PublishEventResult! # No update or delete operations for events # updateEvent - NOT ALLOWED # deleteEvent - NOT ALLOWED }
Past Tense Naming (Domain Event Modeling)	Events describe what has already happened	Event names use past tense Event names describe completed actions Event names are specific and clear Event names follow domain language Event names avoid ambiguity	Use clear, unambiguous past tense verbs for event names Ensure names reflect completed actions, not ongoing processes or commands	# ✅ Good - Past tense names type CustomerRegistered implements DomainEvent type OrderPlaced implements DomainEvent type PaymentProcessed implements DomainEvent type InventoryAdjusted implements DomainEvent type ProductDiscontinued implements DomainEvent # ❌ Bad - Present/future tense type CustomerRegistration implements DomainEvent type PlaceOrder implements DomainEvent type ProcessPayment implements DomainEvent
Base Event Interface (Event Structure Patterns)	Define common structure for all domain events	Common event metadata defined Event identity fields included Temporal information captured Causation chain trackable Source attribution clear	Establish a consistent base interface for all events Include essential metadata for traceability and debugging	interface DomainEvent { # Event identity eventId: ID! eventType: String! # Source information aggregateId: ID! aggregateType: String! aggregateVersion: Int! # Temporal information occurredAt: DateTime! # Event evolution eventVersion: Int! # Causation tracking causationId: ID # ID of command that caused this event correlationId: ID # ID linking related events # Metadata userId: ID # Who triggered the event source: EventSource! # Where the event originated } enum EventSource { USER_ACTION SYSTEM_PROCESS EXTERNAL_INTEGRATION SCHEDULED_TASK COMPENSATION }
Event Payload Patterns (Event Structure Patterns)	Structure event data for different use cases	Event payload size appropriate Critical data included in payload Snapshots used for mutable data References used for stable data Payload evolution considered	Decide whether to include full data or references based on consumer needs and data volatility Use snapshots for mutable data at the time of the event	# Minimal event - just the fact type CustomerRegistered implements DomainEvent { # Base event fields eventId: ID! aggregateId: ID! occurredAt: DateTime! # Minimal payload customerId: ID! email: String! } # Rich event - includes relevant context type OrderPlaced implements DomainEvent { # Base event fields eventId: ID! aggregateId: ID! occurredAt: DateTime! # Rich payload orderNumber: String! customerId: ID! lineItems: [OrderLineItemSnapshot!]! shippingAddress: AddressSnapshot! totalAmount: Money! paymentMethod: PaymentMethodSnapshot! orderSource: OrderSource! } # Snapshot types for event data type OrderLineItemSnapshot { productSku: String! productName: String! quantity: Int! unitPrice: Money! }
Event Versioning (Event Structure Patterns)	Handle event schema evolution over time	Event versioning strategy defined Backward compatibility maintained Version migration paths clear Legacy version support planned Schema evolution documented	Plan for how event schemas will evolve without breaking existing consumers Use version numbers and potentially unions for backward compatibility	# Version 1 of event type CustomerRegisteredV1 implements DomainEvent { eventId: ID! eventVersion: Int! # Always 1 customerId: ID! email: String! } # Version 2 adds more fields type CustomerRegisteredV2 implements DomainEvent { eventId: ID! eventVersion: Int! # Always 2 customerId: ID! email: String! # New fields in v2 customerNumber: String! registrationChannel: RegistrationChannel! } # Union for handling multiple versions union CustomerRegisteredEvent = CustomerRegisteredV1 | CustomerRegisteredV2 # Current version alias type CustomerRegistered implements DomainEvent { eventId: ID! eventVersion: Int! customerId: ID! email: String! customerNumber: String! registrationChannel: RegistrationChannel! }
Event Streams (Event Aggregation Patterns)	Group related events into streams	Event streams logically grouped Stream filtering available Stream ordering preserved Stream pagination supported Stream subscription management	Define clear logical groupings for events (e.g., by aggregate) Provide mechanisms for filtering, ordering, and subscribing to event streams	type Subscription { # Stream all events for an aggregate customerEvents(customerId: ID!): CustomerEvent! # Stream events by type orderEvents(filter: OrderEventFilter): OrderEvent! # Stream events by time range domainEvents( from: DateTime! to: DateTime eventTypes: [String!] ): DomainEvent! } union CustomerEvent = CustomerRegistered | CustomerUpdated | CustomerDeactivated union OrderEvent = OrderPlaced | OrderConfirmed | OrderShipped | OrderDelivered | OrderCancelled input OrderEventFilter { customerId: ID orderStatus: [OrderStatus!] dateRange: DateRangeInput }
Event Projections (Event Aggregation Patterns)	Create read models from event streams	Projections built from events Projection state clearly defined Projection versioning handled Projection rebuilding supported Projection consistency monitored	Design projections to be eventually consistent, tailored for specific query needs Ensure projections can be rebuilt from the event stream	# Event-sourced aggregate state type CustomerProjection { customerId: ID! currentState: CustomerState! version: Int! lastUpdated: DateTime! # Projected from events registrationDate: DateTime! totalOrders: Int! totalSpent: Money! loyaltyLevel: LoyaltyLevel! # Event history eventHistory: [CustomerEvent!]! } type CustomerState { customerNumber: String! profile: CustomerProfile! isActive: Boolean! preferences: CustomerPreferences! } # Query projections type Query { customerProjection(customerId: ID!): CustomerProjection customerProjections( filter: CustomerProjectionFilter orderBy: CustomerProjectionSort ): [CustomerProjection!]! } input CustomerProjectionFilter { isActive: Boolean loyaltyLevel: [LoyaltyLevel!] registeredAfter: DateTime totalSpentRange: MoneyRangeInput }
Event Sagas (Event Aggregation Patterns)	Coordinate long-running business processes	Saga state explicitly modeled Saga steps clearly defined Compensation actions tracked Saga timeout handling Saga failure recovery	Model the state of the saga explicitly to track progress and handle failures Define clear compensation actions for when a saga fails	# Saga state tracking type OrderFulfillmentSaga { sagaId: ID! orderId: ID! currentStep: SagaStep! status: SagaStatus! startedAt: DateTime! completedAt: DateTime # Saga state inventoryReserved: Boolean! paymentProcessed: Boolean! shippingArranged: Boolean! # Compensation tracking compensationActions: [CompensationAction!]! } enum SagaStep { RESERVE_INVENTORY PROCESS_PAYMENT ARRANGE_SHIPPING COMPLETE_ORDER } enum SagaStatus { RUNNING COMPLETED FAILED COMPENSATING COMPENSATED } type CompensationAction { actionType: String! executedAt: DateTime! reason: String! } # Saga coordination type Mutation { startOrderFulfillmentSaga(orderId: ID!): StartSagaResult! compensateOrderFulfillment(sagaId: ID!, reason: String!): CompensationResult! }
Event Publishing (Cross-Context Event Patterns)	Publish events for consumption by other contexts	Event publishing mechanism defined Event routing configured Target contexts identified Publishing reliability ensured Event ordering preserved	Define clear contracts for published events Ensure reliable delivery and proper routing to interested consumers	# Publishing context type Mutation { placeOrder(input: PlaceOrderInput!): PlaceOrderPayload! # Publishes OrderPlaced event } type Subscription { # Publish events to subscribers orderEvents: OrderEvent! inventoryEvents: InventoryEvent! paymentEvents: PaymentEvent! } # Event metadata for routing type OrderPlaced implements DomainEvent { eventId: ID! aggregateId: ID! # Routing information publishedTo: [String!]! # Target contexts routingKey: String! # Message routing # Business data orderNumber: String! customerId: ID! totalAmount: Money! }
Event Consumption (Cross-Context Event Patterns)	Consume events from other contexts	Event subscription configured Event handlers implemented Error handling defined Retry logic implemented Dead letter handling	Implement robust error handling and retry mechanisms for event consumption Consider dead-letter queues for events that cannot be processed	# Consuming context type Subscription { # Subscribe to external events externalOrderEvents: OrderEvent! externalCustomerEvents: CustomerEvent! } # Event handlers type Mutation { handleOrderPlaced(event: OrderPlacedInput!): HandleEventResult! handleCustomerRegistered(event: CustomerRegisteredInput!): HandleEventResult! } type HandleEventResult { success: Boolean! eventId: ID! processedAt: DateTime! errors: [EventProcessingError!]! } type EventProcessingError { code: String! message: String! retryable: Boolean! }
Event Translation (Cross-Context Event Patterns)	Translate events between context boundaries	Event translation rules defined Data mapping documented Translation errors handled Schema compatibility maintained Translation testing comprehensive	Define clear translation rules and handle potential data mismatches Ensure robust error handling for translation failures	# External event format type ExternalOrderPlaced { id: String! customer_id: String! order_total: Float! currency: String! timestamp: String! } # Internal event format type OrderPlaced implements DomainEvent { eventId: ID! aggregateId: ID! occurredAt: DateTime! # Translated data orderNumber: String! customerId: ID! totalAmount: Money! } # Translation service type Mutation { translateExternalEvent(externalEvent: ExternalEventInput!): TranslationResult! } type TranslationResult { internalEvent: DomainEvent translationErrors: [TranslationError!]! }
Event Store Design (Event Sourcing Patterns)	Store events as the source of truth	Event storage mechanism defined Event retrieval patterns supported Concurrency conflicts handled Event ordering guaranteed Storage scalability considered	Choose an event store that supports immutable appends and efficient retrieval Address concurrency and ensure strict event ordering	type EventStore { # Event storage appendEvent(event: DomainEventInput!): AppendResult! # Event retrieval getEvents(aggregateId: ID!, fromVersion: Int, toVersion: Int): [DomainEvent!]! getEventsByType( eventType: String! from: DateTime to: DateTime ): [DomainEvent!]! } type AppendResult { success: Boolean! eventId: ID! version: Int! errors: [EventStoreError!]! } type EventStoreError { code: EventStoreErrorCode! message: String! } enum EventStoreErrorCode { CONCURRENCY_CONFLICT INVALID_EVENT STORAGE_ERROR SERIALIZATION_ERROR }
Snapshot Patterns (Event Sourcing Patterns)	Optimize event replay with snapshots	Snapshot strategy defined Snapshot frequency optimized Snapshot consistency ensured Snapshot storage managed Rebuild performance monitored	Determine optimal snapshot frequency to balance storage vs. replay performance Ensure snapshots are consistent with the event stream	type AggregateSnapshot { aggregateId: ID! aggregateType: String! version: Int! snapshotData: JSON! createdAt: DateTime! } type Query { # Get latest snapshot getSnapshot(aggregateId: ID!): AggregateSnapshot # Rebuild from events rebuildAggregate( aggregateId: ID! fromSnapshot: Boolean = true ): AggregateRebuildResult! } type AggregateRebuildResult { aggregateId: ID! finalVersion: Int! eventsProcessed: Int! snapshotUsed: Boolean! rebuildTime: Duration! }
Event Metrics (Event Monitoring and Observability)	Monitor event processing and performance	Event volume monitoring Performance metrics tracked Error rates monitored Business metrics included Alerting thresholds defined	Define key metrics for event volume, performance, and errors Set up alerting for critical thresholds	type EventMetrics { # Volume metrics eventsPublished: Int! eventsConsumed: Int! eventsPerSecond: Float! # Performance metrics averageProcessingTime: Duration! processingLatency: Duration! # Error metrics processingErrors: Int! errorRate: Float! deadLetterCount: Int! # Business metrics eventsByType: [EventTypeMetric!]! eventsBySource: [EventSourceMetric!]! } type EventTypeMetric { eventType: String! count: Int! averageSize: Int! errorRate: Float! } type Query { eventMetrics( timeRange: DateRangeInput! aggregateBy: MetricAggregation! ): EventMetrics! }
Event Tracing (Event Monitoring and Observability)	Trace event flows across contexts	Event tracing implemented Correlation IDs tracked Cross-context flows visible Performance bottlenecks identified Trace data retention managed	Implement correlation IDs to trace events across multiple services Visualize event flows to identify bottlenecks and issues	type EventTrace { traceId: ID! correlationId: ID! events: [TracedEvent!]! totalDuration: Duration! contextTransitions: Int! } type TracedEvent { eventId: ID! eventType: String! context: String! timestamp: DateTime! processingDuration: Duration! causedBy: ID # Previous event in chain causedEvents: [ID!]! # Subsequent events } type Query { traceEvents(correlationId: ID!, traceId: ID): EventTrace! findEventTraces( aggregateId: ID eventType: String timeRange: DateRangeInput! ): [EventTrace!]! }

Schema

Subgraph Relationships

DDD Concept	Definition	Characteristics	Considerations	Example
Cross-Subgraph Relationships	Fundamental to GraphQL federation, enabling distributed domain models while maintaining bounded context integrity	Patterns for modeling relationships that span multiple subgraphs in DDD-compliant ways	Ensuring bounded context integrity, effective communication between subgraphs	See individual relationship patterns for examples.
Reference Relationships	One entity references another entity by stable identifier	References use stable, immutable identifiers Referenced entities are owned by appropriate contexts	Is the referenced entity owned by another bounded context? Is the relationship stable over time? Do you need immediate access to referenced entity data? Reference integrity is handled at application level Broken references are handled gracefully Reference relationships are documented	# Order subgraph - owns Order entity type Order @key(fields: "id") { id: ID! orderNumber: String! customerId: ID! # Reference to Customer entity productIds: [ID!]! # References to Product entities status: OrderStatus! totalAmount: Money! } # Customer subgraph - owns Customer entity type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! } # Product subgraph - owns Product entity type Product @key(fields: "sku") { sku: String! name: String! price: Money! }
Federated Navigation Relationships	Enable rich navigation across subgraph boundaries using federation	Federation keys are properly defined External fields are marked correctly	Navigation relationships are bidirectional where needed Performance implications are considered Error handling for unavailable services	# Order subgraph type Order @key(fields: "id") { id: ID! orderNumber: String! customerId: ID! # Federated navigation to Customer customer: Customer! # Federated navigation to Products lineItems: [LineItem!]! } type LineItem { productSku: String! quantity: Int! unitPrice: Money! # Federated navigation to Product product: Product! } # Customer subgraph type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! } # Extend Customer with order-related data extend type Customer @key(fields: "id") { id: ID! @external # Back-navigation to orders orders: [Order!]! recentOrders: [Order!]! orderHistory: OrderHistory! } # Product subgraph type Product @key(fields: "sku") { sku: String! name: String! description: String! price: Money! }
Aggregated Relationships	Provide aggregated views of cross-subgraph data	Aggregations are computed in owning context Aggregation data is kept up-to-date	Performance of aggregation queries is acceptable Aggregation consistency is managed Aggregation evolution is planned	# Customer subgraph type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! } # Order subgraph extends Customer with order aggregations extend type Customer @key(fields: "id") { id: ID! @external # Aggregated order data orderStatistics: OrderStatistics! loyaltyMetrics: LoyaltyMetrics! } type OrderStatistics { totalOrders: Int! totalSpent: Money! averageOrderValue: Money! lastOrderDate: DateTime! # Time-based aggregations ordersThisYear: Int! spentThisYear: Money! ordersThisMonth: Int! spentThisMonth: Money! } type LoyaltyMetrics { loyaltyPoints: Int! loyaltyLevel: LoyaltyLevel! nextLevelRequirement: Int! lifetimeValue: Money! } # Product subgraph extends Customer with product preferences extend type Customer @key(fields: "id") { id: ID! @external # Product-related aggregations favoriteCategories: [ProductCategory!]! recommendedProducts: [Product!]! purchaseHistory: ProductPurchaseHistory! }
Event-Driven Relationships	Maintain relationship consistency through domain events	Events represent meaningful business occurrences Event schemas are stable and versioned	Event processing is idempotent Event ordering is handled correctly Event failure recovery is implemented	# Customer subgraph publishes events type Subscription { customerEvents: CustomerEvent! } union CustomerEvent = CustomerRegistered | CustomerUpdated | CustomerDeactivated type CustomerRegistered implements DomainEvent { eventId: ID! customerId: ID! customerNumber: String! email: String! registrationDate: DateTime! } # Order subgraph consumes customer events type Mutation { # Event handlers (internal) handleCustomerRegistered(event: CustomerRegisteredInput!): HandleEventResult! handleCustomerUpdated(event: CustomerUpdatedInput!): HandleEventResult! } # Order subgraph maintains customer snapshot type CustomerSnapshot { customerId: ID! customerNumber: String! email: String! isActive: Boolean! lastSyncedAt: DateTime! } type Order @key(fields: "id") { id: ID! customerId: ID! # Reference to local customer snapshot customerSnapshot: CustomerSnapshot! # Federated reference to live customer data customer: Customer! }
Conditional Relationships	Relationships that exist only under certain conditions	Conditions are clearly documented Conditional logic is consistent	Error handling for invalid conditions Performance impact of conditions considered Conditions are testable	type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! status: CustomerStatus! } # Order subgraph extend type Customer @key(fields: "id") { id: ID! @external status: CustomerStatus! @external # Conditional relationships based on status activeOrders: [Order!]! # Only for active customers orderHistory: OrderHistory # Only for customers with orders loyaltyProgram: LoyaltyProgram # Only for eligible customers } type Query { # Conditional queries customerOrders(customerId: ID!, includeInactive: Boolean = false): [Order!]! } # Resolver logic handles conditions
Temporal Relationships	Relationships that change over time	Temporal boundaries are clearly defined Historical data is preserved	Time-based queries are efficient Temporal consistency is maintained Timezone handling is correct	type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! } # Subscription subgraph extend type Customer @key(fields: "id") { id: ID! @external # Current subscription currentSubscription: Subscription # Historical subscriptions subscriptionHistory: [Subscription!]! # Time-based queries subscriptionAt(date: DateTime!): Subscription subscriptionsDuring(period: DateRange!): [Subscription!]! } type Subscription @key(fields: "id") { id: ID! customerId: ID! plan: SubscriptionPlan! # Temporal information startDate: DateTime! endDate: DateTime status: SubscriptionStatus! # Temporal relationships previousSubscription: Subscription nextSubscription: Subscription }
Hierarchical Relationships	Parent-child relationships across subgraphs	Hierarchy levels are clearly defined Parent-child relationships are consistent	Circular references are prevented Hierarchy navigation is efficient Hierarchy changes are handled correctly	# Organization subgraph type Organization @key(fields: "id") { id: ID! name: String! type: OrganizationType! } # Customer subgraph type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! organizationId: ID # Reference to organization } # Extend Organization with customer relationships extend type Organization @key(fields: "id") { id: ID! @external # Hierarchical customer relationships customers: [Customer!]! primaryContact: Customer billingContact: Customer # Aggregated customer data customerCount: Int! totalCustomerValue: Money! } # Extend Customer with organization context extend type Customer @key(fields: "id") { id: ID! @external # Parent organization organization: Organization # Role within organization organizationRole: OrganizationRole permissions: [Permission!]! }
Data Locality Optimization	Optimize data placement for common query patterns	Frequently accessed data is co-located Data duplication is minimized	Data consistency is maintained Update mechanisms are in place Performance gains are measured	# Order subgraph includes frequently accessed customer data type Order @key(fields: "id") { id: ID! orderNumber: String! customerId: ID! # Local customer data for performance customerSnapshot: CustomerSnapshot! # Full customer data via federation customer: Customer! @provides(fields: "customerNumber email") } type CustomerSnapshot { customerNumber: String! email: String! name: String! loyaltyLevel: LoyaltyLevel! # Snapshot of frequently needed customer data }
Batch Loading Patterns	Optimize cross-subgraph data loading	Batch loading is implemented for N+1 problems Batch sizes are optimized	Caching is implemented where appropriate Error handling for batch failures Performance monitoring is in place	# Product subgraph type Product @key(fields: "sku") { sku: String! name: String! price: Money! } # Order subgraph with batch loading type Order @key(fields: "id") { id: ID! lineItems: [LineItem!]! } type LineItem { productSku: String! quantity: Int! # Batch loaded product data product: Product! } # Resolver implements DataLoader pattern for batch loading
Caching Strategies	Cache cross-subgraph relationship data	Cache invalidation strategy is defined Cache TTL is appropriate	Cache consistency is maintained Cache performance is monitored Cache failures are handled gracefully	type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! # Cached relationship data recentOrders: [Order!]! # Cached for performance orderSummary: OrderSummary! # Pre-computed and cached } type OrderSummary { totalOrders: Int! totalSpent: Money! lastOrderDate: DateTime! # Cache metadata lastUpdated: DateTime! cacheExpiry: DateTime! }
Graceful Degradation	Handle subgraph unavailability gracefully	Fallback data is available Service unavailability is handled	Error messages are informative Partial data is clearly indicated Recovery mechanisms are in place	type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! } extend type Customer @key(fields: "id") { id: ID! @external # May return null if order service unavailable orders: [Order!] # Cached/snapshot data always available orderSummary: OrderSummary! } type OrderSummary { totalOrders: Int! lastOrderDate: DateTime! isLive: Boolean! # Indicates if data is current lastUpdated: DateTime! }
Circuit Breaker Pattern	Prevent cascade failures in cross-subgraph calls	Circuit breaker thresholds are configured Service health is monitored	Fallback behavior is defined Recovery testing is performed Alerts are configured for service issues	type Customer @key(fields: "id") { id: ID! profile: CustomerProfile! } extend type Customer @key(fields: "id") { id: ID! @external # Protected by circuit breaker orders: [Order!] # Service health indicator orderServiceStatus: ServiceStatus! } enum ServiceStatus { AVAILABLE DEGRADED UNAVAILABLE }

Naming Conventions

DDD Concept	Definition	Characteristics	Considerations	Example
Ubiquitous Language	A common language shared between domain experts and developers, reflected in code and schema	Type names must use domain terminology, not technical terms Names match domain expert vocabulary No technical abbreviations in public schema Consistent terminology across all types Names are meaningful to business users Domain concepts clearly expressed	All type names use business terminology Ensures clarity and maintainability Reduces miscommunication between teams Supports long-term schema evolution	# ✅ Good - Uses business language type Customer { customerNumber: String! loyaltyLevel: LoyaltyLevel! creditLimit: Money! } type Order { orderNumber: String! fulfillmentStatus: FulfillmentStatus! shippingMethod: ShippingMethod! } # ❌ Bad - Uses technical language type CustomerRecord { custId: String! lvl: Int! creditAmt: Float! }
Clarity and Readability	Names should be self-documenting and unambiguous	Names are descriptive and specific No ambiguous abbreviations Boolean fields clearly indicate true/false meaning (e.g., isAvailableForPurchase) Collection fields indicate plurality (e.g., lineItems) Purpose is clear from name alone	Improves understanding for all schema users Reduces the need for external documentation Facilitates easier debugging and maintenance	# ✅ Good - Clear and specific type ProductCatalogEntry { productSku: String! displayName: String! shortDescription: String! detailedDescription: String! isAvailableForPurchase: Boolean! } # ❌ Bad - Ambiguous and unclear type Product { id: String! name: String! desc: String! info: String! flag: Boolean! }
Consistency	Apply naming patterns consistently across the entire schema	ID fields follow consistent pattern (e.g., customerId, orderId) Date fields use consistent suffixes (e.g., registrationDate, lastLoginDate) Similar concepts use similar naming Patterns applied across all types Exceptions are documented	Ensures predictability and reduces cognitive load Streamlines development and integration Supports automated tooling and code generation	# ✅ Good - Consistent patterns type Customer { customerId: ID! customerNumber: String! registrationDate: DateTime! lastLoginDate: DateTime! } type Order { orderId: ID! orderNumber: String! placementDate: DateTime! lastModifiedDate: DateTime! } # ❌ Bad - Inconsistent patterns type Customer { id: ID! customerNum: String! registered: DateTime! lastLogin: DateTime! }
Entity Types Naming	Use singular nouns in PascalCase for entity types	Singular noun form PascalCase formatting (e.g., Customer, Product) No prefixes or suffixes unless necessary for compound names Compound names clearly joined (e.g., CustomerProfile) Names reflect domain concepts	Clearly identifies core domain entities Aligns with common GraphQL type naming conventions	# Entity types type Customer @key(fields: "id") { id: ID! customerNumber: String! } type Product @key(fields: "sku") { sku: String! name: String! } # Compound entity names type CustomerProfile { personalInfo: PersonalInfo! contactInfo: ContactInfo! }
Value Object Types Naming	Use descriptive nouns that indicate the value's purpose	Names indicate value purpose (e.g., Money, Address) No "Value" or "Object" suffixes Descriptive and specific Consistent with domain language Clear semantic meaning	Distinguishes value objects from entities Promotes reusability of common data structures	# Value objects type Money { amount: Decimal! currency: Currency! } type Address { street: String! city: String! postalCode: String! country: String! } # Measurement value objects type Weight { value: Decimal! unit: WeightUnit! }
Enum Types Naming	Use singular nouns with descriptive suffixes when needed	Enum type names are singular (e.g., Currency, OrderStatus) Enum values are UPPER_SNAKE_CASE (e.g., USD, PENDING_PAYMENT) Values are descriptive and clear No redundant prefixes in values Logical grouping of related values	Provides clear, self-documenting lists of discrete values Ensures consistent representation of fixed choices	# Simple enums enum Currency { USD EUR GBP } enum OrderStatus { DRAFT PENDING_PAYMENT CONFIRMED } # Enums with descriptive suffixes enum PaymentMethod { CREDIT_CARD DEBIT_CARD }
Interface Types Naming	Use descriptive names that indicate the common contract	Names indicate common behavior or contract (e.g., Identifiable, Purchasable) Use adjective forms when appropriate (e.g., Timestamped) Clear semantic meaning No "Interface" suffix Focused on single responsibility	Defines shared behaviors and structures across types Promotes schema extensibility and polymorphism	# Domain interfaces interface DomainEvent { eventId: ID! aggregateId: ID! occurredAt: DateTime! } interface Identifiable { id: ID! } # Business capability interfaces interface Purchasable { price: Money! isAvailable: Boolean! }
Union Types Naming	Use descriptive names that indicate the union purpose	Names indicate union purpose (e.g., OrderEvent, SearchResult) Clear semantic grouping No "Union" suffix Logical member types Consistent with domain concepts	Allows for returning multiple possible types for a single field Enhances flexibility in representing diverse but related data	# Event unions union OrderEvent = OrderPlaced | OrderShipped | OrderDelivered # Search result unions union SearchResult = Product | Category | Brand # Error unions union ValidationError = FieldError | BusinessRuleError
Scalar Fields Naming	Use camelCase with descriptive names	camelCase formatting (e.g., firstName, totalOrderCount) Descriptive and specific Boolean fields start with "is", "has", "can", etc. (e.g., isActive) Date fields end with "Date" (e.g., registrationDate) Count fields end with "Count" (e.g., totalOrderCount)	Provides clear and consistent field access Aligns with common JavaScript/GraphQL field naming conventions	type Customer { firstName: String! lastName: String! emailAddress: String! isActive: Boolean! registrationDate: DateTime! totalOrderCount: Int! }
Object Fields Naming	Use camelCase names that indicate the relationship	Names indicate relationship type (e.g., profile, billingAddress) Singular for single objects (e.g., customer) Plural for collections (e.g., lineItems) Clear ownership vs. reference Consistent relationship naming	Defines relationships between different types in the schema Enhances graph traversability and data retrieval	type Customer { profile: CustomerProfile! billingAddress: Address! primaryPaymentMethod: PaymentMethod } type Order { lineItems: [LineItem!]! customer: Customer! paymentMethod: PaymentMethod! }
Collection Fields Naming	Use plural nouns that clearly indicate the collection contents	Plural noun forms (e.g., orders, paymentMethods) Clear collection contents Descriptive qualifiers when filtered (e.g., activeOrders, recommendedProducts) Consistent collection naming Appropriate nullability (e.g., [Order!]!)	Represents lists of related items Facilitates querying multiple entities at once	type Customer { orders: [Order!]! paymentMethods: [PaymentMethod!]! activeOrders: [Order!]! } type Product { variants: [ProductVariant!]! categories: [Category!]! images: [ProductImage!]! }
Query Operations Naming	Use descriptive verbs and nouns that indicate the query purpose	Descriptive query names (e.g., customer, searchProducts, calculateShipping) Consistent parameter naming Clear return type indication Logical grouping of related queries Appropriate nullability	Defines entry points for data retrieval Ensures clarity on what data can be fetched	type Query { customer(id: ID!): Customer products(filter: ProductFilter): [Product!]! searchProducts(query: String!): ProductSearchResult! calculateShipping(input: ShippingCalculationInput!): ShippingQuote! }
Mutation Operations Naming	Use imperative verbs that clearly describe the action	Imperative verb forms (e.g., createCustomer, updateOrderStatus, cancelOrder) Clear action description Consistent input/payload pattern (e.g., CreateCustomerInput, CreateCustomerPayload) Business-focused operation names Appropriate error handling	Defines operations that modify data Provides clear intent for state changes	type Mutation { createCustomer(input: CreateCustomerInput!): CreateCustomerPayload! updateOrderStatus(input: UpdateOrderStatusInput!): UpdateOrderStatusPayload! cancelOrder(orderId: ID!, reason: String!): CancelOrderPayload! }
Subscription Operations Naming	Use descriptive names that indicate the event stream	Names indicate event streams (e.g., customerUpdates, orderEvents) Clear subscription purpose Appropriate filtering options Consistent event naming Real-time semantics clear	Enables real-time data updates Supports event-driven architectures	type Subscription { customerUpdates(customerId: ID!): CustomerEvent! orderEvents(filter: OrderEventFilter): OrderEvent! priceUpdates(productSkus: [String!]!): PriceUpdate! }
Input Types Naming	Use descriptive names with "Input" suffix	"Input" suffix for all input types (e.g., CreateCustomerInput, CustomerFilter) Descriptive base names Appropriate field nullability Logical field grouping Consistent with output types	Clearly identifies types used for mutation arguments Promotes reusability of complex input structures	input CreateCustomerInput { firstName: String! lastName: String! emailAddress: String! } input CustomerFilter { isActive: Boolean registeredAfter: DateTime }
Payload Types Naming	Use descriptive names with "Payload" suffix	"Payload" suffix for all payload types (e.g., CreateCustomerPayload, UpdateCustomerPayload) Include primary result object Include error and warning arrays Additional metadata when relevant (e.g., orderNumber, estimatedDelivery) Consistent error handling pattern	Standardizes mutation responses Provides a consistent way to return data, errors, and warnings	type CreateCustomerPayload { customer: Customer errors: [Error!]! warnings: [Warning!]! } type PlaceOrderPayload { order: Order orderNumber: String! confirmationNumber: String! errors: [Error!]! }
Subgraph Naming	Use domain-focused names that reflect bounded contexts	Domain-focused names (e.g., customer-management, order-processing) Kebab-case formatting Clear business capability indication No technical implementation details Consistent with bounded context names	Organizes a federated graph into logical, self-contained services Promotes team autonomy and clear ownership	customer-management product-catalog order-processing inventory-management
Deprecation Naming	Use clear deprecation messages with migration guidance	Clear deprecation reasons provided Migration guidance provided Version information when relevant Alternative field/value indicated Consistent deprecation messaging	Communicates changes to consumers without breaking existing integrations Facilitates a smooth evolution of the schema	type Customer { email: String @deprecated(reason: "Use profile.contactInfo.emailAddress instead") phone: String @deprecated(reason: "Use profile.contactInfo.phoneNumber instead") } enum OrderStatus { PENDING @deprecated(reason: "Use PENDING_PAYMENT instead") PENDING_PAYMENT }
Versioning Conventions	Use semantic versioning concepts in schema evolution	Version information tracked Breaking changes documented Migration paths clear Backward compatibility maintained where possible Evolution strategy defined	Manages schema changes over time Ensures stability for consumers while allowing for new features	type CustomerV2 { id: ID! customerNumber: String! profile: CustomerProfileV2! } type SchemaInfo { version: String! # "2.1.0" deprecatedFields: [DeprecatedField!]! }

Strategies

DDD Concept	Definition	Characteristics	Considerations	Example
Domain-Centric Organization	Organize schema files around domain concepts and aggregates	Files grouped by domain concepts Related types co-located Clear separation of concerns Shared types properly organized	Schema composition is clear	customer-subgraph/ ├── schema/ │ ├── customer/ │ │ ├── customer.graphql │ │ ├── customer-profile.graphql │ │ ├── customer-queries.graphql │ │ └── customer-mutations.graphql │ ├── address/ │ │ ├── address.graphql │ │ └── address-validation.graphql │ ├── loyalty/ │ │ ├── loyalty-program.graphql │ │ └── loyalty-calculations.graphql │ ├── shared/ │ │ ├── scalars.graphql │ │ ├── enums.graphql │ │ └── interfaces.graphql │ └── schema.graphql
Layer-Based Organization	Organize schema files by architectural layers	Clear architectural layers Consistent layer organization Dependencies flow correctly Layer boundaries respected	Easy to navigate structure	order-subgraph/ ├── schema/ │ ├── entities/ │ │ ├── order.graphql │ │ ├── line-item.graphql │ │ └── order-status.graphql │ ├── value-objects/ │ │ ├── money.graphql │ │ ├── address.graphql │ │ └── date-range.graphql │ ├── services/ │ │ ├── pricing-service.graphql │ │ ├── shipping-service.graphql │ │ └── tax-service.graphql │ ├── events/ │ │ ├── order-events.graphql │ │ └── event-interfaces.graphql │ ├── operations/ │ │ ├── queries.graphql │ │ ├── mutations.graphql │ │ └── subscriptions.graphql │ └── schema.graphql
Feature-Based Organization	Organize schema files around business features	Features clearly defined Feature boundaries respected Cross-feature dependencies minimized Feature evolution supported	Business alignment clear	product-subgraph/ ├── schema/ │ ├── catalog-management/ │ │ ├── product.graphql │ │ ├── category.graphql │ │ ├── catalog-queries.graphql │ │ └── catalog-mutations.graphql │ ├── inventory-tracking/ │ │ ├── inventory.graphql │ │ ├── stock-levels.graphql │ │ └── inventory-operations.graphql │ ├── pricing/ │ │ ├── price.graphql │ │ ├── discounts.graphql │ │ └── pricing-rules.graphql │ ├── search/ │ │ ├── search-types.graphql │ │ ├── filters.graphql │ │ └── search-operations.graphql │ └── schema.graphql
Aggregate-Centric Type Grouping	Group types around domain aggregates	Aggregate boundaries clear Related types grouped together Aggregate operations co-located Aggregate consistency maintained	Clear ownership model	# customer-aggregate.graphql # Customer Aggregate Root type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! status: CustomerStatus! addresses: CustomerAddresses! } # Customer Profile (part of Customer aggregate) type CustomerProfile { personalInfo: PersonalInfo! contactInfo: ContactInfo! preferences: CustomerPreferences! } # Customer Addresses (part of Customer aggregate) type CustomerAddresses { billing: Address! shipping: Address additional: [Address!]! } # Customer-specific enums enum CustomerStatus { ACTIVE INACTIVE SUSPENDED PENDING_VERIFICATION } # Customer operations extend type Query { customer(id: ID!): Customer customerByNumber(customerNumber: String!): Customer } extend type Mutation { createCustomer(input: CreateCustomerInput!): CreateCustomerPayload! updateCustomer(input: UpdateCustomerInput!): UpdateCustomerPayload! }
Interface-Based Type Organization	Organize types around common interfaces and contracts	Interfaces define clear contracts Common behavior abstracted Interface implementations consistent Interface evolution planned	Polymorphic queries supported	# identifiable-interface.graphql interface Identifiable { id: ID! } interface Timestamped { createdAt: DateTime! updatedAt: DateTime! } interface Versioned { version: Int! lastModifiedBy: String! } # auditable-types.graphql interface Auditable implements Identifiable & Timestamped { id: ID! createdAt: DateTime! updatedAt: DateTime! auditTrail: [AuditEntry!]! } type AuditEntry { action: AuditAction! performedBy: String! performedAt: DateTime! changes: [FieldChange!]! } # domain-entities.graphql type Customer implements Identifiable & Timestamped & Auditable @key(fields: "id") { id: ID! createdAt: DateTime! updatedAt: DateTime! auditTrail: [AuditEntry!]! # Customer-specific fields customerNumber: String! profile: CustomerProfile! } type Order implements Identifiable & Timestamped & Versioned @key(fields: "id") { id: ID! createdAt: DateTime! updatedAt: DateTime! version: Int! lastModifiedBy: String! # Order-specific fields orderNumber: String! status: OrderStatus! }
Value Object Clustering	Group related value objects together	Related value objects grouped Value object behavior included Input types provided Validation rules embedded	Reusability maximized	# money-types.graphql type Money { amount: Decimal! currency: Currency! # Money behavior formattedAmount: String! minorUnits: Int! } enum Currency { USD EUR GBP JPY CAD } input MoneyInput { amount: Decimal! currency: Currency! } # measurement-types.graphql type Weight { value: Decimal! unit: WeightUnit! # Conversions inGrams: Decimal! inKilograms: Decimal! inPounds: Decimal! } type Dimensions { length: Length! width: Length! height: Length! # Computed properties volume: Volume! surfaceArea: Area! } enum WeightUnit { GRAM KILOGRAM POUND OUNCE } # contact-types.graphql type ContactInfo { email: Email! phone: PhoneNumber address: Address! } type Email { address: String! isVerified: Boolean! verifiedAt: DateTime } type PhoneNumber { number: String! countryCode: String! type: PhoneType! isVerified: Boolean! }
Modular Schema Composition	Compose schemas from modular components	Clear import structure Dependency order correct No circular dependencies Modular boundaries respected	Schema composition validates	# schema.graphql - Main composition file # Import base types #import "shared/scalars.graphql" #import "shared/interfaces.graphql" #import "shared/enums.graphql" # Import domain modules #import "customer/customer-types.graphql" #import "customer/customer-operations.graphql" #import "order/order-types.graphql" #import "order/order-operations.graphql" #import "product/product-types.graphql" #import "product/product-operations.graphql" # Import value objects #import "value-objects/money.graphql" #import "value-objects/address.graphql" #import "value-objects/contact.graphql" # Import events #import "events/domain-events.graphql" #import "events/event-subscriptions.graphql" # Schema definition schema { query: Query mutation: Mutation subscription: Subscription }
Namespace-Based Organization	Use GraphQL namespaces to organize related functionality	Namespaces logically organized Related operations grouped Namespace boundaries clear Query paths intuitive	Namespace evolution supported	# Namespace for customer operations type CustomerOperations { # Customer queries byId(id: ID!): Customer byNumber(customerNumber: String!): Customer search(query: String!, filter: CustomerFilter): CustomerSearchResult! # Customer analytics analytics(filter: AnalyticsFilter!): CustomerAnalytics! segmentation(criteria: SegmentationCriteria!): [CustomerSegment!]! } # Namespace for order operations type OrderOperations { # Order queries byId(id: ID!): Order byNumber(orderNumber: String!): Order byCustomer(customerId: ID!, filter: OrderFilter): [Order!]! # Order analytics analytics(filter: OrderAnalyticsFilter!): OrderAnalytics! reports(type: ReportType!, period: DateRange!): OrderReport! } # Root query with namespaces type Query { customers: CustomerOperations! orders: OrderOperations! products: ProductOperations! inventory: InventoryOperations! } # Usage: query { customers { byId(id: "123") { name } } }
Context-Aware Schema Organization	Organize schema elements by bounded context concerns	Context boundaries respected Context-specific concerns separated Cross-context relationships clear Context evolution independent	Domain alignment maintained	# customer-context.graphql # Customer bounded context types and operations type Customer @key(fields: "id") { id: ID! # Core customer context data customerNumber: String! profile: CustomerProfile! registrationInfo: RegistrationInfo! } type CustomerProfile { personalInfo: PersonalInfo! contactInfo: ContactInfo! preferences: CustomerPreferences! } extend type Query { # Customer context queries customer(id: ID!): Customer customerProfile(customerId: ID!): CustomerProfile } extend type Mutation { # Customer context mutations registerCustomer(input: RegisterCustomerInput!): RegisterCustomerPayload! updateProfile(input: UpdateProfileInput!): UpdateProfilePayload! } # order-context.graphql # Order bounded context extensions extend type Customer @key(fields: "id") { id: ID! @external # Order context view of customer orderHistory: OrderHistory! loyaltyStatus: LoyaltyStatus! shippingPreferences: ShippingPreferences! } extend type Query { # Order context queries customerOrders(customerId: ID!): [Order!]! orderStatistics(customerId: ID!): OrderStatistics! }
Schema Documentation Strategy	Organize comprehensive schema documentation	All types documented Business rules explained Examples provided Relationships documented	Evolution notes included	""" Customer aggregate root representing a business customer. The Customer entity encapsulates all customer-related information and serves as the primary entry point for customer operations. Business Rules: - Customer numbers must be unique across the system - Email addresses must be verified before account activation - Customer status changes trigger domain events Related Aggregates: - Order: Customers can place multiple orders - Payment: Customers can have multiple payment methods """ type Customer @key(fields: "id") { """ Unique identifier for the customer. This ID is stable across the customer lifecycle and is used for federation across subgraphs. """ id: ID! """ Business identifier for the customer. Format: CUS-YYYYMMDD-NNNN Example: CUS-20231201-0001 Generated automatically during customer registration. """ customerNumber: String! """ Customer profile containing personal and contact information. The profile is a value object that encapsulates all customer-specific data and preferences. """ profile: CustomerProfile! }
Schema Metadata Organization	Include rich metadata for schema governance	Ownership information included Version information tracked Business rules documented Performance hints provided	Governance metadata complete	# Schema metadata directive @owner(team: String!, contact: String!) on OBJECT | FIELD_DEFINITION directive @since(version: String!) on OBJECT | FIELD_DEFINITION | ENUM_VALUE directive @businessRule(description: String!) on OBJECT | FIELD_DEFINITION directive @performance(complexity: Int!, cacheHint: String) on FIELD_DEFINITION type Customer @key(fields: "id") @owner(team: "Customer Experience", contact: "customer-team@company.com") @since(version: "1.0.0") @businessRule( description: "Customer must have verified email before activation" ) { id: ID! @since(version: "1.0.0") customerNumber: String! @since(version: "1.0.0") @businessRule(description: "Must follow format CUS-YYYYMMDD-NNNN") profile: CustomerProfile! @since(version: "1.1.0") @performance(complexity: 5, cacheHint: "300s") loyaltyLevel: LoyaltyLevel! @since(version: "2.0.0") @performance(complexity: 3, cacheHint: "600s") }

Modularization

DDD Concept	Definition	Characteristics	Considerations	Example
Ubiquitous Language	A common language shared between domain experts and developers, reflected in code and schema	Type names must use domain terminology, not technical terms	All type names use business terminology	# ✅ Good - Uses domain language type Order { orderNumber: String! customer: Customer! lineItems: [LineItem!]! totalAmount: Money! status: OrderStatus! } # ❌ Bad - Uses technical language type OrderRecord { id: ID! customerId: ID! items: [OrderItemRecord!]! total: Float! statusCode: Int! }
Domain Module Pattern	Create modules around domain aggregates and bounded contexts	Module boundaries align with domain boundaries Clear module dependencies Well-defined module interface Module versioning strategy Module documentation complete	Encapsulates all related types, operations, and business logic within a bounded context Dependencies and exports are explicitly defined	customer-domain-module/ ├── types/ │ ├── customer.graphql │ ├── customer-profile.graphql │ ├── customer-address.graphql │ └── customer-enums.graphql ├── operations/ │ ├── customer-queries.graphql │ ├── customer-mutations.graphql │ └── customer-subscriptions.graphql ├── interfaces/ │ ├── customer-interfaces.graphql │ └── customer-contracts.graphql ├── events/ │ ├── customer-events.graphql │ └── customer-handlers.graphql └── module.graphql
Capability Module Pattern	Organize modules around business capabilities	Capability clearly defined Service interfaces well-designed Capability versioning managed Integration points documented Capability testing comprehensive	Provides comprehensive capabilities, such as price calculation or discount application Defines metadata and services for the capability	pricing-capability-module/ ├── services/ │ ├── price-calculation.graphql │ ├── discount-engine.graphql │ └── tax-calculation.graphql ├── types/ │ ├── price-quote.graphql │ ├── discount-types.graphql │ └── tax-types.graphql ├── rules/ │ ├── pricing-rules.graphql │ ├── discount-rules.graphql │ └── tax-rules.graphql └── capability.graphql
Shared Module Pattern	Create reusable modules for common types and functionality	Shared types are truly reusable Module stability is appropriate Versioning strategy is clear Usage guidelines provided Governance model defined	Provides common value objects and types used across multiple bounded contexts Emphasizes immutability, self-validating types, and backward compatibility	shared-value-objects-module/ ├── money/ │ ├── money-types.graphql │ ├── currency-types.graphql │ └── money-operations.graphql ├── temporal/ │ ├── date-types.graphql │ ├── duration-types.graphql │ └── date-range-types.graphql ├── contact/ │ ├── address-types.graphql │ ├── email-types.graphql │ └── phone-types.graphql ├── measurement/ │ ├── weight-types.graphql │ ├── dimension-types.graphql │ └── volume-types.graphql └── shared-module.graphql
Hierarchical Module Composition	Compose modules in hierarchical layers	Layer dependencies are clear No circular dependencies Layer boundaries respected Composition order correct Dependency validation automated	Organizes schemas into distinct layers (e.g., Foundation, Value Objects, Domain, Capability, Integration) Defines strict dependency rules to prevent circular dependencies	subgraph-schema/ ├── foundation/ │ ├── shared-scalars/ │ ├── shared-interfaces/ │ └── shared-enums/ ├── value-objects/ │ ├── money-module/ │ ├── contact-module/ │ └── temporal-module/ ├── domain-modules/ │ ├── customer-module/ │ ├── product-module/ │ └── order-module/ ├── capability-modules/ │ ├── pricing-module/ │ ├── inventory-module/ │ └── shipping-module/ ├── integration-modules/ │ ├── federation-module/ │ ├── event-module/ │ └── api-module/ └── schema.graphql
Plugin-Based Module System	Design modules as pluggable components	Plugin interface well-defined Module lifecycle managed Configuration externalized Dependencies resolved automatically Plugin registry maintained	Modules implement a common ModulePlugin interface Supports dynamic activation/deactivation and dependency resolution	interface ModulePlugin { name: String! version: String! isEnabled: Boolean! dependencies: [ModuleDependency!]! initialize: InitializationResult! validate: ValidationResult! activate: ActivationResult! deactivate: DeactivationResult! } type CustomerModulePlugin implements ModulePlugin { # ... (details omitted for brevity) } type ModuleRegistry { registeredModules: [ModulePlugin!]! activeModules: [ModulePlugin!]! moduleGraph: ModuleDependencyGraph! # ... (operations omitted for brevity) }
Event-Driven Module Integration	Integrate modules through domain events	Event contracts well-defined Event routing configured Error handling robust Event ordering preserved Module coupling minimized	Modules communicate by publishing and subscribing to domain events Events are well-defined, and handlers manage event processing	interface ModuleEvent { eventId: ID! moduleSource: String! eventType: String! occurredAt: DateTime! payload: JSON! } type CustomerModuleEvent implements ModuleEvent { # ... (details omitted for brevity) } type ModuleEventHandler { handlerName: String! moduleSource: String! eventTypes: [String!]! isActive: Boolean! # ... (configuration omitted for brevity) } type ModuleEventBus { publishEvent(event: ModuleEventInput!): PublishResult! subscribeToEvents(filter: EventFilter!): Subscription! getEventHistory(filter: EventHistoryFilter!): [ModuleEvent!]! # ... (metrics omitted for brevity) }
Module Lifecycle Management	Define clear lifecycle stages for modules	Lifecycle stages clearly defined Transition criteria specified Ownership model clear Quality gates enforced Compliance requirements met	Defines stages like DEVELOPMENT, PRODUCTION, DEPRECATED, and transition criteria Includes governance policies for ownership, changes, and quality	type ModuleLifecycle { currentStage: LifecycleStage! stageHistory: [LifecycleStageEntry!]! nextStage: LifecycleStage stageTransitionCriteria: [String!]! } enum LifecycleStage { DEVELOPMENT TESTING STAGING PRODUCTION MAINTENANCE DEPRECATED RETIRED } type ModuleGovernance { owner: ModuleOwner! maintainers: [ModuleMaintainer!]! reviewers: [ModuleReviewer!]! # ... (policies and gates omitted for brevity) }
Module Versioning Strategy	Implement semantic versioning for modules	Semantic versioning followed Breaking changes documented Migration guides provided Dependency constraints clear Compatibility matrix maintained	Adheres to semantic versioning (major, minor, patch) Documents release notes, breaking changes, and deprecations with migration guides	type ModuleVersion { version: String! # "2.1.0" majorVersion: Int! # 2 minorVersion: Int! # 1 patchVersion: Int! # 0 # ... (metadata and compatibility omitted for brevity) dependencies: [ModuleDependency!]! dependents: [ModuleDependent!]! } type BreakingChange { type: BreakingChangeType! description: String! migrationGuide: String! affectedTypes: [String!]! introducedInVersion: String! } enum BreakingChangeType { TYPE_REMOVED FIELD_REMOVED FIELD_TYPE_CHANGED OPERATION_REMOVED OPERATION_SIGNATURE_CHANGED ENUM_VALUE_REMOVED }

Versioning

DDD Concept	Definition	Characteristics	Considerations	Example
Schema Evolution and Versioning	Strategies for evolving DDD-compliant schemas in GraphQL federated architectures while maintaining backward compatibility	Requires careful planning Enables domain model growth Avoids breaking existing clients	Maintaining backward compatibility is crucial Schema evolution should reflect domain model evolution Federation impact must be considered during subgraph evolution	# Version 1.0 - Initial schema type Customer @key(fields: "id") { id: ID! name: String! email: String! } # Version 1.1 - Additive changes (safe) type Customer @key(fields: "id") { id: ID! name: String! email: String! phone: String registrationDate: DateTime displayName: String! isActive: Boolean! }
Backward Compatibility	New schema versions must not break existing clients	Safe evolution patterns: adding optional fields, types, enum values (at end), operations, or deprecating fields with alternatives Unsafe evolution patterns: removing fields without deprecation, changing field types, making optional fields required, removing enum values, changing operation signatures	All changes should maintain backward compatibility Deprecated fields need clear migration paths New fields should be optional or have defaults Breaking changes must be avoided Migration timeline should be communicated	# Version 1.2 - Field deprecation (safe with migration period) type Customer @key(fields: "id") { id: ID! name: String! @deprecated(reason: "Use profile.fullName instead") email: String! @deprecated(reason: "Use profile.contactInfo.email instead") phone: String @deprecated(reason: "Use profile.contactInfo.phone instead") profile: CustomerProfile! displayName: String! isActive: Boolean! }
Domain-Driven Evolution	Schema evolution should reflect domain model evolution	Evolution is driven by a deeper understanding of the business domain Business concepts are properly modeled	Evolution should reflect deeper domain understanding Business concepts should be properly modeled Domain expert feedback must be incorporated Ubiquitous language must be maintained Business rules should be embedded in the schema	# V2: Richer domain model as understanding grows type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! status: CustomerStatus! name: String! @deprecated(reason: "Use profile.fullName") email: String! @deprecated(reason: "Use profile.contactInfo.email") } type CustomerProfile { personalInfo: PersonalInfo! contactInfo: ContactInfo! preferences: CustomerPreferences! }
Federated Evolution	Subgraph evolution must consider federation impact	Changes within a subgraph can affect the overall federated graph Requires coordination across subgraphs	Federation keys should remain stable External field changes require coordination Cross-subgraph impacts must be assessed Schema composition should continue to work Query planning should not be negatively affected	# V2: Enhanced customer with multiple keys type Customer @key(fields: "id") @key(fields: "customerNumber") { id: ID! customerNumber: String! profile: CustomerProfile! name: String! @deprecated(reason: "Use profile.fullName") email: String! @deprecated(reason: "Use profile.contactInfo.email") } extend type Customer @key(fields: "customerNumber") { customerNumber: String! @external orders: [Order!]! }
Semantic Versioning for Schemas	Applying semantic versioning principles to GraphQL schemas	Uses Major, Minor, and Patch version increments Major for breaking changes, Minor for backward-compatible features, Patch for bug fixes	Version numbers should follow semantic versioning Breaking changes should increment the major version New features should increment the minor version Bug fixes should increment the patch version Version metadata should be maintained	type SchemaInfo { version: String! # "2.1.0" majorVersion: Int! # 2 minorVersion: Int! # 1 patchVersion: Int! # 0 deprecatedFields: [DeprecatedField!]! addedInVersion: String! compatibilityLevel: CompatibilityLevel! }
Field-Level Versioning	Versioning individual fields for granular evolution	Allows for independent evolution of fields Provides clear deprecation timelines for specific fields	Field versions should be tracked Deprecation timelines should be clear Migration guidance should be provided Field evolution should be documented Client impact should be assessed	type Customer @key(fields: "id") { id: ID! name: String! @deprecated(reason: "Use profile.fullName. Removed in v3.0") email: String! @deprecated(reason: "Use profile.contactInfo.email. Removed in v3.0") customerNumber: String! # Added in v2.0 profile: CustomerProfile! # Added in v2.0 loyaltyLevel: LoyaltyLevel! # Added in v2.1 fieldVersions: [FieldVersion!]! }
Type Versioning	Versioning entire types when significant changes occur	Allows new type versions to coexist with old ones during migration Useful for major structural changes to a type	Type versions should coexist during migration Migration paths should be clearly defined Data consistency must be maintained Client migration should be supported A rollback strategy should exist	# V1 Customer type type Customer @key(fields: "id") { id: ID! name: String! email: String! } # V2 Customer type (coexisting during migration) type CustomerV2 @key(fields: "id") @key(fields: "customerNumber") { id: ID! customerNumber: String! profile: CustomerProfile! status: CustomerStatus! }
Gradual Migration	Migrating clients gradually over time	Supports both old and new patterns concurrently Provides migration helpers and guidance to clients	Migration timelines should be communicated Legacy and new patterns should coexist Migration assistance should be provided Progress should be tracked Support should be available during migration	type Customer @key(fields: "id") { id: ID! name: String! @deprecated(reason: "Use profile.fullName") email: String! @deprecated(reason: "Use profile.contactInfo.email") profile: CustomerProfile! migrationInfo: MigrationInfo! } type Query { customer(id: ID!): Customer @deprecated(reason: "Use customerByNumber") customerByNumber(customerNumber: String!): Customer }
Feature Flags for Schema Evolution	Using feature flags to control schema evolution	New schema elements can be toggled on or off using flags Allows for gradual rollout and testing of new features	Feature flags should control new functionality Flag states should be clearly documented Flag rollout should be gradual Flag removal should be planned Flag dependencies should be managed	type Customer @key(fields: "id") { id: ID! name: String! email: String! profile: CustomerProfile # Available when "enhanced_customer_profile" flag is enabled loyaltyProgram: LoyaltyProgram # Available when "loyalty_program" flag is enabled } type Query { customer(id: ID!): Customer customerAnalytics(customerId: ID!): CustomerAnalytics # Requires "analytics" flag }
Blue-Green Schema Deployment	Deploying new schema versions alongside existing ones	New versions are deployed to a separate "green" environment Traffic can be gradually shifted from "blue" to "green."	Both environments should be fully functional Traffic can be gradually shifted Rollback should be immediate if needed Data consistency must be maintained Monitoring should cover both environments	# Blue environment (current production) type Customer @key(fields: "id") { id: ID! name: String! email: String! } # Green environment (new version) type Customer @key(fields: "id") @key(fields: "customerNumber") { id: ID! customerNumber: String! profile: CustomerProfile! name: String! @deprecated(reason: "Use profile.fullName") email: String! @deprecated(reason: "Use profile.contactInfo.email") }
Schema Change Events	Publishing events when schema changes occur	Clients can subscribe to these events to react to schema updates Provides a real-time notification mechanism for schema evolution	Schema changes should be published as events Clients should be able to subscribe to schema changes Change notifications should include migration guidance Event history should be maintained Change impact should be communicated	type Subscription { schemaChanges: SchemaChangeEvent! } union SchemaChangeEvent = FieldAdded | FieldDeprecated | FieldRemoved | TypeAdded | TypeModified type FieldAdded implements SchemaChangeEvent { eventId: ID! timestamp: DateTime! typeName: String! fieldName: String! fieldType: String! version: String! description: String! }
Automated Migration Detection	Automatically detecting and suggesting migrations	Tools can analyze client schemas and suggest necessary updates Estimates migration effort and identifies automation opportunities	Migration opportunities should be identified automatically Migration effort should be estimated Automation should be provided where possible Migration tracking should be available Success metrics should be defined	type Query { migrationOpportunities(clientId: String!): [MigrationOpportunity!]! schemaCompatibility(clientSchema: String!): CompatibilityReport! } type MigrationOpportunity { type: MigrationType! description: String! currentUsage: String! recommendedChange: String! effort: MigrationEffort! deadline: DateTime! automationAvailable: Boolean! }

Patterns

Decision Tree

Category	Decision Tree	Checklist
Bounded Context Decisions
Context Boundary Identification	Should this be a separate bounded context? Does this concept have different meanings in different parts of the business? → Yes: Separate bounded contexts / No: Continue evaluation Do different teams have expertise in different aspects of this concept? → Yes: Consider separate bounded contexts / No: Continue evaluation Would changes to this concept affect different business capabilities? → Yes: Separate bounded contexts / No: Continue evaluation Can this concept be owned and evolved independently? → Yes: Good candidate for separate context / No: Consider shared context or different boundaries Does this concept have its own data and business rules? → Yes: Strong candidate for separate context / No: Likely part of larger context	Context Boundary Validation Context has clear business purpose Context can be owned by single team Context has minimal dependencies on other contexts Context boundaries align with data ownership Context size is manageable for team Context has cohesive set of capabilities Context interfaces are well-defined Context can evolve independently
Subgraph Mapping Decision	Should this bounded context be a single subgraph? Does the context represent a single business capability? → No: Consider splitting into multiple subgraphs / Yes: Continue evaluation Can the context be owned by a single team? → No: Split into team-owned subgraphs / Yes: Continue evaluation Are all entities in the context highly cohesive? → No: Consider entity-based subgraph split / Yes: Continue evaluation Does the context have consistent change frequency? → No: Consider splitting by change patterns / Yes: Good candidate for single subgraph Is the context size manageable for development and deployment? → No: Consider splitting for manageability / Yes: Proceed with single subgraph	Subgraph Design Validation Subgraph represents single bounded context Subgraph has clear ownership Subgraph entities are cohesive Subgraph has minimal external dependencies Subgraph can be deployed independently Subgraph has appropriate size and complexity Subgraph interfaces are well-defined Subgraph evolution strategy is clear
Entity and Aggregate Decisions
Entity vs Value Object Decision	Should this be an entity or value object? Does this concept have a distinct identity that matters to the business? → Yes: Entity / No: Continue evaluation Does this concept need to be tracked over time? → Yes: Entity / No: Continue evaluation Can two instances with the same attributes be considered identical? → Yes: Value Object / No: Entity Does this concept have a lifecycle independent of other concepts? → Yes: Entity / No: Value Object	Entity Design Validation Entity has stable, unique identity Entity identity is meaningful to business Entity has independent lifecycle Entity can be referenced from other contexts Entity supports required operations Entity boundaries are clear Entity state changes are tracked Entity relationships are well-defined Value Object Design Validation Value object has no identity Value object is immutable Value object validates its own invariants Value object can be compared by value Value object encapsulates related attributes Value object has clear semantic meaning Value object is reusable across contexts Value object serialization is well-defined
Aggregate Boundary Decision	Should these entities be in the same aggregate? Do these entities need to be consistent together? → Yes: Same aggregate / No: Continue evaluation Do these entities change together as part of business operations? → Yes: Same aggregate / No: Continue evaluation Can these entities exist independently? → No: Same aggregate / Yes: Continue evaluation Is the relationship ownership or reference? → Ownership: Same aggregate / Reference: Different aggregates Would separating these entities create consistency issues? → Yes: Same aggregate / No: Different aggregates	Aggregate Design Validation Aggregate has single root entity Aggregate maintains business invariants Aggregate size is manageable Aggregate boundaries respect consistency requirements Aggregate operations are atomic Aggregate can be loaded and saved as unit Aggregate has clear ownership Aggregate minimizes external dependencies
Federation Design Decisions
Entity Federation Strategy	How should this entity be federated? Is this entity owned by this subgraph? → Yes: Define as primary entity with @key / No: Continue evaluation Does this subgraph need to add context-specific data to the entity? → Yes: Extend entity with relevant fields / No: Continue evaluation Does this subgraph only need to reference the entity? → Yes: Reference by ID only / No: Extend with needed fields Does this subgraph need to provide data for other subgraphs? → Yes: Use @provides directive / No: Standard extension	Entity Federation Validation Entity ownership is clear Key fields are stable and unique External fields are properly marked Required fields are available Provided fields are accurate Federation directives are correct Cross-subgraph references are minimal Performance implications are considered
Field Resolution Strategy	How should this field be resolved? Is the data owned by this subgraph? → Yes: Resolve locally / No: Continue evaluation Is the data available from another subgraph? → Yes: Use federation to resolve / No: Continue evaluation Can the data be computed from available data? → Yes: Compute in resolver / No: Continue evaluation Is the data critical for this context? → Yes: Consider data replication / No: Use reference or omit	Field Resolution Validation Data ownership is clear Resolution strategy is efficient Dependencies are minimal Error handling is robust Performance is acceptable Caching strategy is defined Fallback behavior is specified Monitoring is in place
Schema Design Decisions
Type Design Strategy	What GraphQL type should this concept be? Does this concept represent a distinct business entity? → Yes: Object Type / No: Continue evaluation Does this concept represent a set of related values? → Yes: Object Type (Value Object) / No: Continue evaluation Does this concept represent a choice from fixed options? → Yes: Enum Type / No: Continue evaluation Does this concept define a contract for multiple implementations? → Yes: Interface Type / No: Continue evaluation Does this concept represent one of several possible types? → Yes: Union Type / No: Scalar Type	Type Design Validation Type purpose is clear Type name follows conventions Type fields are appropriate Type relationships are well-defined Type supports required operations Type evolution is considered Type documentation is complete Type validation is comprehensive
Field Design Strategy	How should this field be designed? Is this field always present? → Yes: Non-nullable field / No: Continue evaluation Can this field be null in valid business scenarios? → Yes: Nullable field / No: Non-nullable field Does this field represent a collection? → Yes: List type / No: Continue evaluation Can the collection be empty? → Yes: Nullable list or non-null list of nullable items / No: Non-null list of non-null items Is this field computed from other data? → Yes: Resolver-computed field / No: Direct field mapping	Field Design Validation Field nullability is correct Field type is appropriate Field name follows conventions Field documentation is clear Field validation is defined Field performance is acceptable Field evolution is considered Field relationships are correct
Operation Design Decisions
Query vs Mutation Decision	Should this be a query or mutation? Does this operation change system state? → Yes: Mutation / No: Query Does this operation have side effects? → Yes: Mutation / No: Query Is this operation idempotent? → No: Mutation / Yes: Could be Query Does this operation need to be cached? → Yes: Prefer Query / No: Either Query or Mutation	Operation Design Validation Operation type is appropriate (Query/Mutation/Subscription) Operation name is descriptive Operation parameters are well-defined Operation return type is appropriate Operation error handling is comprehensive Operation performance is acceptable Operation security is considered Operation documentation is complete
Input Design Strategy	How should operation inputs be structured? Does the operation have multiple parameters? → Yes: Use input object / No: Continue evaluation Are the parameters logically related? → Yes: Group in input object / No: Consider separate parameters Will the operation parameters evolve over time? → Yes: Use input object for flexibility / No: Either approach acceptable Do multiple operations share similar parameters? → Yes: Create reusable input types / No: Operation-specific input	Input Design Validation Input structure is logical Input fields are appropriately nullable Input validation is comprehensive Input evolution is considered Input reusability is maximized Input documentation is clear Input naming follows conventions Input complexity is manageable
Event Design Decisions
Event Granularity Decision	What should be the scope of this event? Does this represent a single business occurrence? → Yes: Single event / No: Continue evaluation Do multiple things happen atomically? → Yes: Single event with rich payload / No: Multiple events Do different consumers need different parts of the information? → Yes: Consider multiple events or rich event with optional data / No: Single event Is the event payload becoming too large? → Yes: Split into multiple events / No: Single event acceptable	Event Design Validation Event represents business occurrence Event name uses past tense Event payload is appropriate size Event is immutable Event includes necessary context Event versioning is considered Event ordering is defined Event error handling is specified
Event Publishing Strategy	How should this event be published? Do consumers need immediate notification? → Yes: Real-time publishing / No: Continue evaluation Can consumers tolerate eventual consistency? → Yes: Asynchronous publishing / No: Synchronous publishing Do all consumers need all events? → No: Filtered publishing / Yes: Broadcast publishing Is event ordering important? → Yes: Ordered publishing / No: Unordered publishing acceptable	Event Publishing Validation Publishing mechanism is appropriate Event routing is configured Event filtering is available Event ordering is preserved when needed Event delivery guarantees are defined Event error handling is robust Event monitoring is in place Event retention is managed
Performance and Scalability Decisions
Caching Strategy Decision	What caching strategy should be used? Does this data change frequently? → Yes: Short TTL or no caching / No: Continue evaluation Is this data expensive to compute? → Yes: Cache with appropriate TTL / No: Continue evaluation Do multiple clients request the same data? → Yes: Shared caching / No: Client-side caching Is data consistency critical? → Yes: Cache invalidation strategy needed / No: TTL-based caching acceptable	Caching Strategy Validation Caching strategy matches data characteristics Cache TTL is appropriate Cache invalidation is handled Cache performance is monitored Cache consistency is maintained Cache storage is appropriate Cache security is considered Cache evolution is planned
Pagination Strategy Decision	What pagination approach should be used? Is the dataset size bounded and small? → Yes: No pagination needed / No: Continue evaluation Do clients need to navigate arbitrarily through the dataset? → Yes: Cursor-based pagination / No: Continue evaluation Is the dataset frequently updated? → Yes: Cursor-based pagination / No: Offset-based pagination acceptable Do clients need to know total count? → Yes: Include total count / No: Omit total count for performance	Pagination Strategy Validation Pagination approach matches use case Page size limits are enforced Pagination performance is acceptable Pagination consistency is maintained Pagination metadata is appropriate Pagination error handling is robust Pagination documentation is clear Pagination evolution is considered

Patterns

DDD Concept	Definition	Characteristics	Considerations	Example
Ubiquitous Language	A common language shared between domain experts and developers, reflected in code and schema	Type names must use domain terminology, not technical terms	All type names use business terminology	# ✅ Good - Uses domain language type Order { orderNumber: String! customer: Customer! lineItems: [LineItem!]! totalAmount: Money! status: OrderStatus! } # ❌ Bad - Uses technical language type OrderRecord { id: ID! customerId: ID! items: [OrderItemRecord!]! total: Float! statusCode: Int! }
Aggregate Root Pattern	Designate a single entity as the aggregate root and route all operations through it	Complex business entities with multiple components Strong consistency requirements Clear business boundaries Transactional operations needed	Maintains business invariants Encapsulates business logic Clear ownership boundaries Simplified consistency model	# Aggregate Root type Order @key(fields: "id") { id: ID! orderNumber: String! customerId: ID! # Aggregate components (owned entities) lineItems: [LineItem!]! shippingAddress: Address! billingAddress: Address! # Aggregate state status: OrderStatus! totalAmount: Money! # Aggregate behavior canBeCancelled: Boolean! canBeModified: Boolean! estimatedDelivery: DateTime! } # Internal entities (not directly accessible) type LineItem { productSku: String! quantity: Int! unitPrice: Money! lineTotal: Money! } # Mutations operate on aggregate root type Mutation { createOrder(input: CreateOrderInput!): CreateOrderPayload! addLineItem(orderId: ID!, input: LineItemInput!): AddLineItemPayload! updateOrderStatus(orderId: ID! status: OrderStatus!): UpdateOrderStatusPayload! cancelOrder(orderId: ID!, reason: String!): CancelOrderPayload! }
Domain Service Pattern	Create domain services that encapsulate complex business logic	Complex calculations or algorithms Operations spanning multiple aggregates Stateless business logic Cross-cutting concerns	Encapsulates complex logic Promotes reusability Clear separation of concerns Testable business logic	type Query { # Pricing domain service calculatePrice(input: PriceCalculationInput!): PriceQuote! # Shipping domain service calculateShipping(input: ShippingCalculationInput!): ShippingQuote! # Inventory domain service checkAvailability(input: AvailabilityCheckInput!): AvailabilityResult! # Recommendation domain service getRecommendations(input: RecommendationInput!): RecommendationResult! } type PriceQuote { basePrice: Money! discounts: [Discount!]! taxes: [Tax!]! finalPrice: Money! validUntil: DateTime! # Service metadata calculationId: ID! calculatedAt: DateTime! pricingRules: [PricingRule!]! } type Mutation { # Order processing domain service processOrder(input: ProcessOrderInput!): ProcessOrderResult! # Payment processing domain service processPayment(input: ProcessPaymentInput!): ProcessPaymentResult! # Fulfillment domain service fulfillOrder(input: FulfillOrderInput!): FulfillOrderResult! }
Repository Pattern	Create repository-style query interfaces that hide persistence details	Complex query requirements Multiple access patterns for same data Need for pagination and filtering Abstraction over data storage	Domain-focused query interface Hides persistence complexity Supports multiple access patterns Enables query optimization	type Query { # Customer repository customer(id: ID!): Customer customerByNumber(customerNumber: String!): Customer customerByEmail(email: String!): Customer customers(filter: CustomerFilter, sort: CustomerSort): CustomerConnection! # Product repository product(sku: String!): Product productsByCategory(category: String!): [Product!]! searchProducts(query: String!, filter: ProductFilter): ProductSearchResult! # Order repository order(id: ID!): Order orderByNumber(orderNumber: String!): Order customerOrders(customerId: ID!, filter: OrderFilter): [Order!]! ordersInDateRange(from: DateTime!, to: DateTime!): [Order!]! } # Rich filter types input CustomerFilter { isActive: Boolean loyaltyLevel: [LoyaltyLevel!] registeredAfter: DateTime registeredBefore: DateTime hasOrders: Boolean totalSpentRange: MoneyRange } # Connection types for pagination type CustomerConnection { edges: [CustomerEdge!]! pageInfo: PageInfo! totalCount: Int! }
Entity Extension Pattern	Use GraphQL federation to extend entities with relevant context data	Entity spans multiple bounded contexts Context-specific data needs Avoiding god objects Maintaining separation of concerns	Maintains bounded context integrity Avoids data duplication Enables rich cross-context queries Supports independent evolution	# Customer subgraph (entity owner) type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! registrationDate: DateTime! } # Order subgraph (extends with order context) extend type Customer @key(fields: "id") { id: ID! @external # Order-specific customer data orders: [Order!]! orderHistory: OrderHistory! loyaltyPoints: Int! preferredShippingAddress: Address } # Marketing subgraph (extends with marketing context) extend type Customer @key(fields: "id") { id: ID! @external # Marketing-specific customer data marketingPreferences: MarketingPreferences! campaignHistory: [Campaign!]! segmentMemberships: [Segment!]! recommendedProducts: [Product!]! }
Federated Aggregate Pattern	Keep aggregate root in one subgraph and use events for cross-aggregate coordination	Aggregates span multiple contexts Eventual consistency is acceptable Need for loose coupling Complex business processes	Maintains aggregate boundaries Enables loose coupling Supports complex workflows Provides audit trail	# Order subgraph (aggregate owner) type Order @key(fields: "id") { id: ID! customerId: ID! status: OrderStatus! lineItems: [LineItem!]! totalAmount: Money! } type Mutation { placeOrder(input: PlaceOrderInput!): PlaceOrderPayload! # Publishes OrderPlaced event } # Inventory subgraph (separate aggregate) type InventoryItem @key(fields: "productSku") { productSku: String! quantityAvailable: Int! quantityReserved: Int! } type Subscription { # Listens for order events orderEvents: OrderEvent! } type Mutation { # Handles order events reserveInventory(input: ReserveInventoryInput!): ReserveInventoryPayload! } # Event coordination union OrderEvent = OrderPlaced | OrderCancelled | OrderShipped
Gateway Aggregation Pattern	Create aggregation types that combine data from multiple sources	Complex UI requirements Multiple data sources needed Performance optimization required Simplified client queries	Reduces client complexity Optimizes data fetching Provides unified views Enables caching strategies	# Gateway aggregation types type CustomerDashboard { customer: Customer! orderSummary: OrderSummary! paymentMethods: [PaymentMethod!]! recommendations: [Product!]! notifications: [Notification!]! # Aggregation metadata lastUpdated: DateTime! dataFreshness: DataFreshness! } type OrderSummary { totalOrders: Int! totalSpent: Money! averageOrderValue: Money! lastOrderDate: DateTime! # Recent activity recentOrders: [Order!]! pendingOrders: [Order!]! } type Query { # Aggregated views customerDashboard(customerId: ID!): CustomerDashboard! orderAnalytics(filter: AnalyticsFilter!): OrderAnalytics! inventoryReport(filter: InventoryFilter!): InventoryReport! }
Event Sourcing Pattern	Store all changes as immutable events and build current state from events	Complete audit trail required Temporal queries needed Complex business processes Regulatory compliance	Complete audit trail Temporal query capabilities Natural event publishing Debugging and analysis support	# Event store interface type EventStore { events(aggregateId: ID!, fromVersion: Int): [DomainEvent!]! eventsByType(eventType: String!, from: DateTime): [DomainEvent!]! appendEvent(event: DomainEventInput!): AppendEventResult! } # Domain events interface DomainEvent { eventId: ID! aggregateId: ID! eventType: String! occurredAt: DateTime! version: Int! } type CustomerRegistered implements DomainEvent { eventId: ID! aggregateId: ID! eventType: String! occurredAt: DateTime! version: Int! # Event data customerNumber: String! email: String! registrationChannel: String! } # Event-sourced aggregate type Customer @key(fields: "id") { id: ID! version: Int! # Current state (projected from events) customerNumber: String! profile: CustomerProfile! status: CustomerStatus! # Event history events: [DomainEvent!]! # Temporal queries stateAt(timestamp: DateTime!): CustomerSnapshot! }
Saga Pattern	Use saga orchestration to manage distributed transactions	Long-running business processes Multiple service coordination Compensation required Complex workflows	Manages distributed transactions Provides compensation mechanisms Enables complex workflows Maintains process visibility	# Saga orchestrator type OrderFulfillmentSaga { sagaId: ID! orderId: ID! currentStep: SagaStep! status: SagaStatus! # Saga state inventoryReserved: Boolean! paymentProcessed: Boolean! shippingArranged: Boolean! # Compensation tracking compensationActions: [CompensationAction!]! # Saga timeline startedAt: DateTime! completedAt: DateTime steps: [SagaStepExecution!]! } enum SagaStep { RESERVE_INVENTORY PROCESS_PAYMENT ARRANGE_SHIPPING COMPLETE_ORDER } type Mutation { # Saga management startOrderFulfillment(orderId: ID!): StartSagaResult! compensateOrderFulfillment(sagaId: ID!): CompensationResult! # Step execution executeReserveInventory(sagaId: ID!): StepResult! executeProcessPayment(sagaId: ID!): StepResult! executeArrangeShipping(sagaId: ID!): StepResult! } type Subscription { sagaEvents(sagaId: ID!): SagaEvent! }
DataLoader Pattern	Implement batching and caching for entity resolution	N+1 query problems High-frequency entity access Performance optimization needed Large result sets	Eliminates N+1 queries Improves performance Reduces service load Enables caching	# Efficient entity resolution type Order @key(fields: "id") { id: ID! customerId: ID! lineItems: [LineItem!]! # Efficiently resolved via DataLoader customer: Customer! } type LineItem { productSku: String! quantity: Int! # Batch loaded products product: Product! } # Batch loading interface (implementation detail) type BatchLoader { loadCustomers(ids: [ID!]!): [Customer!]! loadProducts(skus: [String!]!): [Product!]! loadOrders(ids: [ID!]!): [Order!]! }
Caching Strategy Pattern	Implement multi-level caching with appropriate invalidation strategies	Performance optimization required Expensive computations High-frequency access patterns Static or semi-static data	Improves response times Reduces computational load Scales better under load Provides better user experience	# Cache-aware types type Product @key(fields: "sku") { sku: String! name: String! price: Money! # Cache metadata cacheInfo: CacheInfo! } type CacheInfo { cacheKey: String! ttl: Int! lastUpdated: DateTime! cacheHit: Boolean! } # Cache control directives type Query { # Short-lived cache for dynamic data inventory(productSku: String!): InventoryLevel! @cacheControl(maxAge: 60) # Long-lived cache for static data productCatalog: [Product!]! @cacheControl(maxAge: 3600) # No cache for personalized data customerRecommendations(customerId: ID!): [Product!]! @cacheControl(maxAge: 0) }

Anti-Patterns

DDD Concept	Definition	Characteristics	Considerations	Example
Ubiquitous Language	A common language shared between domain experts and developers, reflected in code and schema	Type names must use domain terminology, not technical terms	All type names use business terminology	# ✅ Good - Uses domain language type Order { orderNumber: String! customer: Customer! lineItems: [LineItem!]! totalAmount: Money! status: OrderStatus! } # ❌ Bad - Uses technical language type OrderRecord { id: ID! customerId: ID! items: [OrderItemRecord!]! total: Float! statusCode: Int! }
Anemic Domain Model	Creating types that only contain data without behavior or business logic	Separates data from behavior Makes business logic hard to find and maintain Violates DDD principles Leads to procedural programming in GraphQL	Embed business logic in domain types Use computed fields for business rules Create rich value objects Encapsulate behavior with data	# ❌ Bad - Anemic domain model type Customer { id: ID! firstName: String! lastName: String! email: String! totalSpent: Float! orderCount: Int! } type Query { # Business logic in separate operations calculateCustomerDiscount(customerId: ID!, orderAmount: Float!): Float! validateCustomerCredit(customerId: ID!, amount: Float!): Boolean! determineShippingEligibility(customerId: ID!): Boolean! } # ✅ Good - Rich domain model type Customer { id: ID! firstName: String! lastName: String! email: String! # Business behavior embedded in the model loyaltyLevel: LoyaltyLevel! availableCredit: Money! isEligibleForFreeShipping: Boolean! # Computed business properties lifetimeValue: Money! riskScore: RiskScore! } type LoyaltyLevel { tier: LoyaltyTier! discountPercentage: Float! benefits: [LoyaltyBenefit!]! nextTierRequirement: Money }
Database-Driven Schema Design	Designing GraphQL schema to match database structure instead of domain model	Exposes implementation details Uses technical naming Doesn't reflect business concepts Makes schema hard to understand	Design schema based on domain model Use business terminology Hide database implementation details Focus on business capabilities	# ❌ Bad - Database-driven design type CustomerRecord { cust_id: ID! first_name: String! last_name: String! email_addr: String! created_dt: String! updated_dt: String! status_cd: Int! } type OrderRecord { order_id: ID! cust_id: ID! order_dt: String! total_amt: Float! currency_cd: String! status_cd: Int! } type OrderLineRecord { line_id: ID! order_id: ID! prod_id: ID! qty: Int! unit_price: Float! } # ✅ Good - Domain-driven design type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! registrationDate: DateTime! status: CustomerStatus! } type Order @key(fields: "id") { id: ID! orderNumber: String! customer: Customer! placementDate: DateTime! totalAmount: Money! status: OrderStatus! lineItems: [LineItem!]! } type LineItem { product: Product! quantity: Int! unitPrice: Money! lineTotal: Money! }
God Object Anti-Pattern	Creating overly large types that contain too many responsibilities	Violates single responsibility principle Makes types hard to understand and maintain Creates tight coupling Complicates evolution	Decompose large types into smaller, focused types Use composition over large flat structures Group related fields into value objects Respect aggregate boundaries	# ❌ Bad - God object type Customer { # Identity id: ID! customerNumber: String! # Personal info firstName: String! lastName: String! birthDate: Date! # Contact info email: String! phone: String! # Address info billingStreet: String! billingCity: String! billingState: String! billingZip: String! shippingStreet: String! shippingCity: String! shippingState: String! shippingZip: String! # Order info orders: [Order!]! totalOrders: Int! totalSpent: Money! averageOrderValue: Money! # Payment info paymentMethods: [PaymentMethod!]! defaultPaymentMethod: PaymentMethod! # Marketing info marketingOptIn: Boolean! preferredChannel: String! segments: [String!]! # Support info supportTickets: [SupportTicket!]! supportLevel: String! } # ✅ Good - Properly decomposed type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! status: CustomerStatus! } type CustomerProfile { personalInfo: PersonalInfo! contactInfo: ContactInfo! addresses: CustomerAddresses! preferences: CustomerPreferences! } type PersonalInfo { firstName: String! lastName: String! birthDate: Date! } type ContactInfo { email: String! phone: String! preferredContactMethod: ContactMethod! } type CustomerAddresses { billing: Address! shipping: Address additional: [Address!]! }
Chatty Federation	Creating excessive cross-subgraph calls for simple operations	Poor query performance High latency Service coupling Reliability issues	Use @provides directive to optimize data fetching Include necessary data in owning subgraph Pre-compute aggregations Design for query patterns	# ❌ Bad - Chatty federation # Customer subgraph type Customer @key(fields: "id") { id: ID! name: String! } # Order subgraph extend type Customer @key(fields: "id") { id: ID! @external orders: [Order!]! } # Product subgraph extend type Order @key(fields: "id") { id: ID! @external products: [Product!]! @requires(fields: "lineItems { productId }") } # Inventory subgraph extend type Product @key(fields: "id") { id: ID! @external availability: Availability! # Requires call to inventory service } # Results in: Customer → Orders → Products → Availability (4 service calls) # ✅ Good - Optimized federation # Order subgraph includes necessary data type Order @key(fields: "id") { id: ID! customer: Customer! @provides(fields: "name") lineItems: [LineItem!]! orderSummary: OrderSummary! # Pre-computed summary } type LineItem { product: Product! @provides(fields: "name price") quantity: Int! availability: AvailabilitySnapshot! # Snapshot at order time } type OrderSummary { totalItems: Int! totalAmount: Money! estimatedDelivery: DateTime! }
Shared Database Anti-Pattern	Multiple subgraphs accessing the same database tables	Violates bounded context principles Creates tight coupling Makes evolution difficult Causes data consistency issues	Each subgraph owns its data Use events for data synchronization Maintain separate data stores Respect bounded context boundaries	# ❌ Bad - Shared database access # Customer subgraph accesses customers table type Customer @key(fields: "id") { id: ID! name: String! email: String! } # Order subgraph also accesses customers table extend type Customer @key(fields: "id") { id: ID! @external # Directly queries customer table for this data totalOrders: Int! lastOrderDate: DateTime! } # Marketing subgraph also accesses customers table extend type Customer @key(fields: "id") { id: ID! @external # Directly queries customer table marketingSegments: [String!]! optInStatus: Boolean! } # ✅ Good - Clear data ownership # Customer subgraph owns customer data type Customer @key(fields: "id") { id: ID! name: String! email: String! profile: CustomerProfile! } # Order subgraph maintains its own order statistics extend type Customer @key(fields: "id") { id: ID! @external orderStatistics: OrderStatistics! # From order service's own data } # Marketing subgraph maintains its own customer data extend type Customer @key(fields: "id") { id: ID! @external marketingProfile: MarketingProfile! # From marketing service's own data }
Leaky Abstraction Anti-Pattern	Exposing internal implementation details through the GraphQL schema	Couples clients to implementation Makes refactoring difficult Exposes unnecessary complexity Violates encapsulation	Hide implementation details Use domain language in schema Focus on business capabilities Maintain clean abstractions	# ❌ Bad - Leaky abstraction type Customer { id: ID! name: String! # Exposing internal database structure customerRecord: CustomerRecord! auditLog: [AuditLogEntry!]! # Exposing internal service calls externalSystemId: String! lastSyncTimestamp: DateTime! syncStatus: String! # Exposing caching details cacheKey: String! cacheExpiry: DateTime! } type CustomerRecord { # Raw database fields created_at: DateTime! updated_at: DateTime! version: Int! deleted_flag: Boolean! } # ✅ Good - Clean abstraction type Customer @key(fields: "id") { id: ID! customerNumber: String! profile: CustomerProfile! # Business-focused metadata registrationDate: DateTime! lastActivityDate: DateTime! status: CustomerStatus! # Domain-relevant relationships orders: [Order!]! preferences: CustomerPreferences! } enum CustomerStatus { ACTIVE INACTIVE SUSPENDED PENDING_VERIFICATION }
Primitive Obsession	Using primitive types instead of domain-specific value objects	Loses domain meaning No validation or business rules Difficult to evolve Error-prone for clients	Create value objects for domain concepts Use enums for fixed choices Embed validation in types Make invalid states unrepresentable	# ❌ Bad - Primitive obsession type Product { id: ID! name: String! price: Float! # Should be Money weight: Float! # Should be Weight with unit dimensions: String! # Should be structured Dimensions currency: String! # Should be enum availability: String! # Should be enum or rich type tags: String! # Should be array } type Order { id: ID! total: Float! # Should be Money tax: Float! # Should be Money shipping: Float! # Should be Money status: String! # Should be enum date: String! # Should be DateTime } # ✅ Good - Rich value objects type Product { id: ID! name: String! price: Money! weight: Weight! dimensions: Dimensions! availability: ProductAvailability! tags: [ProductTag!]! } type Money { amount: Decimal! currency: Currency! } type Weight { value: Decimal! unit: WeightUnit! } type Dimensions { length: Length! width: Length! height: Length! } enum Currency { USD EUR GBP } type ProductAvailability { status: AvailabilityStatus! quantity: Int! restockDate: DateTime }
Inconsistent Nullability	Inconsistent or incorrect use of nullable vs non-nullable fields	Confuses client developers Leads to runtime errors Makes schema hard to understand Inconsistent error handling	Use non-null for required business data Use nullable only when business allows null Be consistent across similar fields Document nullability decisions	# ❌ Bad - Inconsistent nullability type Customer { id: ID # Should be non-null name: String! # Good email: String # Should probably be non-null phone: String! # Might be null in some cases orders: [Order!] # List itself should be non-null addresses: [Address!]! # Good } type Order { id: ID! # Good customer: Customer # Should be non-null total: Money! # Good items: [LineItem] # Should be non-null list } # ✅ Good - Consistent nullability type Customer { id: ID! # Always present name: String! # Always required email: String! # Required for customers phone: String # Optional orders: [Order!]! # Non-null list, might be empty addresses: [Address!]! # Non-null list, might be empty } type Order { id: ID! # Always present customer: Customer! # Always has a customer total: Money! # Always calculated items: [LineItem!]! # Non-null list, never empty for valid orders }
Over-Normalization	Excessive normalization that makes queries complex and inefficient	Requires multiple queries for simple data Poor performance Complex client code Doesn't match usage patterns	Design for query patterns Group related data together Use composition over excessive normalization Consider client needs	# ❌ Bad - Over-normalized type Customer { id: ID! personalInfoId: ID! contactInfoId: ID! addressIds: [ID!]! } type PersonalInfo { id: ID! firstName: String! lastName: String! birthDate: Date! } type ContactInfo { id: ID! emailId: ID! phoneId: ID! } type Email { id: ID! address: String! type: EmailType! } type Phone { id: ID! number: String! type: PhoneType! } # Requires multiple queries to get basic customer info # ✅ Good - Appropriate denormalization type Customer { id: ID! profile: CustomerProfile! addresses: [Address!]! } type CustomerProfile { personalInfo: PersonalInfo! contactInfo: ContactInfo! } type PersonalInfo { firstName: String! lastName: String! birthDate: Date! } type ContactInfo { primaryEmail: Email! secondaryEmail: Email primaryPhone: Phone! secondaryPhone: Phone } type Email { address: String! type: EmailType! isVerified: Boolean! } type Phone { number: String! type: PhoneType! isVerified: Boolean! }