Serverless Patterns Workshop - Complete Microservices Architecture

A comprehensive serverless application demonstrating advanced patterns including user management, order processing, Lambda layers, idempotency, structured logging, and custom metrics using AWS Lambda, API Gateway, DynamoDB, and Cognito.

Services Overview

1. Users Service

User management and JWT-based authentication system.

2. Orders Service

Order processing system with advanced serverless patterns including:

• Lambda Layers for code reuse
• Idempotency with Powertools
• Structured Logging with context
• Custom Metrics for observability
• Business Rules enforcement

Architecture

Users Service

• API Gateway: REST API with Lambda Token Authorizer and CloudWatch logging
• Lambda Functions: User operations and JWT authorization with X-Ray tracing
• DynamoDB: User data storage with pay-per-request billing
• Cognito User Pool: Authentication and user management
• CloudWatch: Comprehensive monitoring with alarms and dashboard
• SNS: Alert notifications for system issues

Orders Service

• API Gateway: REST API with Cognito JWT authorization
• Lambda Functions: Order operations with shared utilities layer
• Lambda Layers: Shared code for order retrieval across functions
• DynamoDB: Order storage with composite keys and idempotency table
• Powertools: Idempotency, structured logging, and custom metrics
• CloudWatch: EMF metrics and structured JSON logs

Resources

Users Service

• UsersTable: DynamoDB table with userid partition key
• UsersFunction: CRUD operations handler (Python 3.10)
• AuthorizerFunction: JWT validation and policy generation
• RestAPI: API Gateway with token authorizer
• UserPool: Cognito authentication with email-based usernames

Orders Service

• OrdersTable: DynamoDB table with composite key (userId + orderId)
• IdempotencyTable: DynamoDB table for idempotency tracking with TTL
• PyUtils Layer: Shared utilities for order operations
• AddOrderFunction: Create orders with idempotency protection
• GetOrderFunction: Retrieve individual orders
• ListOrdersFunction: List all orders for authenticated user
• EditOrderFunction: Update orders with conditional checks
• CancelOrderFunction: Cancel orders with business rule validation

Monitoring & Observability

• CloudWatch Alarms: Error and throttling detection
• SNS Topic: Alert notifications
• Dashboard: Real-time metrics visualization
• Custom Metrics: SuccessfulOrder and OrderTotal metrics
• Structured Logs: JSON logs with Lambda context
• Access Logs: API Gateway request logging (30-day retention)

API Endpoints

Users Service

Method	Path	Description	Authorization
GET	/users	List all users	Admin only
POST	/users	Create new user	Admin only
GET	/users/{userid}	Get specific user	Owner or Admin
PUT	/users/{userid}	Update user	Owner or Admin
DELETE	/users/{userid}	Delete user	Owner or Admin

Orders Service

Method	Path	Description	Business Rules
POST	/orders	Create new order	Idempotent by orderId
GET	/orders	List user orders	User isolation
GET	/orders/{orderId}	Get specific order	Owner access only
PUT	/orders/{orderId}	Update order	PLACED status only
DELETE	/orders/{orderId}	Cancel order	PLACED + <10 minutes

Parameters

Parameter	Description	Default
UserPoolAdminGroupName	User pool group name for API administrators	apiAdmins

Quick Start

1. Deploy Users Service

cd users
sam build
sam deploy --guided

2. Deploy Orders Service

cd ../orders
sam build
sam deploy --guided

3. Create Admin User

# Get outputs from deployment
USER_POOL_ID=$(aws cloudformation describe-stacks --stack-name <stack-name> --query 'Stacks[0].Outputs[?OutputKey==`UserPool`].OutputValue' --output text)
CLIENT_ID=$(aws cloudformation describe-stacks --stack-name <stack-name> --query 'Stacks[0].Outputs[?OutputKey==`UserPoolClient`].OutputValue' --output text)

# Create admin user
aws cognito-idp admin-create-user \
  --user-pool-id $USER_POOL_ID \
  --username admin@example.com \
  --user-attributes Name=email,Value=admin@example.com \
  --temporary-password TempPass123! \
  --message-action SUPPRESS

# Add to admin group
aws cognito-idp admin-add-user-to-group \
  --user-pool-id $USER_POOL_ID \
  --username admin@example.com \
  --group-name apiAdmins

# Set permanent password
aws cognito-idp admin-set-user-password \
  --user-pool-id $USER_POOL_ID \
  --username admin@example.com \
  --password SecurePass123! \
  --permanent

4. Test APIs

# Get JWT token
TOKEN=$(aws cognito-idp initiate-auth \
  --auth-flow USER_PASSWORD_AUTH \
  --client-id $CLIENT_ID \
  --auth-parameters USERNAME=admin@example.com,PASSWORD=SecurePass123! \
  --query 'AuthenticationResult.IdToken' \
  --output text)

# Test API call
API_URL=$(aws cloudformation describe-stacks --stack-name <stack-name> --query 'Stacks[0].Outputs[?OutputKey==`APIEndpoint`].OutputValue' --output text)
curl -H "Authorization: Bearer $TOKEN" $API_URL/users

5. Test Orders Service

# Set environment variables for testing
export USERS_STACK_NAME=<users-stack-name>
export ORDERS_STACK_NAME=<orders-stack-name>

# Run orders integration tests
cd orders
pytest tests/integration -v

Serverless Patterns Implemented

1. Lambda Layers

• Shared Code: PyUtils layer with get_order() function
• Code Reuse: Used across Get, Edit, and Cancel operations
• Maintainability: Single source of truth for common operations

2. Idempotency

• Powertools Integration: AWS Lambda Powertools for Python
• Duplicate Protection: Prevents duplicate order creation
• TTL Management: Automatic cleanup of idempotency records
• Event Key: Based on orderId from request body

3. Structured Logging

• JSON Format: Structured logs with Lambda context
• Correlation: X-Ray trace ID integration
• Debugging: Order details and operation context
• Performance: Cold start detection and function metrics

4. Custom Metrics

• Business Metrics: SuccessfulOrder count and OrderTotal sum
• EMF Format: CloudWatch Embedded Metric Format
• Dashboards: Real-time visualization capabilities
• Alerting: Custom alarms on business KPIs

5. Business Rules Enforcement

• Order Lifecycle: PLACED → ACKNOWLEDGED → CANCELED states
• Time Windows: 10-minute cancellation window
• Conditional Operations: DynamoDB condition expressions
• Data Integrity: Atomic operations and consistency

Outputs

• APIEndpoint: API Gateway URL
• UserPool: Cognito User Pool ID
• UserPoolClient: Cognito Client ID
• CognitoLoginURL: Hosted UI login URL
• CognitoAuthCommand: CLI authentication command
• AlarmsTopic: SNS topic for alerts
• DashboardURL: CloudWatch dashboard URL

Security Features

• JWT signature validation with Cognito JWKS
• Role-based access control (regular users vs admins)
• Token expiration and audience validation
• API Gateway request validation
• Lambda function isolation with least privilege IAM

Monitoring & Alerts

CloudWatch Alarms

• API Gateway 5XX errors
• Lambda function errors and throttling
• Automatic SNS notifications

Dashboard Metrics

• API Gateway: Request count, latency, errors
• Lambda: Invocations, duration, concurrent executions
• Real-time performance monitoring

Documentation

Detailed documentation available in /docs:

• API Documentation
• Deployment Guide
• Architecture Overview
• Testing Guide

Testing

Users Service

cd users
# Install test dependencies
pip install -r tests/requirements.txt

# Run unit tests
pytest tests/unit/ -v

# Run integration tests
pytest tests/integration/ -v

Orders Service

cd orders
# Install test dependencies
pip install -r tests/requirements.txt

# Run integration tests (8 total)
pytest tests/integration -v

# Generate metrics data
cmd="pytest tests/integration -v"; for i in $(seq 10); do $cmd; sleep 15; done

Integration Test Coverage

1. Authentication: Unauthorized access validation
2. Order Creation: Basic order placement with idempotency
3. Order Retrieval: Individual order lookup
4. Order Modification: Update existing orders
5. Order Cancellation: Business rule validation
6. Error Handling: Invalid state transitions
7. Idempotency: Duplicate request protection
8. List Operations: User order enumeration