Nest QL Schema Package

GraphQL schema definitions and generated TypeScript types for Nest Tanzania Rental Platform.

🔒 Schema Safety Guarantees

This package enforces package-level schema validation with modular architecture:

• ✅ Modular schema files - Domain-separated .graphql files for maintainability
• ✅ Single deployable schema - Merged into schemas/appsync.graphql at build time
• ✅ Build-time validation - Invalid schemas fail during npm run build
• ✅ Publish-time protection - npm publish fails if schema is invalid
• ✅ AppSync compatibility - Generated schema is AppSync-safe only

📁 Modular Schema Structure

schemas/
├── _shared/
│   ├── scalars.graphql      ← AWSDateTime, AWSJSON
│   ├── enums.graphql        ← All enums
│   └── directives.graphql   ← @aws_subscribe
│
├── location/
│   ├── types.graphql        ← Region, District, Ward, Street
│   └── queries.graphql      ← Location queries
│
├── user/
│   ├── types.graphql        ← Tenant, Landlord, Admin, UserProfile
│   ├── inputs.graphql       ← SignUpInput, UpdateUserInput
│   ├── queries.graphql      ← User queries
│   └── mutations.graphql    ← Auth & user mutations
│
├── property/
│   ├── types.graphql        ← Property, Address, PropertyMedia
│   ├── inputs.graphql       ← CreatePropertyInput, UpdatePropertyInput
│   ├── queries.graphql      ← Property queries
│   ├── mutations.graphql    ← Property mutations
│   └── subscriptions.graphql ← Property subscriptions
│
├── application/
│   ├── types.graphql        ← Application, ApplicantDetails
│   ├── inputs.graphql       ← SubmitApplicationInput
│   ├── queries.graphql      ← Application queries
│   ├── mutations.graphql    ← Application mutations
│   └── subscriptions.graphql ← Application subscriptions
│
├── root/
│   ├── query.graphql        ← type Query { _empty: String }
│   ├── mutation.graphql     ← type Mutation { _empty: String }
│   └── subscription.graphql ← type Subscription { _empty: String }
│
└── appsync.graphql          ← GENERATED (DO NOT EDIT)

🚀 Usage

For CDK/AppSync Consumers

import { APPSYNC_SCHEMA_PATH } from 'nest-ql-schema';
import * as appsync from 'aws-cdk-lib/aws-appsync';

new appsync.GraphqlApi(this, 'Api', {
  schema: appsync.SchemaFile.fromAsset(APPSYNC_SCHEMA_PATH),
});

For Type Definitions

import { 
  Property, 
  CreatePropertyInput,
  Resolvers 
} from 'nest-ql-schema';

🛠 Development

# Build merged schema from modules
npm run schema:build

# Validate merged schema
npm run schema:validate

# Generate TypeScript types
npm run codegen  

# Full build (merge + validate + codegen)
npm run build

# Publish (fails if schema invalid)
npm publish

✅ Modular Schema Rules

1. Root types: Use extend type Query/Mutation/Subscription in domain files
2. Domain separation: Each domain owns its types, inputs, queries, mutations
3. No duplicates: GraphQL prevents duplicate type names automatically
4. Single source: Only appsync.graphql is consumed by CDK

🔄 Build Process

1. Merge: Combine all schemas/**/*.graphql files (except generated ones)
2. Validate: Ensure merged schema is valid GraphQL
3. Generate: Create appsync.graphql with header
4. Codegen: Generate TypeScript types from merged schema
5. Package: Copy schemas and generated files to dist/

⚡ What This Prevents

❌ Before: Monolithic schema, merge conflicts, unclear ownership
✅ After: Clean domain separation, no conflicts, clear ownership

❌ Before: Invalid schema deployed to AppSync → runtime failure
✅ After: Invalid schema rejected at build time → no broken deployments

The package now guarantees modular development with deployment safety.