Lambda Functions Deployment Guide

Overview

This guide covers building and deploying Lambda functions for the Momentum backend API.

Lambda Functions

The project includes three Lambda functions:

1. courses-handler - Course management operations (CRUD)
2. lessons-handler - Lesson management operations (CRUD)
3. enrollments-handler - Enrollment and progress tracking

Building Lambda Functions

Build All Functions

npm run build:lambda

This will:

• Clean previous builds
• Install dependencies
• Compile TypeScript
• Create deployment packages (dist/index.zip)

Build Specific Function

npm run build:lambda courses
npm run build:lambda lessons
npm run build:lambda enrollments

Deployment

Deploy Infrastructure (includes Lambda build)

npm run deploy:infrastructure

This script automatically:

1. Builds all Lambda functions
2. Runs terraform plan
3. Deploys infrastructure with terraform apply

Manual Terraform Deployment

If running Terraform manually:

# 1. Build Lambda functions first
npm run build:lambda

# 2. Then run Terraform
cd infrastructure/terraform
terraform init
terraform plan
terraform apply

File Structure

backend/functions/
├── courses/
│   ├── src/
│   │   └── index.ts          # Handler code
│   ├── dist/
│   │   └── index.zip         # Deployment package
│   ├── package.json
│   └── tsconfig.json
├── lessons/
│   ├── src/
│   │   └── index.ts
│   ├── dist/
│   │   └── index.zip
│   ├── package.json
│   └── tsconfig.json
├── enrollments/
│   ├── src/
│   │   └── index.ts
│   ├── dist/
│   │   └── index.zip
│   ├── package.json
│   └── tsconfig.json
└── shared/                   # Shared utilities and repositories
    ├── types/
    ├── utils/
    └── repositories/

TypeScript Configuration

Each Lambda function extends the shared tsconfig.json:

{
  "extends": "../../shared/tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "../../"
  },
  "include": [
    "src/**/*.ts",
    "../../shared/**/*.ts"
  ]
}

Important: The rootDir is set to ../../ to include shared code from outside the function directory.

Package Scripts

Each Lambda function has these npm scripts:

• build - Compile TypeScript and create ZIP
• package - Create deployment ZIP from compiled code
• clean - Remove dist directory

Shared Code

All Lambda functions share common utilities:

• Database utilities (backend/shared/utils/database.ts)
  • Connection pooling
  • Query execution
  • Transaction management
• Secrets management (backend/shared/utils/secrets.ts)
  • AWS Secrets Manager integration
  • Database credential retrieval
• Repositories (backend/shared/repositories/)
  • BaseRepository with common CRUD operations
  • CourseRepository
  • EnrollmentRepository

Deployment Package

The deployment ZIP includes:

• Compiled JavaScript files (from src/)
• Compiled shared code (from ../../shared/)
• node_modules/ with production dependencies

Environment Variables

Lambda functions receive these environment variables from Terraform:

NODE_ENV=development|staging|production
DB_SECRET_ARN=arn:aws:secretsmanager:...
DB_CLUSTER_ARN=arn:aws:rds:...
DB_NAME=momentum
REDIS_SECRET_ARN=arn:aws:secretsmanager:...
AWS_NODEJS_CONNECTION_REUSE_ENABLED=1

Troubleshooting

Build Errors

Issue: TypeScript compilation errors

# Clean and rebuild
npm run build:lambda

Issue: rootDir errors with shared files

✅ Solution: Already fixed - rootDir is set to ../../ to include shared code

Terraform Errors

Issue: “ZIP file not found”

# Build Lambda functions first
npm run build:lambda

# Then run Terraform
cd infrastructure/terraform
terraform apply

Issue: “File size too large”

If ZIP files exceed Lambda limits (50MB zipped, 250MB unzipped):

• Review dependencies in package.json
• Consider using Lambda Layers for shared code
• Remove unnecessary dev dependencies

Testing Lambda Locally

Test Lambda functions locally before deployment:

# Start local database
npm run docker:up

# Set local environment variables
export NODE_ENV=development
export DATABASE_URL=postgresql://dbadmin:localdev123@localhost:5432/momentum

# Run tests (when implemented)
cd backend/functions/courses
npm test

Next Steps

After deploying Lambda functions:

1. Test API endpoints:

   curl https://your-api-gateway-url/dev/courses
   

2. Monitor CloudWatch Logs:
   • AWS Console → CloudWatch → Log Groups
   • /aws/lambda/momentum-courses-dev
   • /aws/lambda/momentum-lessons-dev
   • /aws/lambda/momentum-enrollments-dev
3. Set up CI/CD:
   • GitHub Actions workflow for automated builds
   • Deploy on push to main branch

Best Practices

1. Always build before deploying

   npm run build:lambda && npm run deploy:infrastructure
   

2. Test locally first
   • Use local database (Docker)
   • Test with sample data
   • Verify business logic
3. Monitor after deployment
   • Check CloudWatch Logs
   • Monitor Lambda metrics
   • Set up alarms for errors
4. Keep packages updated

   cd backend/functions/courses
   npm outdated
   npm update
   

Related Documentation

• Technical Architecture
• Local Development
• Infrastructure Deployment

---

Last Updated: 2025-11-15