Instruction file imported from Kevan-Y/Themoo (.github/instructions/infra.instructions.md). Copyright stays with the author.

Infrastructure Agent Instructions

⚠️ NEVER Run pulumi up

pulumi up is strictly prohibited. It deploys live infrastructure and can cause irreversible changes.

• ✅ Allowed: pulumi preview — dry-run diff only
• ❌ Forbidden: pulumi up, pulumi destroy, pulumi refresh

cd services/core/infra && pulumi preview   # dry-run for starter_core
cd services/api/infra  && pulumi preview   # dry-run for starter_apigateway
pulumi stack output                        # view exported values

Two-Stack Overview

services/core/infra/   (Pulumi project: starter_core)
  → DynamoDB tables
  → Lambda functions
  → SSM parameters: /<nameWithEnvironment>/<name>Key (Lambda ARNs)

services/api/infra/    (Pulumi project: starter_apigateway)
  → Reads Lambda ARNs from SSM via lambdaSsmKey(environment)
  → API Gateway HTTP API + JWT authorizer (Clerk)
  → Routes wired to Lambda integrations

Deploy order: starter_core must be deployed first so SSM parameters exist before starter_apigateway reads them.

SSM Key Format for Lambda ARNs

createLambda automatically writes the Lambda ARN to SSM at: /<nameWithEnvironment>/<lambdaName>Key

Helper Conventions

Always Pass { provider } to opts

// ✅ correct
createLambda('myHandler', 'my/myHandler', role.arn, config, { ... }, { provider });
createDynamoTable('MyTable', { hashKey: 'PK', rangeKey: 'SK', ... }, config, { provider });

Adding a New Lambda — 5-Step Checklist

1. Create the handler — services/core/src/features/<name>/<name>Handler.ts
2. Register in core infra — add createLambda(...) in services/core/infra/index.ts
3. Register the SSM key — add to lambdaSsmKey() in services/api/infra/lambdaSsmKey.ts
4. Wire to API Gateway — add getLambdaArn, createIntegration, createRoutes in services/api/infra/index.ts
5. Update the IAM policy — add the new Lambda ARN to the Resource array

After all changes, run pulumi preview (not pulumi up) in each stack to validate the diff.