Turning repeated serverless wiring into reusable CDK constructs.

The hard part is not one service. It is what gets rebuilt every time.

Teams often need the same workflow skeleton: accept a request, store durable state, queue asynchronous work, update status, publish lifecycle events, and show enough operational signal to notice when work is stuck.

If every team hand-builds that pattern, permissions, retry policy, alarm thresholds, table indexes, and event-source settings drift between services. The goal here is to package the repeated parts while keeping the business behavior visible.

The useful middle ground is a small construct library.

A durable workflow path where failure has somewhere to go.

• API Gateway REST API
• 3 Lambda functions
• DynamoDB state table with TTL, PITR, and status index
• SQS work queue and dead-letter queue
• SNS topic for lifecycle events
• 2 CloudWatch alarms
• least-privilege IAM policies
• stack outputs for API URL, table name, and queue URL

The same architecture, with less repeated service code.

const deadLetterQueue = new Queue(this, "WorkflowDeadLetterQueue", {
  retentionPeriod: Duration.days(14)
});

const workQueue = new Queue(this, "WorkflowWorkQueue", {
  visibilityTimeout: Duration.seconds(60),
  retentionPeriod: Duration.days(4),
  deadLetterQueue: {
    queue: deadLetterQueue,
    maxReceiveCount: 3
  }
});

stateTable.grantReadWriteData(submitFunction);
workQueue.grantSendMessages(submitFunction);
stateTable.grantReadData(statusFunction);
stateTable.grantReadWriteData(workerFunction);
workQueue.grantConsumeMessages(workerFunction);
notifications.grantPublish(workerFunction);

const stateTable = new WorkflowStateTable(this, "WorkflowState");
const workQueue = new AsyncWorkQueue(this, "WorkQueue");
const notifications = new WorkflowNotifications(this, "WorkflowNotifications");

new WorkflowApi(this, "WorkflowApi", {
  stateTable,
  workQueue,
  submitEntry,
  statusEntry
});

new WorkflowWorker(this, "WorkflowWorker", {
  stateTable,
  workQueue,
  notifications,
  entry: workerEntry
});

new WorkflowObservability(this, "WorkflowObservability", {
  workQueue
});

Each construct owns one operational concern.

export class WorkflowStateTable extends Construct {
  public readonly table: Table;
  public readonly requestIdKey = "requestId";

  public constructor(scope: Construct, id: string, props: WorkflowStateTableProps = {}) {
    super(scope, id);

    this.table = new Table(this, "Table", {
      partitionKey: { name: this.requestIdKey, type: AttributeType.STRING },
      billingMode: BillingMode.PAY_PER_REQUEST,
      timeToLiveAttribute: props.ttlAttribute ?? "expiresAt",
      pointInTimeRecoverySpecification: {
        pointInTimeRecoveryEnabled: props.pointInTimeRecovery ?? true
      }
    });

    this.table.addGlobalSecondaryIndex({
      indexName: "status-createdAt-index",
      partitionKey: { name: "status", type: AttributeType.STRING },
      sortKey: { name: "createdAt", type: AttributeType.STRING },
      projectionType: ProjectionType.ALL
    });
  }
}

export class AsyncWorkQueue extends Construct {
  public readonly queue: Queue;
  public readonly deadLetterQueue: Queue;

  public constructor(scope: Construct, id: string, props: AsyncWorkQueueProps = {}) {
    super(scope, id);

    this.deadLetterQueue = new Queue(this, "DeadLetterQueue", {
      retentionPeriod: props.retentionPeriod ?? Duration.days(14)
    });

    this.queue = new Queue(this, "Queue", {
      visibilityTimeout: props.visibilityTimeout ?? Duration.seconds(60),
      retentionPeriod: props.retentionPeriod ?? Duration.days(4),
      deadLetterQueue: {
        queue: this.deadLetterQueue,
        maxReceiveCount: props.maxReceiveCount ?? 3
      }
    });
  }
}

Permissions stay close to the workflow boundary.

The example keeps permissions close to the construct that needs them. Submit, status, and worker functions get different grants, and the stack test checks that generated IAM actions do not fall back to broad wildcard access.

expect(submitActions).toEqual(
  expect.arrayContaining(["dynamodb:PutItem", "dynamodb:UpdateItem", "sqs:SendMessage"])
);
expect(submitActions).not.toContain("sqs:ReceiveMessage");
expect(submitActions).not.toContain("sns:Publish");

expect(statusActions).toEqual(expect.arrayContaining(["dynamodb:GetItem", "dynamodb:Query"]));
expect(statusActions).not.toContain("dynamodb:PutItem");
expect(statusActions).not.toContain("sqs:SendMessage");

expect(workerActions).toEqual(
  expect.arrayContaining(["dynamodb:UpdateItem", "sqs:ReceiveMessage", "sns:Publish"])
);
expect(workerActions).not.toContain("sqs:SendMessage");

From construct definition to reproducible CloudFormation.

The two excerpts below are what cdk synth emits for the example stack. They are abbreviated for reading: logical IDs are truncated and unrelated metadata is removed. Anyone running npm run synth in the companion repository can reproduce the full template.

{
  "Type": "AWS::DynamoDB::Table",
  "Properties": {
    "AttributeDefinitions": [
      { "AttributeName": "requestId", "AttributeType": "S" },
      { "AttributeName": "status",    "AttributeType": "S" },
      { "AttributeName": "createdAt", "AttributeType": "S" }
    ],
    "KeySchema": [
      { "AttributeName": "requestId", "KeyType": "HASH" }
    ],
    "BillingMode": "PAY_PER_REQUEST",
    "PointInTimeRecoverySpecification": { "PointInTimeRecoveryEnabled": true },
    "TimeToLiveSpecification":          { "AttributeName": "expiresAt", "Enabled": true },
    "GlobalSecondaryIndexes": [
      {
        "IndexName": "status-createdAt-index",
        "KeySchema": [
          { "AttributeName": "status",    "KeyType": "HASH" },
          { "AttributeName": "createdAt", "KeyType": "RANGE" }
        ],
        "Projection": { "ProjectionType": "ALL" }
      }
    ]
  }
}

{
  "PolicyDocument": {
    "Statement": [
      {
        "Action": ["dynamodb:PutItem", "dynamodb:UpdateItem"],
        "Effect": "Allow",
        "Resource": { "Fn::GetAtt": ["WorkflowStateTableTable...", "Arn"] }
      },
      {
        "Action":   "sqs:SendMessage",
        "Effect":   "Allow",
        "Resource": { "Fn::GetAtt": ["WorkQueueQueue...", "Arn"] }
      }
    ],
    "Version": "2012-10-17"
  }
}

The tests check both behavior and infrastructure shape.

The implementation has workflow unit tests, construct-level tests, full-stack assertion tests, and a before/after comparison test. The comparison is there because the developer interface changed, but the architecture should not quietly change with it.

it("keeps the same architectural shape while changing the developer interface", () => {
  const beforeApp = new App();
  const afterApp = new App();
  const before = Template.fromStack(new BeforeHandWiredStack(beforeApp, "BeforeStack"));
  const after = Template.fromStack(new AfterConstructLibraryStack(afterApp, "AfterStack"));

  expect(selectedResourceCounts(before)).toEqual(selectedResourceCounts(after));
});

What this design chooses, and what it leaves open.

What I would change before running this publicly.

• Authentication and caller identity mapped into request context.
• API throttling, budgets, and alarms for cost control.
• Deployment promotion across environments with retained data policies.
• Structured logs, traces, and dashboard views for support handoff.

This version stays local on purpose. Tests and synth show the construct design without exposing a public endpoint that would need bot protection, request throttling, and spend controls.

This is a focused platform pattern, not a complete internal platform.

The first slice is local and single-region. Authentication, deployment promotion, multi-region failover, structured logging helpers, and publishable package automation are intentionally outside this version. Those become more useful once the construct boundaries are stable.

• Infrastructure as Code with AWS CDK
• AWS serverless architecture
• Resume