infrastructure-stack-patterns

Infrastructure Stack Patterns

Guidelines for creating and maintaining CDK stacks for API services in the T6C project.

MANDATORY Stack Structure

Required Imports and Setup

EVERY stack MUST follow this exact import and setup pattern:

import path from 'node:path'
import { fileURLToPath } from 'node:url'
import * as cdk from 'aws-cdk-lib'
import type * as apigateway from 'aws-cdk-lib/aws-apigateway'
import {
  AttributeType,
  type ITable,
  ProjectionType,
} from 'aws-cdk-lib/aws-dynamodb'
import type { Construct } from 'constructs'
import 'source-map-support/register'
import {
  ApiConstruct,
  ApiGatewayHandlerLambda,
  BaseStack,
  type BaseStackProps,
  DynamoDatabaseTableWithCompositeKey,
} from './constructs/index.js'
import { getEnvVarOrThrow } from './util/index.js'

const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)

Required Stack Class Structure

EVERY stack MUST extend BaseStack and follow this pattern:

type {Service}StackProps = {
  // Dependencies from other stacks
  userServiceUrl: string
} & BaseStackProps

export class {Service}Stack extends BaseStack {
  // Public resources for other stacks
  public readonly table: ITable
  public readonly api: apigateway.RestApi

  constructor(scope: Construct, props: {Service}StackProps) {
    const prefix = `${props.productName}-${props.stageName}`
    super(scope, `${prefix}-{Service}Stack`, props)

    // 1. Create API Gateway using ApiConstruct
    const {service}Api = new ApiConstruct(this, '{Service}Api', { ...props })
    this.api = {service}Api.api

    // 2. Create Database Table using DynamoDatabaseTableWithCompositeKey
    const { table: {service}Table } = new DynamoDatabaseTableWithCompositeKey(
      this,
      `${prefix}-{Service}Table`,
      {
        tableName: `${prefix.toLowerCase()}-{service}`,
        partitionKey: { name: 'PK', type: AttributeType.STRING },
        sortKey: { name: 'SK', type: AttributeType.STRING },
        stream: true,
        globalSecondaryIndexes: [
          {
            indexName: 'GSI1',
            partitionKey: { name: 'GSI1PK', type: AttributeType.STRING },
            sortKey: { name: 'GSI1SK', type: AttributeType.STRING },
            projectionType: ProjectionType.ALL,
          },
          {
            indexName: 'GSI2',
            partitionKey: { name: 'GSI2PK', type: AttributeType.STRING },
            sortKey: { name: 'GSI2SK', type: AttributeType.STRING },
            projectionType: ProjectionType.ALL,
          },
        ],
      },
    )
    this.table = {service}Table

    // 3. Common Props with proper environment variables
    const commonProps = {
      description: prefix,
      apiGatewayResource: this.api.root,
      apiKeyRequired: true,
      env: {
        {SERVICE}_TABLE: {service}Table.tableName,
        USER_SERVICE_URL: props.userServiceUrl,
        USER_SERVICE_API_KEY: getEnvVarOrThrow('USER_SERVICE_API_KEY'),
        // Add other environment variables as needed
      },
    }

    // 4. Register ALL handlers from packages/{service}-api/src/lambdas/
    // ... handler registrations

    // 5. Outputs
    new cdk.CfnOutput(this, '{Service}TableName', {
      value: {service}Table.tableName,
    })
  }
}