vybekiit 0.7.0 → 0.7.2

package/dist/global-skills/aws-serverless/references/production.md

@@ -1,13 +1,15 @@
 # Production-Ready Serverless on AWS
 
-Pre-deployment checklist, architecture trade-offs, and operational patterns. Concise on purpose — the value here is the structured checklist and opinionated defaults, not API syntax.
+Quick-reference for shipping Lambda workloads to production. Covers the pre-deployment checklist, architecture trade-offs, and operational patterns for production traffic.
 
 ## Contents
 
 - [Production readiness checklist](#production-readiness-checklist)
 - [Architecture decisions](#architecture-decisions)
 - [Observability](#observability)
-- [Idempotency](#idempotency)
+- [Security hardening](#security-hardening)
+- [Testing strategies](#testing-strategies)
+- [Idempotency patterns](#idempotency-patterns)
 - [Response streaming](#response-streaming)
 - [Anti-patterns](#anti-patterns)
 
@@ -15,134 +17,365 @@ Pre-deployment checklist, architecture trade-offs, and operational patterns. Con
 
 ## Production readiness checklist
 
+Walk through every item before the first production deployment.
+
 ### Compute
 
-- [ ] Memory right-sized (Power Tuning / load test)
-- [ ] Timeout set explicitly (P99 + buffer — never the 3s default)
-- [ ] Reserved concurrency set to protect downstream
-- [ ] DLQ / on-failure destination on every async invocation and ESM
-- [ ] Config via env vars; SDK clients initialized outside the handler
-- [ ] Deployment package minimized (exclude tests, docs, unused deps)
+- [ ] Memory right-sized (use AWS Lambda Power Tuning or load testing)
+- [ ] Timeout set explicitly (P99 + buffer, never the 3 s default)
+- [ ] Reserved concurrency configured to protect downstream systems
+- [ ] Dead-letter queue (DLQ) or on-failure destination for every async invocation
+- [ ] Environment variables for all config (bucket names, table names, endpoints)
+- [ ] Code signing enabled (if compliance requires it)
+- [ ] SDK clients initialized outside handler (reuse across warm invocations)
+- [ ] Deployment package size minimized (exclude tests, docs, unused dependencies)
 
 ### Observability
 
-- [ ] Structured JSON logging (Powertools Logger) + correlation IDs propagated
-- [ ] X-Ray active tracing
-- [ ] Custom metrics via EMF
-- [ ] Alarms on Errors, Throttles, Duration P99, IteratorAge, ConcurrentExecutions, DLQ depth (see below)
-- [ ] Log retention set — **not** unlimited
-- [ ] Log group encryption with customer managed KMS key when compliance requires it
-- [ ] Lambda Insights enabled
+- [ ] Structured JSON logging via Powertools Logger
+- [ ] X-Ray active tracing enabled
+- [ ] Custom metrics emitted via Embedded Metric Format (EMF)
+- [ ] CloudWatch Alarms on Errors, Throttles, Duration P99, IteratorAge, ConcurrentExecutions, DLQ depth
+- [ ] Log retention policy set — do not leave at unlimited
+- [ ] Correlation IDs propagated to downstream services
+- [ ] Lambda Insights enabled for system-level metrics (CPU, memory, network)
 
 ### Security
 
-- [ ] One IAM role per function, scoped to exact resource ARNs
-- [ ] No secrets in env vars — Secrets Manager / SSM (SecureString) with Powertools caching
-- [ ] Input validation at the handler boundary (Zod / Pydantic / Powertools Validation)
-- [ ] VPC only when required (RDS, ElastiCache); VPC endpoints for AWS services
-- [ ] GuardDuty Lambda Protection, Security Hub Lambda controls, Inspector Lambda scanning, CI dependency scanning
+- [ ] One IAM execution role per function, scoped to exact resource ARNs
+- [ ] No secrets in environment variables — use Secrets Manager / SSM with caching
+- [ ] Input validation on every event payload (JSON Schema, Zod, Pydantic)
+- [ ] VPC placement only when required (RDS, ElastiCache); VPC endpoints for AWS services
+- [ ] GuardDuty Lambda Protection enabled
+- [ ] Security Hub Lambda controls enabled
+- [ ] Dependency scanning in CI (`npm audit`, `pip-audit`, Snyk)
+- [ ] Amazon Inspector Lambda scanning enabled
 - [ ] Function URLs use `AWS_IAM` auth (not `NONE`) in production
-- [ ] SQS queues use SSE-KMS for encryption at rest when compliance requires customer managed keys (SSE-SQS is enabled by default)
-- [ ] DynamoDB tables use customer managed KMS keys when compliance requires key control (AWS owned encryption is enabled by default)
-- [ ] Enforce HTTPS-only access with `aws:SecureTransport` condition in resource policies (S3 buckets, SQS queues)
 
 ### Reliability
 
-- [ ] Every handler idempotent
-- [ ] Partial batch failure reporting (SQS, Kinesis, DynamoDB Streams)
-- [ ] `BisectBatchOnFunctionError` for stream sources
-- [ ] Retry config tuned (`MaximumRetryAttempts`, `MaximumEventAgeInSeconds`)
-- [ ] Reserved concurrency = 0 documented as the emergency kill switch
-- [ ] No unhandled exceptions — catch, log, return meaningful errors
+- [ ] Every handler is idempotent
+- [ ] Partial batch failure reporting enabled (SQS, Kinesis, DynamoDB Streams)
+- [ ] `BisectBatchOnFunctionError` enabled for stream sources (isolates poison records)
+- [ ] Retry config tuned — `MaximumRetryAttempts`, `MaximumEventAgeInSeconds`
+- [ ] Circuit breakers on downstream HTTP calls
+- [ ] Reserved concurrency = 0 documented as emergency kill switch
+- [ ] Graceful error handling — catch, log, and return meaningful errors (no unhandled exceptions)
 
 ### Deployment
 
-- [ ] Aliases + weighted shifting (or CodeDeploy canary/linear) with rollback alarms
-- [ ] All infra in code (CDK/SAM/CloudFormation)
-- [ ] Separate accounts for dev/staging/prod
-- [ ] Post-deploy smoke tests + pre-traffic hooks before full shift
+- [ ] Aliases + weighted traffic shifting (or CodeDeploy canary/linear)
+- [ ] Rollback alarms wired into the deployment pipeline
+- [ ] All infrastructure defined in code (CDK, SAM, or CloudFormation)
+- [ ] Separate AWS accounts for dev, staging, production
+- [ ] Automated smoke tests run post-deployment before full traffic shift
+- [ ] Pre-traffic hooks (BeforeAllowTraffic) validate function health before shifting
 
 ---
 
 ## Architecture decisions
 
-### Lambdalith vs micro-Lambda
+### Monolith Lambda vs micro-Lambda
+
+| Aspect | Lambdalith (single function) | Micro-Lambda (function per route) |
+|---|---|---|
+| Cold starts | One function to warm; larger package | Many functions; smaller, faster init |
+| IAM granularity | Single broad role | Per-function least-privilege |
+| Deployment | Everything together; simpler CI/CD | Independent; more pipeline complexity |
+| Observability | One log group; harder per-route metrics | Per-function metrics, alarms, logs |
+| Scaling | Single concurrency pool | Independent scaling + reserved concurrency per function |
+| DX | Familiar Express/FastAPI style | More AWS-native; requires IaC discipline |
+
+**Guidance**: Prefer micro-Lambda for greenfield (least privilege, independent scaling, granular observability). Use Lambdalith when migrating existing Express/FastAPI apps or when team size makes deployment simplicity more valuable than granularity.
+
+### Function URLs vs API Gateway
 
-Prefer **micro-Lambda** (function per route) for greenfield: per-function least-privilege IAM, independent scaling + reserved concurrency, granular observability, smaller/faster cold starts. Use a **Lambdalith** when migrating an existing Express/FastAPI app or when a small team values deployment simplicity over granularity.
+| Feature | Function URLs | API Gateway (HTTP API) | API Gateway (REST API) |
+|---|---|---|---|
+| Auth | IAM only (or in-code) | IAM, JWT, Lambda authorizers | IAM, Cognito, Lambda authorizers, API keys |
+| Rate limiting | None built-in | Built-in throttling | Throttling + usage plans |
+| Response streaming | Yes (native) | No | Yes (proxy integration) |
+| Custom domains | Via CloudFront | Built-in | Built-in |
+| WAF | No (use CloudFront) | No (use CloudFront) | Yes |
+| Request validation | None | None | JSON Schema |
+| Caching | Via CloudFront | None | Built-in |
+| WebSocket | No | No | No (separate WebSocket API required) |
+
+**Use Function URLs** for: internal service-to-service (IAM auth), Lambdalith + CloudFront, streaming, webhook receivers.
+
+**Use API Gateway** for: public APIs needing rate limiting, JWT/Cognito auth, multi-function path routing, WAF without CloudFront.
 
 ### Reserved vs Provisioned Concurrency
 
-Reserved = guarantee capacity + protect downstream (cold starts still possible, throttles at the limit). Provisioned = eliminate cold starts (spills to on-demand beyond the count). Need both → provisioned ≤ reserved. Try **SnapStart** before Provisioned for Java/Python 3.12+/.NET 8+ (no cost for Java). See [concurrency.md](concurrency.md).
+| Aspect | Reserved Concurrency | Provisioned Concurrency |
+|---|---|---|
+| Purpose | Guarantee capacity + protect downstream | Eliminate cold starts |
+| Cold starts | Still possible | Eliminated (pre-warmed) |
+| Throttling | Throttles at the limit | Spills to on-demand beyond provisioned |
+| Use case | Protect a database; guarantee capacity | Latency-sensitive APIs; payment processing |
+
+Decision flow:
+
+1. **Need to limit scaling** → Reserved concurrency
+2. **Need to eliminate cold starts** → Provisioned concurrency (try SnapStart first — no additional cost for Java; caching + restore charges for Python/.NET)
+3. **Need both** → Set provisioned ≤ reserved; reserved acts as the ceiling
 
 ---
 
 ## Observability
 
-Use Powertools **Logger** (structured JSON, auto correlation IDs), **Tracer** (wraps X-Ray, auto-captures SDK/HTTP calls; annotate traces with business keys), **Metrics** (EMF — zero latency, writes to stdout vs ~5–20ms for synchronous `PutMetricData`; avoid `PutMetricData` in hot paths).
+### Powertools setup (Python / TypeScript / Java / .NET)
 
-### Minimum alarm set (every production function)
+**Logger** — structured JSON, correlation IDs injected automatically, log level via env var.
 
-| Alarm | Metric | Threshold | Why |
-|---|---|---|---|
-| Error rate | `Errors / Invocations` | > 1% | Bugs / upstream failures |
-| Throttles | `Throttles` | > 0 | Concurrency limit hit |
-| Duration P99 | `Duration` P99 | > 80% of timeout | Catch slow functions before timeout |
-| Iterator age | `IteratorAge` | > 60s | Stream processing falling behind |
-| Concurrent executions | `ConcurrentExecutions` | > 80% of reserved | Approaching throttle threshold |
-| DLQ depth | SQS `ApproximateNumberOfMessagesVisible` | > 0 | Failed messages accumulating |
+**Tracer** — wraps X-Ray SDK; auto-captures AWS SDK calls, HTTP requests, handler. Add custom subsegments for critical paths. Annotate traces with business keys (customer ID, order ID) for filtering.
+
+**Metrics** — emits via Embedded Metric Format. Zero latency impact.
+
+### EMF vs PutMetricData
+
+| | EMF (Powertools Metrics) | `PutMetricData` API |
+|---|---|---|
+| Latency impact | Zero — writes to stdout | Synchronous API call (~5–20 ms) |
+| Complexity | One-liner with Powertools | Manual batching, error handling |
+| Recommendation | **Use this** | Avoid in hot paths |
+
+### Minimum alarm set
+
+Set these six alarms on every production function:
 
-Set **log retention** when creating log groups — the default is "never expire."
+| Alarm | Metric | Threshold | Period | Why |
+|---|---|---|---|---|
+| Error rate | `Errors / Invocations` | > 1 % | 5 min | Catch bugs and upstream failures |
+| Throttles | `Throttles` | > 0 | 5 min | Concurrency limit hit |
+| Duration P99 | `Duration` P99 | > 80 % of timeout | 5 min | Catch slow functions before timeout |
+| Iterator age | `IteratorAge` | > 60 s | 5 min | Stream processing falling behind |
+| Concurrent executions | `ConcurrentExecutions` | > 80 % of reserved | 5 min | Approaching throttle threshold |
+| DLQ depth | SQS `ApproximateNumberOfMessagesVisible` | > 0 | 5 min | Failed messages accumulating |
 
-### Testing
+### Log retention
 
-Serverless apps are mostly about **service integrations**, not complex business logic — so the **integration layer (tested in the cloud) is the most valuable**, with few unit tests (pure logic) and few E2E. Structure handlers as thin adapters calling pure functions. Don't rely on LocalStack/DynamoDB Local as primary testing (they diverge on IAM, quotas, error codes); don't mock AWS SDK calls for integration tests. Iterate fast with `sam sync` / `cdk watch`; give each developer an isolated stack.
+Set retention when creating log groups. Defaults to "never expire" — storage accumulates continuously. Choose a retention period based on your compliance and debugging needs.
 
 ---
 
-## Idempotency
+## Security hardening
 
-Lambda guarantees **at-least-once** — duplicates come from async retries, SQS visibility expiry, stream replays, client retries, Step Functions task retries. Use the **Powertools Idempotency** utility (Python/TS/Java/.NET), backed by a DynamoDB table with TTL.
+### One role per function
 
-Table: `id` (hash of idempotency key) + `status` (INPROGRESS/COMPLETED/EXPIRED), `data` (cached response), `expiration` (TTL).
+Never share IAM roles across functions. Scope every policy to specific resource ARNs:
 
-Idempotency key by source:
+```yaml
+# Good
+Effect: Allow
+Action: dynamodb:PutItem
+Resource: arn:aws:dynamodb:us-east-1:123456789012:table/OrdersTable
 
-| Source | Key |
+# Bad
+Effect: Allow
+Action: dynamodb:*
+Resource: "*"
+```
+
+Use IAM Access Analyzer to identify unused permissions and generate least-privilege policies.
+
+### Secrets management
+
+- Store in **Secrets Manager** or **SSM Parameter Store** (SecureString)
+- Cache in the execution environment with **Powertools Parameters** (avoids API call per invocation)
+- Rotate automatically via Secrets Manager rotation Lambdas
+- Environment variables are visible in the Lambda console and API — never put secrets there
+
+### Input validation
+
+Validate at the handler boundary before business logic runs:
+
+| Language | Library |
 |---|---|
-| SQS | `messageId` |
-| EventBridge | `detail.id` or composite |
-| DynamoDB Streams | `eventID` |
-| API Gateway / Function URL | `Idempotency-Key` header or body hash |
-| Step Functions | Execution ID + task token |
+| TypeScript | Zod, io-ts, JSON Schema |
+| Python | Pydantic, Powertools Validation (JSON Schema) |
+| Java | Bean Validation (JSR 380), JSON Schema |
+
+Powertools Validation supports envelope extraction for API Gateway, SQS, EventBridge, etc.
+
+### VPC: endpoints over NAT Gateway
 
-TTL ≈ how long duplicates can arrive (API retries ~1h; SQS ≈ `maxReceiveCount` × visibility; stream replays ~24h).
+If your function must be in a VPC, use **VPC endpoints** for AWS service access instead of NAT Gateway:
+
+| | VPC Endpoint | NAT Gateway |
+|---|---|---|
+| Latency | Lower (stays on AWS backbone) | Higher (extra hop) |
+
+Create endpoints for: DynamoDB (gateway), S3 (gateway), SQS, Secrets Manager, SSM, KMS.
 
 ---
 
-## Response streaming
+## Testing strategies
 
-Use for payloads > 6 MB (buffered limit), TTFB-sensitive responses, SSE, LLM token streaming, or large file generation.
+### The serverless testing pyramid (inverted)
 
-- **Function URLs** are simplest; REST API also supports streaming (proxy, STREAM mode); **HTTP API does not**.
-- **200 MB** response limit; **2 MBps** cap after the first 6 MB.
-- Billed for full duration even if the client disconnects.
-- Node.js has native support (`awslambda.streamifyResponse` + `awslambda.HttpResponseStream.from`); other runtimes need a custom runtime or Lambda Web Adapter.
-- **Not supported for VPC-attached functions via Function URL** — use the `InvokeWithResponseStream` API instead.
+```
+        ┌─────────────┐
+        │   E2E Tests  │  Few — full workflow verification
+        ├─────────────┤
+        │ Integration  │  Many — THIS IS THE MOST VALUABLE LAYER
+        │  (in cloud)  │  Test real service interactions
+        ├─────────────┤
+        │  Unit Tests  │  Fast — pure business logic only
+        └─────────────┘
+```
 
-Don't stream small JSON (< 6 MB) — buffered is simpler.
+Serverless apps are primarily about service integrations, not complex business logic. Integration tests in the cloud detect the most impactful defects.
+
+### Structure code for testability
+
+```
+handler (thin adapter)
+  → extract + validate event
+  → call business logic (pure functions — unit test these)
+  → call AWS services (integration test these in the cloud)
+```
+
+### What to test where
+
+| Layer | What | How |
+|---|---|---|
+| Unit | Business logic (calculations, transforms, validation) | Local, fast, mocked dependencies |
+| Integration | Service contracts (DynamoDB reads/writes, SQS send/receive, IAM permissions) | Deploy to AWS, test against real services |
+| E2E | Full workflows (API → Lambda → DynamoDB → Stream → Lambda → SQS) | Dedicated staging environment; poll for async side effects |
+
+### Fast iteration
+
+- **`sam sync`** — hot-deploys code changes to AWS in seconds
+- **`cdk watch`** — watches for file changes and auto-deploys
+- Each developer gets an isolated test stack (separate account or prefixed stack name)
+
+### What NOT to do
+
+- Don't rely on LocalStack / DynamoDB Local as primary testing — they diverge from real AWS (IAM, quotas, error codes)
+- Don't mock AWS SDK calls for integration tests — you'll miss permission and config issues
+- Don't skip cloud testing because "it's slow" — use `sam sync` / `cdk watch`
 
 ---
 
-## Anti-patterns
+## Idempotency patterns
+
+Lambda guarantees **at-least-once** execution. Duplicates happen from: async retries, SQS visibility timeout expiry, stream shard replays, client retries on timeout, Step Functions task retries.
+
+### Powertools Idempotency utility
+
+Uses DynamoDB to track processed events. Available for Python, TypeScript, Java, .NET.
+
+**Python:**
+
+```python
+from aws_lambda_powertools.utilities.idempotency import (
+    DynamoDBPersistenceLayer, idempotent
+)
+
+persistence = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+
+@idempotent(persistence_store=persistence)
+def handler(event, context):
+    payment = process_payment(event)
+    return {"statusCode": 200, "body": payment}
+```
+
+**TypeScript:**
+
+```typescript
+import { makeIdempotent } from "@aws-lambda-powertools/idempotency";
+import { DynamoDBPersistenceLayer } from "@aws-lambda-powertools/idempotency/dynamodb";
+
+const persistence = new DynamoDBPersistenceLayer({ tableName: "IdempotencyTable" });
+
+export const handler = makeIdempotent(async (event) => {
+  const payment = await processPayment(event);
+  return { statusCode: 200, body: JSON.stringify(payment) };
+}, { persistenceStore: persistence });
+```
+
+### DynamoDB table design
+
+```
+Table: IdempotencyTable
+  PK: id (String)          — hash of the idempotency key
+  Attributes:
+    status:     INPROGRESS | COMPLETED | EXPIRED
+    data:       cached response payload
+    expiration: TTL epoch timestamp
+  TTL attribute: expiration
+```
+
+### Choosing the idempotency key
+
+| Event source | Key |
+|---|---|
+| SQS | `messageId` |
+| EventBridge | `detail.id` or composite of event fields |
+| DynamoDB Streams | `eventID` |
+| API Gateway / Function URL | `Idempotency-Key` header or request body hash |
+| Step Functions | Execution ID + task token |
+
+### TTL for cleanup
 
-- **Lambda calling Lambda synchronously** — doubles latency, tight coupling, fragile error handling. Decouple via SQS, or use Step Functions when you need the result.
-- **Unintentional monolithic handler** — routing stuffed into one function without weighing trade-offs prevents independent scaling and broadens IAM blast radius. Choose Lambdalith vs micro-Lambda deliberately (see above).
-- **Secrets in env vars** — visible in console/API, 4 KB total cap. Use Secrets Manager with Powertools caching.
-- **Skipping idempotency** — at-least-once delivery causes duplicate records.
-- **VPC when not needed** — adds cold-start latency. Only for private resources; use VPC endpoints for AWS services.
-- **Default 3s timeout** — legitimate requests fail silently. Set SDK/HTTP client timeouts shorter than the Lambda timeout for meaningful errors.
-- **Missing DLQ** — failed async invocations / ESM messages are discarded silently.
-- **Log retention = forever** — storage accumulates continuously.
+Set TTL based on how long duplicates can arrive. Typical values:
+
+- API retries: 1 hour
+- SQS retries: match the queue's `maxReceiveCount` × visibility timeout
+- Stream replays: 24 hours (Kinesis retention default)
+
+DynamoDB automatically deletes expired items (typically within a few days of TTL expiry).
+
+---
+
+## Response streaming
+
+### When to use
+
+| Use case | Why streaming helps |
+|---|---|
+| Large payloads (> 6 MB) | Buffered limit is 6 MB; streaming supports up to 200 MB |
+| TTFB-sensitive responses | Client sees partial data immediately (HTML shell, then content) |
+| Server-sent events (SSE) | Real-time updates to browser clients |
+| LLM / AI token streaming | Stream tokens as generated (conversational AI-style) |
+| Large file generation | CSV/PDF rows streamed as produced |
+
+### Constraints
+
+- **Function URLs** are simplest for streaming. REST API also supports streaming via proxy integration with STREAM transfer mode. HTTP API does **not** support streaming.
+- **200 MB** response limit
+- **2 MBps** bandwidth cap after the first 6 MB
+- Billed for full function duration even if client disconnects
+- Node.js has native support; other runtimes use custom runtime or Lambda Web Adapter
+- **Function URL streaming is NOT supported for VPC-attached functions.** Use the `InvokeWithResponseStream` API as an alternative.
+
+### Node.js example
+
+```javascript
+export const handler = awslambda.streamifyResponse(
+  async (event, responseStream, context) => {
+    const metadata = {
+      statusCode: 200,
+      headers: { "Content-Type": "text/html" },
+    };
+    responseStream = awslambda.HttpResponseStream.from(responseStream, metadata);
+
+    responseStream.write("<html><body>");
+    for (const chunk of generateContent()) {
+      responseStream.write(chunk);
+    }
+    responseStream.write("</body></html>");
+    responseStream.end();
+  }
+);
+```
+
+### When NOT to use
+
+- Small JSON responses (< 6 MB) — buffered is simpler
+- When you need API Gateway features (rate limiting, caching, WAF) without CloudFront
+- VPC-based functions needing Function URL streaming (use `InvokeWithResponseStream` API instead)
 
 ---
 
@@ -151,6 +384,110 @@ Don't stream small JSON (< 6 MB) — buffered is simpler.
 - [AWS Lambda Best Practices](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)
 - [Lambda Concurrency and Scaling](https://docs.aws.amazon.com/lambda/latest/dg/lambda-concurrency.html)
 - [Response Streaming](https://docs.aws.amazon.com/lambda/latest/dg/configuration-response-streaming.html)
-- [Testing serverless functions](https://docs.aws.amazon.com/lambda/latest/dg/testing-guide.html)
+- [How to Test Serverless Functions](https://docs.aws.amazon.com/lambda/latest/dg/testing-guide.html)
 - [Serverless Applications Lens — Well-Architected](https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/welcome.html)
 - [Powertools for AWS Lambda](https://docs.powertools.aws.dev/lambda/)
+
+---
+
+## Anti-patterns
+
+Common mistakes that cause production issues in serverless applications. Each pairs the problem with the correct alternative.
+
+### Avoid: Lambda calling Lambda synchronously
+
+Synchronous Lambda-to-Lambda invocation doubles latency, creates tight coupling, and makes error handling fragile.
+
+```python
+# BAD: Direct synchronous invocation
+lambda_client.invoke(FunctionName='downstream', InvocationType='RequestResponse', Payload=json.dumps(event))
+```
+
+### Instead: Use Step Functions or SQS
+
+```python
+# GOOD: Decouple via SQS
+sqs.send_message(QueueUrl=QUEUE_URL, MessageBody=json.dumps(event))
+```
+
+Or use Step Functions for orchestration when you need the result.
+
+---
+
+### Avoid: Monolithic handler without intentional design
+
+Routing logic stuffed into a single handler without considering trade-offs prevents independent scaling, broadens IAM blast radius, and increases cold start times.
+
+```python
+# BAD: One function handling all routes without considering trade-offs
+def handler(event, context):
+    path = event['path']
+    if path == '/users': return handle_users(event)
+    elif path == '/orders': return handle_orders(event)
+    elif path == '/products': return handle_products(event)
+```
+
+### Instead: Choose deliberately
+
+For greenfield projects, prefer one function per route (least privilege, independent scaling, granular observability). For migrations from Express/FastAPI or small teams prioritizing deployment simplicity, a Lambdalith is a valid choice — see [Architecture decisions](#architecture-decisions) for trade-offs.
+
+---
+
+### Avoid: Secrets in environment variables
+
+Visible in console and API, 4 KB total limit for all environment variables combined.
+
+```python
+# BAD: Secret in env var
+db_password = os.environ['DB_PASSWORD']
+```
+
+### Instead: Use Secrets Manager with Powertools caching
+
+```python
+# GOOD: Cached secret retrieval
+from aws_lambda_powertools.utilities import parameters
+db_password = parameters.get_secret("my-db-secret", max_age=300)
+```
+
+---
+
+### Avoid: Skipping idempotency
+
+Lambda delivers at-least-once; duplicates cause duplicate records.
+
+### Instead: Use Powertools Idempotency
+
+```python
+from aws_lambda_powertools.utilities.idempotency import idempotent, DynamoDBPersistenceLayer
+
+persistence = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+
+@idempotent(persistence_store=persistence)
+def handler(event, context):
+    return process_payment(event)
+```
+
+---
+
+### Avoid: VPC when not needed
+
+Adds cold start latency. Only attach Lambda to a VPC for private resources (RDS, ElastiCache, Elasticsearch). Use VPC endpoints for AWS service access instead.
+
+---
+
+### Avoid: Default 3s timeout
+
+Legitimate requests fail silently. Set timeout based on load-test P99 + buffer. Set SDK/HTTP client timeouts shorter than Lambda timeout to get meaningful errors instead of generic timeouts.
+
+---
+
+### Avoid: Missing DLQ
+
+Failed async invocations and event source messages are discarded without notification. Configure dead-letter queues on all async invocations and event source mappings.
+
+---
+
+### Avoid: CloudWatch Logs retention = forever
+
+Storage accumulates continuously. Set a retention period — do not leave at unlimited.