Development

Working with the infrastructure locally

The infrastructure project is a standard TypeScript-based AWS CDK application. Local development mainly consists of editing stack definitions, configuring environment variables, synthesising CloudFormation templates, and previewing changes before deployment.

To get started locally:

cd infrastructure/aws
npm install
cp .env.dist .env

Then update .env with the AWS account, region, and stack-specific configuration for the environment you want to work with.

Environment configuration

infrastructure/aws/.env holds the deployment configuration used by the CDK app.

At a minimum, you will usually configure values such as:

AWS_ACCOUNT_ID=123456789012
AWS_REGION=eu-west-1
ENVIRONMENT=dev
ENABLE_DELETION_PROTECTION=false

Additional variables control repository names, domain settings, build paths, and application-specific configuration for the Core, Web, and Admin stacks.

Project structure

The main project structure looks like this:

infrastructure/aws/
  bin/
	app.ts
  lib/
	core-stack.ts
	web-stack.ts
	admin-stack.ts
	domain.ts
  lambda/
	core-stack/
	  deployment-trigger.ts
	web-stack/
	  deployment-trigger.ts
  cdk.json
  .env.dist
  package.json

• bin/app.ts: CDK entry point that instantiates the stacks
• lib/core-stack.ts: shared backend platform resources such as VPC, RDS, Redis, and the API service
• lib/web-stack.ts: Web hosting resources
• lib/admin-stack.ts: Admin hosting resources
• lib/domain.ts: shared domain and certificate helpers
• lambda/*: deployment trigger functions used by the stacks

Useful commands

• npm run cdk diff: preview infrastructure changes before deploying
• npm run cdk synth: synthesise the CloudFormation templates
• npm run cdk deploy --all: deploy all stacks
• npm run cdk deploy core: deploy the Core stack only
• npm run cdk deploy web: deploy the Web stack only
• npm run cdk deploy admin-hosting: deploy the Admin stack only
• npm run cdk destroy --all: destroy all deployed stacks
• npm run watch: compile TypeScript in watch mode

CDK bootstrap

When deploying to an AWS account and region for the first time, bootstrap CDK first:

cdk bootstrap aws://<ACCOUNT_ID>/<REGION>

This creates the CDK toolkit resources needed for later deployments.

Previewing changes

Before deploying infrastructure changes, it is good practice to inspect both the diff and the synthesised templates:

npm run cdk diff
npm run cdk synth

This makes it easier to catch unintended resource creation, deletion, or replacement before applying changes to AWS.