Migrate template to an AWS CDK based setup

* Increment root package version, move to node 22, Nx 21 and new typescript setup

* Add core CDK application and service generator

* Add CDK migration notes, version and alias resources, lambda defaults, STAGE tag

* Constructs, aspects, injectors to standardise development in cdk-utils

* Use mjs format for everything

* Include store-parameters package for SSM parameter management

---------

Co-authored-by: KaiNguyen <108910975+kai-nguyen-aligent@users.noreply.github.com>

Author: Torbjorn van Heeswijck

.git-hooks/pre-commit

@@ -6,20 +6,40 @@
 export NVM_DIR="$HOME/.nvm"
 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
 
-# This take the current active node version you want to verify the hook
-export NVM_DIR="$HOME/.nvm"
-a=$(nvm current)
-
-export PATH="$NVM_DIR/versions/node/$a/bin:$PATH"
-
 # Define colours for nicer CLI output
 RED="\033[1;31m"
 GREEN="\033[1;32m"
 NO_COLOUR="\033[0m"
 
-echo -e "${GREEN} Executing git hook $0 $@ ${NO_COLOUR}"
+echo -e "${GREEN}Executing git hook $0 $@${NO_COLOUR}"
+
+# Use the current Node version explicitly
+nvm use
+
+# Get the list of staged changes
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+# Exclude files that shouldn't trigger pre-commit checks
+# This is done here because `nx affected` doesn't look at task inputs
+# when determining if a project is affected
+EXCLUDED_FILES_REGEX='.*\.md$' # Ignore markdown files
+EXCLUDED_FILES_REGEX+='|.*\/step-functions\/.*\.(yml|yaml)$' # Ignore step function yaml files
+EXCLUDED_FILES_REGEX+='|^\/?([^\/]*)$' # Ignore all root-level files
+AFFECTED_FILES=$(echo "$STAGED_FILES" | \
+  grep -vE "$EXCLUDED_FILES_REGEX" | \
+  paste -sd,)
+
+echo -e "${GREEN}\nAffected files: $AFFECTED_FILES\n${NO_COLOUR}"
+
+# Exit early if there are no affected files
+if [ -z "$AFFECTED_FILES" ]; then
+  echo -e "${GREEN}No affected files found. Exiting pre-commit hook.${NO_COLOUR}"
+  exit 0
+fi
 
-commands=("npx nx affected -t lint, typecheck --parallel=3" "npx nx affected:test --coverage")
+# Prepare the affected commands for static analysis targets
+AFFECTED_COMMAND="yarn nx affected --files=$AFFECTED_FILES --nxBail --tui=false"
+commands=("$AFFECTED_COMMAND -t lint typecheck --parallel=3", "$AFFECTED_COMMAND -t test --configuration coverage")
 failures=()
 
 # Loop over commands, execute and push failure message if we see one

.github/workflows/package.yml

@@ -12,9 +12,12 @@ jobs:
   deploy:
     name: Test package building
     runs-on: ubuntu-latest
+    env:
+      # Generating an Nx library will cause a failure if this is enabled
+      YARN_ENABLE_IMMUTABLE_INSTALLS: 0
     strategy:
       matrix:
-        node-version: [20.18]
+        node-version: [22.14]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -29,13 +32,13 @@ jobs:
           cache: yarn
 
       - name: Install dependencies
-        run: yarn install --immutable
+        run: yarn install
 
       - name: Generate test library
-        run: npx nx g library test-lib --directory=libs/test-lib --unitTestRunner=none
+        run: yarn nx g library test-lib --directory=libs/test-lib --unitTestRunner=none
 
       - name: Generate test app
-        run: npx nx g service test-app
+        run: yarn nx g service test-app --type=general
 
       # The next 2 lines are needed for nx affected to work when CI is running on a PR
       - name: Set base SHA to origin/main
@@ -45,10 +48,10 @@ jobs:
         run: git fetch
 
       - name: Run tests
-        run: npx nx affected -t lint, test, build --parallel=3 --base=origin/main
+        run: yarn nx affected -t lint, typecheck, build --parallel=3 --base=origin/main
 
       - name: Remove test library
-        run: npx nx g rm test-lib
+        run: yarn nx g rm @aligent/test-lib
 
       - name: Remove test app
-        run: npx nx g rm test-app
+        run: yarn nx g rm @services/test-app

.gitignore

@@ -2,12 +2,13 @@
 
 # environment
 *.env
+*.env*.csv
+!.env.example.csv
 
 # compiled output
 dist
 tmp
-/out-tsc
-.serverless
+out-tsc
 .build
 
 # dependencies
@@ -58,3 +59,7 @@ Thumbs.db
 # Vite temporary config files
 vite.config.*.timestamp*
 vitest.config.*.timestamp*
+
+# CDK asset staging directory
+.cdk.staging
+cdk.out

.nvmrc

@@ -1 +1 @@
-v20.18
+v22.14.0

.vscode/extensions.json

@@ -3,6 +3,9 @@
         "nrwl.angular-console",
         "esbenp.prettier-vscode",
         "dbaeumer.vscode-eslint",
-        "editorconfig.editorconfig"
+        "editorconfig.editorconfig",
+        "amazonwebservices.aws-toolkit-vscode",
+        "usernamehw.errorlens",
+        "yoavbls.pretty-ts-errors"
     ]
 }

CLAUDE.md

@@ -0,0 +1,155 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Essential Commands
+
+### Testing
+
+- **Run tests for affected projects**: `yarn test`
+- **Run tests for all projects**: `yarn test:all`
+- **Run a single test file**: `npx vitest run path/to/test.spec.ts`
+- **Run tests in watch mode**: `npx vitest watch`
+- **Run tests for specific project**: `npx nx test @libs/cdk-utils`
+- **Run specific test file with Nx**: `npx nx test @libs/cdk-utils -- path/to/test.spec.ts`
+
+### Code Quality
+
+- **Lint affected projects**: `yarn lint`
+- **Lint all projects**: `yarn lint:all`
+- **Type check affected projects**: `yarn typecheck`
+- **Type check all projects**: `yarn typecheck:all`
+
+### Service Management
+
+- **Generate new service**: `npx nx g service <service-name>`
+- **Generate notification service**: `npx nx g service <service-name> notification`
+- **Deploy service to AWS**: `npx nx deploy <service-name> -- -s <stage> --aws-profile <profile>`
+- **Remove service from AWS**: `npx nx run <service-name>:remove -- -s <stage> --aws-profile <profile>`
+
+### CDK Deployment
+
+- **Deploy all stacks**: `cd applications/core && cdk deploy`
+- **Deploy staging stacks**: `cd applications/core && cdk deploy stg/**`
+- **Deploy production stacks**: `cd applications/core && cdk deploy prd/**`
+- **View CDK diff**: `cd applications/core && cdk diff`
+
+### API Client Generation
+
+- **Generate typed API client**: `npx nx g client <client-name>`
+
+## Architecture Overview
+
+This is an AWS microservices template using:
+
+- **Nx monorepo** structure with services in `services/` and libraries in `libs/`
+- **AWS CDK v2** for infrastructure as code (recently migrated from Serverless Framework)
+- **TypeScript** with strict type checking extending @aligent/ts-code-standards
+- **Node.js 22.14.0** runtime
+
+### Key Architecture Patterns
+
+1. **Service-Based Architecture**
+
+   - Each service is a separate CDK Stack defined in `services/<service-name>/src/index.ts`
+   - Services export a Stack class that extends `aws-cdk-lib.Stack`
+   - Services are imported and instantiated in `ApplicationStage` inside `applications/core/bin/main.ts`
+
+2. **CDK Application Structure**
+
+   - Entry point: `applications/core/bin/main.ts` creates CDK App and stages
+   - Stages (dev/stg/prd) are created as ApplicationStage instances directly in `main.ts`
+   - Stage-specific configuration is applied via property injectors and aspects
+   - Each stage automatically configures resources based on deployment environment
+
+3. **Lambda and Step Functions**
+
+   - Lambda functions are in `services/<service>/src/lambda/`
+   - Step Functions use YAML definitions in `services/<service>/src/step-functions/`
+   - Shared constructs in `services/<service>/src/lib/constructs/`
+   - Step Functions use JSONata for output transformations
+   - Automatic versioning and aliasing applied via VersionFunctionsAspect
+   - Stage-specific configuration applied via property injectors
+
+4. **Property Injection Architecture**
+
+   - Configuration-based defaults applied via property injectors:
+     - **NodeJsFunctionDefaultsInjector**: Bundling configuration (sourceMap, esm, minify)
+     - **LogGroupDefaultsInjector**: Duration-based retention (SHORT/MEDIUM/LONG)
+     - **StepFunctionDefaultsInjector**: Automatic logging for EXPRESS workflows
+     - **BucketDefaultsInjector**: Auto-cleanup policies for S3 buckets
+   - Cross-cutting concerns handled by aspects (VersionFunctionsAspect for automatic versioning)
+   - Configuration can be customized per stage or globally
+   - Uses CDK's built-in property injection system - no custom constructs needed
+
+5. **CDK Constructs and Utilities**
+
+   - **S3Bucket**: Lifecycle management with duration-based rules (SHORT/MEDIUM/LONG/PERMANENT)
+   - **SsmParameterGroup**: Abstract class for grouping and managing SSM parameters
+   - **StepFunctionFromFile**: Load Step Function definitions from YAML/JSON files
+
+6. **Testing Strategy**
+   - Vitest for unit testing with coverage reports
+   - Test files colocated with source files as `*.spec.ts` or `*.test.ts`
+   - Workspace-level Vitest configuration in `vitest.workspace.ts`
+
+## Important Context
+
+### CDK Migration Notes
+
+- Project migrated from Serverless Framework to CDK using property injection pattern
+- CDK construct IDs are critical - changing them will replace resources
+- Lambda versions and aliases are automatically created via VersionFunctionsAspect
+- Step Functions use `LambdaInvoke` resource with automatic retry blocks
+- Task outputs are nested in `Payload` property - use JSONata to transform
+- Stage-specific resource configuration handled by property injectors
+
+### Configuration
+
+- Update brand name in `nx.json` generators section before first use
+- Package name in `package.json` should follow `@<brand>-int/integrations` format
+- Services are tagged with STAGE and SERVICE tags automatically
+
+### Development Workflow
+
+1. Always run lint and type checks before committing
+2. Use Nx affected commands to optimize CI/CD performance
+3. Follow existing code patterns and conventions in the codebase
+4. Check `CDK-MIGRATION-NOTES.md` for CDK-specific guidance
+
+## AI Helpers
+
+The `docs/ai-helpers/` folder contains documentation templates to assist AI code assistants in creating consistent and comprehensive documentation:
+
+### Recommended MCP Servers
+
+When using Claude Code or other MCP-compatible tools, the following MCP servers are recommended for this repository:
+
+- **context7**: Provides up-to-date documentation for libraries and frameworks
+- **eslint**: Enables linting capabilities for code quality checks
+- **nx**: Offers Nx-specific commands and workspace insights
+
+These servers should be used when available to enhance development capabilities.
+
+### Available Templates
+
+- **`APPLICATION_ARCHITECTURE_FORMAT.md`**: Template for creating comprehensive architecture diagrams for AWS CDK services
+  - Provides guidelines for analyzing CDK application structure
+  - Includes Mermaid diagram formats with consistent color palettes
+  - Shows how to map Step Function workflows and Lambda functions
+  - Contains common architectural patterns and best practices
+
+- **`SERVICE_README_FORMAT.md`**: Template for creating service-specific README documentation
+  - Standardized format for service documentation
+  - Context diagram template showing external system interactions
+  - Sections for workflows, critical information, and operational details
+  - Consistent color palette for system visualization
+
+### When to Use
+
+Reference these templates when:
+- Creating new architecture documentation (`ARCHITECTURE.md`)
+- Documenting a new service with a README
+- Updating existing service documentation
+- Generating visual representations of service interactions
+- Ensuring consistency across all service documentation