aws-serverless-eda – DevOps & Infrastructure skill for AI agents

AWS Serverless & Event-Driven Architecture

This skill provides comprehensive guidance for building serverless applications and event-driven architectures on AWS based on Well-Architected Framework principles.

AWS Documentation Requirement

Verify changeable AWS facts with available official documentation tools or primary AWS documentation. Dependencies are not automatically loaded by this Markdown skill; do not install MCP servers as a prerequisite for answering.

Serverless MCP Servers

This skill leverages the CDK MCP server (provided via aws-cdk-development dependency) and AWS Documentation MCP for serverless guidance.

> Note: The following AWS MCP servers are available separately via the Full AWS MCP Server (see aws-mcp-setup skill) and are not bundled with this plugin:

> - AWS Serverless MCP — SAM CLI lifecycle (init, deploy, local test)

> - AWS Lambda Tool MCP — Direct Lambda invocation

> - AWS Step Functions MCP — Workflow orchestration

> - Amazon SNS/SQS MCP — Messaging and queue management

When to Use This Skill

Use this skill when:

• Building serverless applications with Lambda
• Designing event-driven architectures
• Implementing microservices patterns
• Creating asynchronous processing workflows
• Orchestrating multi-service transactions
• Building real-time data processing pipelines
• Implementing saga patterns for distributed transactions
• Designing for scale and resilience

AWS Well-Architected Serverless Design Principles

1. Speedy, Simple, Singular

Functions should be concise and single-purpose

// ✅ GOOD - Single purpose, focused function
export const processOrder = async (event: OrderEvent) => {
  // Only handles order processing
  const order = await validateOrder(event);
  await saveOrder(order);
  await publishOrderCreatedEvent(order);
  return { statusCode: 200, body: JSON.stringify({ orderId: order.id }) };
};

// ❌ BAD - Function does too much
export const handleEverything = async (event: any) => {
  // Handles orders, inventory, payments, shipping...
  // Too many responsibilities
};

Keep functions environmentally efficient and cost-aware:

• Minimize cold start times
• Optimize memory allocation
• Use provisioned concurrency only when needed
• Leverage connection reuse

2. Think Concurrent Requests, Not Total Requests

Design for concurrency, not volume

Lambda scales horizontally - design considerations should focus on:

• Concurrent execution limits
• Downstream service throttling
• Shared resource contention
• Connection pool sizing

// Consider concurrent Lambda executions accessing DynamoDB
const table = new dynamodb.Table(this, 'Table', {
  billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, // Auto-scales with load
});

// Or with provisioned capacity + auto-scaling
const table = new dynamodb.Table(this, 'Table', {
  billingMode: dynamodb.BillingMode.PROVISIONED,
  readCapacity: 5,
  writeCapacity: 5,
});

// Enable auto-scaling for concurrent load
table.autoScaleReadCapacity({ minCapacity: 5, maxCapacity: 100 });
table.autoScaleWriteCapacity({ minCapacity: 5, maxCapacity: 100 });

3. Share Nothing

Function runtime environments are short-lived

// ❌ BAD - Relying on local file system
export const handler = async (event: any) => {
  fs.writeFileSync('/tmp/data.json', JSON.stringify(data)); // Lost after execution
};

// ✅ GOOD - Use persistent storage
export const handler = async (event: any) => {
  await s3.putObject({
    Bucket: process.env.BUCKET_NAME,
    Key: 'data.json',
    Body: JSON.stringify(data),
  });
};

State management:

• Use DynamoDB for persistent state
• Use Step Functions for workflow state
• Use ElastiCache for session state
• Use S3 for file storage

4. Assume No Hardware Affinity

Applications must be hardware-agnostic

Infrastructure can change without notice:

• Lambda functions can run on different hardware
• Container instances can be replaced
• No assumption about underlying infrastructure

Design for portability:

• Use environment variables for configuration
• Avoid hardware-specific optimizations
• Test across different environments

5. Orchestrate with State Machines, Not Function Chaining

Use Step Functions for orchestration

// ❌ BAD - Lambda function chaining
export const handler1 = async (event: any) => {
  const result = await processStep1(event);
  await lambda.invoke({
    FunctionName: 'handler2',
    Payload: JSON.stringify(result),
  });
};

// ✅ GOOD - Step Functions orchestration
const stateMachine = new stepfunctions.StateMachine(this, 'OrderWorkflow', {
  definition: stepfunctions.Chain
    .start(validateOrder)
    .next(processPayment)
    .next(shipOrder)
    .next(sendConfirmation),
});

Benefits of Step Functions:

• Visual workflow representation
• Built-in error handling and retries
• Execution history and debugging
• Parallel and sequential execution
• Service integrations without code

6. Use Events to Trigger Transactions

Event-driven over synchronous request/response

// Pattern: Event-driven processing
const bucket = new s3.Bucket(this, 'DataBucket');

bucket.addEventNotification(
  s3.EventType.OBJECT_CREATED,
  new s3n.LambdaDestination(processFunction),
  { prefix: 'uploads/' }
);

// Pattern: EventBridge integration
const rule = new events.Rule(this, 'OrderRule', {
  eventPattern: {
    source: ['orders'],
    detailType: ['OrderPlaced'],
  },
});

rule.addTarget(new targets.LambdaFunction(processOrderFunction));

Benefits:

• Loose coupling between services
• Asynchronous processing
• Better fault tolerance
• Independent scaling

7. Design for Failures and Duplicates

Operations must be idempotent

// INCOMPLETE sketch: this check/process/write sequence races on concurrent
// deliveries and repeats side effects if the process crashes before recording completion.
export const handler = async (event: SQSEvent) => {
  for (const record of event.Records) {
    const orderId = JSON.parse(record.body).orderId;

    // Check if already processed (idempotency)
    const existing = await dynamodb.getItem({
      TableName: process.env.TABLE_NAME,
      Key: { orderId },
    });

    if (existing.Item) {
      console.log('Order already processed:', orderId);
      continue; // Skip duplicate
    }

    // Process order
    await processOrder(orderId);

    // Mark as processed
    await dynamodb.putItem({
      TableName: process.env.TABLE_NAME,
      Item: { orderId, processedAt: Date.now() },
    });
  }
};

Use atomic conditional acquisition, explicit in-progress/completed state and expiry, plus provider-side idempotency/reconciliation for external effects. See [AWS Powertools idempotency](https://docs.aws.amazon.com/powertools/typescript/latest/features/idempotency/). A pre-read followed by put is not duplicate protection.

Illustrative retry loop for replay-safe transient operations only:

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
  throw new Error('Max retries exceeded');
}

Architecture Patterns

For detailed implementation patterns with full code examples, see the reference documentation:

Event-Driven Architecture Patterns

File: references/eda-patterns.md

• Event Router with EventBridge (custom event bus, schema registry, rule-based routing)
• Queue-Based Processing with SQS (standard/FIFO, DLQ, Lambda consumers)
• Pub/Sub Fan-Out with SNS + SQS (multi-consumer, filtering)
• Saga Pattern with Step Functions (distributed transactions, compensating actions)
• Event Sourcing with DynamoDB Streams (append-only event store, projections)

Serverless Architecture Patterns

File: references/serverless-patterns.md

• API-Driven Microservices (REST API + Lambda backend)
• Stream Processing with Kinesis (real-time, batch windowing, bisect on error)
• Async Task Processing with SQS (background jobs, concurrency control)
• Scheduled Jobs with EventBridge (cron/rate schedules)
• Webhook Processing (signature validation, async queue forwarding)

> Important: When using CDK code examples from references, avoid hardcoding resource names (e.g., restApiName, eventBusName). Let CDK generate unique names automatically to enable reusability and parallel deployments. See aws-cdk-development skill for details.

Best Practices

Error Handling

Implement comprehensive error handling:

export const handler = async (event: SQSEvent) => {
  const failures: SQSBatchItemFailure[] = [];

  for (const record of event.Records) {
    try {
      await processRecord(record);
    } catch (error) {
      console.error('Fai

… (full content is in the download package)