AppSync Users API - Development & Deployment Guide

This project is an AWS AppSync GraphQL API for managing users with DynamoDB as the data store. This guide shows you how to run everything locally for development and deploy to AWS for production.

Prerequisites

• Node.js 18+ and npm
• AWS CLI configured (for deployment)
• AWS CDK CLI: npm install -g aws-cdk

🚀 Quick Start

Local Development

# 1. Setup everything (install deps + build)
npm run setup
# 2. Start local development environment 
npm run dev

What this gives you:

• 🗄️ Local DynamoDB on port 8999
• 🚀 GraphQL API on port 4000 with interactive playground
• 🖥️ Database Admin UI on port 8010

Access your services:

• GraphQL Playground: http://localhost:4000/graphql
• Database Admin: http://localhost:8010

AWS Deployment

# 1. Setup everything (install deps + build)
npm run setup

# 2. Deploy to AWS
npm run deploy

What this creates:

• 🌐 AppSync GraphQL API with API Key authentication
• 🗄️ DynamoDB Table with Global Secondary Index
• ⚡ Lambda Function (ARM64, Node.js 20.x)
• 📊 CloudWatch Logging and X-Ray tracing

Project Structure

appsync-assessment/
├── package.json              # Root dependencies and scripts
├── tsconfig.json            # Root TypeScript config
├── appSync/
│   └── schema.graphql       # GraphQL schema definition
├── infra/                   # AWS CDK infrastructure
│   ├── package.json         # CDK dependencies
│   ├── tsconfig.json        # CDK TypeScript config
│   ├── bin/app.ts           # CDK app entry point
│   └── lib/stack.ts         # CDK stack definition
└── lambda/                  # Lambda function code
    ├── package.json         # Lambda dependencies
    ├── tsconfig.json        # Lambda TypeScript config
    ├── .env.example         # Environment variables template
    └── src/
        ├── handler.ts           # Lambda handler (entry point)
        ├── types/
        │   └── user.types.ts    # TypeScript type definitions
        ├── database/
        │   └── database.context.ts  # Database connection management
        ├── repositories/
        │   └── user.repository.ts   # Data access layer
        ├── services/
        │   └── user.service.ts      # Business logic layer
        └── manager/
            └── service.manager.ts # Dependency injection

Environment Configuration

The project uses environment variables for configuration. Environment files are included:

• .env - Local development configuration (automatically loaded)
• .env.example - Template for production environment variables
• lambda/.env - Lambda-specific environment variables

Environment Variables

Variable	Description	Local Value	Production Value
DDB_LOCAL	Use local DynamoDB	1	0 or unset
TABLE_NAME	DynamoDB table name	UsersTable	Set by CDK
GSI1_NAME	Global Secondary Index name	GSI1	GSI1
AWS_REGION	AWS region	us-east-1	Your AWS region
DYNAMO_ENDPOINT	DynamoDB endpoint	http://localhost:8999	Unset
AWS_ACCESS_KEY_ID	AWS access key	dummy	Your AWS access key
AWS_SECRET_ACCESS_KEY	AWS secret key	dummy	Your AWS secret key
PORT	Server port	4000	As needed
DDB_PORT	DynamoDB local port	8999	N/A
DDB_ADMIN_PORT	DynamoDB admin port	8010	N/A

Process Management

Auto-cleanup: All local processes are automatically terminated when you close the terminal or press Ctrl+C.

Manual cleanup:

# Stop all local development services
npm run stop
# or
npm run clean

# Destroy AWS resources
npm run destroy

GraphQL Schema

The API supports these operations:

Mutations

mutation CreateUser {
  createUser(input: {
    name: "Jane Smith"
    email: "jane@example.com"
    status: ACTIVE
  }) {
    userId
    name
    email
    status
    createdAt
  }
}

Queries

# Get all users
query GetUsers {
  getUsers {
    items {
      userId
      name
      email
      status
      createdAt
    }
    nextToken
  }
}

# Search users
query SearchUsers {
  getUsers(search: "john", status: ACTIVE, limit: 5) {
    items {
      userId
      name
      email
      status
      createdAt
    }
  }
}

# Filter by date range
query GetUsersByDate {
  getUsers(
    dateFrom: "2024-01-01T00:00:00Z"
    dateTo: "2024-12-31T23:59:59Z"
  ) {
    items {
      userId
      name
      email
      status
      createdAt
    }
  }
}

Available Scripts

Command	Description
npm run setup	Install all dependencies and build everything
npm run build	Build lambda and infrastructure
npm run dev	Start complete local development environment
npm run deploy	Deploy to AWS (creates all resources)
npm run destroy	Destroy AWS resources (cleanup)
npm run stop	Stop all local development services
npm run clean	Alternative local cleanup command
npm run lambda:test	Test the Lambda function locally
npm run status	Check status of local services
npm run dev:db	Start local DynamoDB on port 8999 (manual)
npm run dev:admin	Start DynamoDB admin interface on port 8010 (manual)

🌐 AWS Deployment

Prerequisites for AWS Deployment

# 1. Install AWS CLI (if not already installed)
# macOS: brew install awscli
# Windows: choco install awscli
# Linux: sudo apt install awscli

# 2. Configure AWS credentials
aws configure
# Enter your:
# - AWS Access Key ID
# - AWS Secret Access Key  
# - Default region (e.g., us-east-1)
# - Default output format (json)

# 3. Install CDK globally (if not already installed)
npm install -g aws-cdk

# 4. Bootstrap CDK (first time only per region/account)
cdk bootstrap

Simple AWS Deployment

# 1. Setup everything (install deps + build)
npm run setup

# 2. Deploy to AWS
npm run deploy

Manual AWS Deployment Steps

# Build everything first
npm run build

# Deploy using CDK
cd infra
npm run deploy

# Or use CDK directly
cdk deploy

Additional AWS Commands

# Preview changes before deployment
cd infra && cdk diff

# View generated CloudFormation template  
cd infra && cdk synth

# Destroy all AWS resources (cleanup)
npm run destroy
# or
cd infra && cdk destroy