serverless.yml (Alternative to CDK for rapid prototyping)

s backend requires shifting from endpoint-centric routing to domain-boundary function design, externalizing state, and enforcing strict execution contracts. The following implementation uses TypeScript, AWS Lambda, API Gateway, DynamoDB, and AWS CDK v2 for infrastructure definition.

Step 1: Define Execution Boundaries by Domain Capability

Functions should encapsulate business capabilities, not HTTP endpoints. Grouping related operations under a single function reduces deployment surface area, minimizes cold starts, and simplifies IAM policy management.

// src/handlers/orderProcessor.ts
import { APIGatewayProxyHandlerV2 } from 'aws-lambda';
import { OrderService } from '../services/order.service';
import { validatePayload } from '../utils/validation';
import { createResponse } from '../utils/response';

export const handler: APIGatewayProxyHandlerV2 = async (event) => {
  if (!event.body) return createResponse(400, { error: 'Missing payload' });
  
  const payload = validatePayload(JSON.parse(event.body));
  const orderService = new OrderService();
  
  try {
    const result = await orderService.processOrder(payload);
    return createResponse(201, result);
  } catch (err) {
    return createResponse(500, { error: 'Processing failed', trace: process.env.NODE_ENV === 'production' ? undefined : err });
  }
};

Step 2: Externalize State and Manage Connections

Serverless functions are ephemeral. Never maintain in-memory state across invocations. For database connections, use connection pooling alternatives: DynamoDB SDK v3 handles connection reuse internally, but for relational databases, route through a proxy like RDS Proxy or use a managed serverless data API.

// src/services/order.service.ts
import { DynamoDBClient, PutItemCommand } from '@aws-sdk/client-dynamodb';
import { marshall } from '@aws-sdk/util-dynamodb';

const client = new DynamoDBClient({ region: process.env.AWS_REGION });

export class OrderService {
  async processOrder(payload: any) {
    const orderId = crypto.randomUUID();
    const item = marshall({
      orderId,
      status: 'PENDING',
      items: payload.items,
      createdAt: new Date().toISOString(),
    });

    await client.send(new PutItemCommand({
      TableName: process.env.ORDERS_TABLE!,
      Item: item,
      ConditionExpression: 'attribute_not_exists(orderId)',
    }));

    return { orderId, status: 'PENDING' };
  }
}

Step 3: Configure Infrastructure as Code

Use CDK v2 to define infrastructure declaratively. This enables version control, drift detection, and environment parity.

// lib/stack.ts
import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apig from 'aws-cdk-lib/aws-apigatewayv2';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const ordersTable = new dynamodb.Table(this, 'OrdersTable', {
      partitionKey: { name: 'orderId', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      encryption: dynamodb.TableEncryption.AWS_MANAGED,
    });

    const orderFunction = new lambda.Function(this, 'OrderProcessor', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'src/handlers/orderProcessor.handler',
      code: lambda.Code.fromAsset('dist'),
      environment: {
        ORDERS_TABLE: ordersTable.tableName,
        NODE_OPTIONS: '--enable-source-maps',
      },
      memorySize: 512,
      timeout: cdk.Duration.seconds(10),
      tracing: lambda.Tracing.ACTIVE,
    });

    ordersTable.grantReadWriteData(orderFunction);

    const api = new apig.HttpApi(this, 'OrdersApi');
    api.addRoutes({
      path: '/orders',
      methods: [apig.HttpMethod.POST],
      integration: new apig.LambdaProxyIntegration({ handler: orderFunction }),
    });

    new cdk.CfnOutput(this, 'ApiEndpoint', { value: api.apiEndpoint });
  }
}

Architecture Rationale

• Function-per-domain reduces deployment complexity and aligns with domain-driven design boundaries.
• SDK v3 + DynamoDB eliminates connection pooling overhead and scales automatically with request volume.
• CDK v2 provides type-safe infrastructure definition, enabling compile-time validation and consistent CI/CD pipelines.
• Explicit timeout/memory configuration prevents runaway costs and ensures predictable scaling behavior.

Pitfall Guide

1. Monolithic Function Bundling

Packaging entire frameworks (Express, NestJS) into a single Lambda function inflates deployment size, triggers cold starts, and obscures failure boundaries. Functions should be scoped to single business operations. Use lightweight routers or API Gateway path routing instead.

2. Synchronous Database Connections Per Invocation

Opening a new connection on every invocation exhausts database limits and adds 200–800ms latency. DynamoDB SDK v3 manages connections internally. For relational databases, use RDS Proxy, Supavisor, or PgBouncer in serverless mode. Never store connections in global scope without lifecycle management.

3. Ignoring Idempotency and Retry Semantics

Serverless platforms guarantee at-least-once delivery for event sources (SQS, DynamoDB Streams, EventBridge). Handlers must be idempotent. Implement idempotency keys, deduplication tables, or conditional writes. Never assume single execution.

4. Over-Reliance on API Gateway for Business Logic

API Gateway is a routing and throttling layer, not a compute engine. Validating payloads, transforming data, or calling multiple downstream services inside Gateway mapping templates creates brittle, untestable infrastructure. Keep Gateway thin; push logic into functions or dedicated microservices.

5. Inadequate Observability Across Async Boundaries

Distributed tracing breaks when context isn't propagated across SQS, SNS, or Step Functions. Use AWS X-Ray or OpenTelemetry with context injection. Ensure correlation IDs flow through event payloads. Log structured JSON with request IDs, not console.log.

6. Cost Blindness at Scale

On-demand pricing is economical for bursty traffic but expensive for sustained load. Failing to evaluate provisioned concurrency, data transfer costs, or API Gateway request pricing leads to budget overruns. Implement cost allocation tags, set budget alerts, and benchmark p95 execution duration vs provisioned concurrency thresholds.

7. Vendor Lock-In Without Abstraction

Tightly coupling to AWS SDK specifics, proprietary IAM roles, or CloudFormation-specific resources makes migration impossible. Abstract infrastructure dependencies, use standard event formats (CloudEvents), and isolate provider-specific code behind interfaces. Maintain a deployment abstraction layer.

Production Bundle

Action Checklist

• Scope functions to domain capabilities, not HTTP endpoints
• Externalize all state; use managed data services with automatic connection handling
• Implement idempotency keys and conditional writes for all mutation operations
• Configure explicit timeout, memory, and concurrency limits per function
• Inject correlation IDs into event payloads and enable distributed tracing
• Set up cost allocation tags, budget alerts, and p95 latency monitoring
• Abstract provider-specific SDK calls behind interfaces for migration readiness

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Bursty API traffic (0–10k req/min)	On-demand Lambda + API Gateway	Pay-per-ms model matches unpredictable load	Low (zero idle cost)
Sustained high throughput (>50k req/min)	Provisioned Concurrency or Fargate	Avoids cold start tax and scaling lag	Medium-High (reserved capacity premium)
Real-time data processing streams	Lambda + DynamoDB Streams	Native integration, automatic batching, retry handling	Low-Medium (stream read costs)
Long-running jobs (>15s)	Step Functions + ECS/SQS	Lambda timeout limit; orchestration handles retries/state	Medium (state machine execution costs)
Multi-region active-active	Global Accelerator + regional Lambdas	Latency routing, regional isolation, failover	High (cross-region data transfer)

Configuration Template

# serverless.yml (Alternative to CDK for rapid prototyping)
service: serverless-backend
frameworkVersion: '3'

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1
  environment:
    NODE_OPTIONS: '--enable-source-maps'
    ORDERS_TABLE: ${self:service}-orders-${sls:stage}
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - dynamodb:PutItem
            - dynamodb:GetItem
            - dynamodb:UpdateItem
          Resource: arn:aws:dynamodb:${self:provider.region}:*:table/${self:provider.environment.ORDERS_TABLE}

functions:
  processOrder:
    handler: src/handlers/orderProcessor.handler
    events:
      - httpApi:
          path: /orders
          method: post
    memorySize: 512
    timeout: 10
    tracing: active

resources:
  Resources:
    OrdersTable:
      Type: AWS::DynamoDB::Table
      Properties:
        TableName: ${self:provider.environment.ORDERS_TABLE}
        AttributeDefinitions:
          - AttributeName: orderId
            AttributeType: S
        KeySchema:
          - AttributeName: orderId
            KeyType: HASH
        BillingMode: PAY_PER_REQUEST
        SSESpecification:
          SSEEnabled: true

Quick Start Guide

1. Initialize project: Run npm init -y && npm install aws-cdk-lib constructs @aws-sdk/client-dynamodb @types/aws-lambda typescript ts-node. Create tsconfig.json with module: commonjs, target: es2020, strict: true.
2. Define stack: Copy the CDK lib/stack.ts code into your project. Run npx cdk bootstrap in your AWS account, then npx cdk deploy to provision API Gateway, Lambda, and DynamoDB.
3. Build and deploy: Compile TypeScript with npx tsc, copy assets to dist/, and run npx cdk deploy --hotswap for rapid iteration. Test the endpoint with curl -X POST <api-endpoint>/orders -d '{"items":[{"id":"sku-1","qty":2}]}' -H 'Content-Type: application/json'.
4. Verify observability: Open AWS CloudWatch Logs, confirm structured JSON output, and validate X-Ray traces show the full request path from API Gateway through Lambda to DynamoDB.