AWS CDK

Our infrastructure is defined using the AWS Cloud Development Kit (CDK), allowing us to provision and manage cloud resources using TypeScript.

Stacks

The infrastructure is divided into several stacks to maintain separation of concerns:

• CoreStack: Foundations of the infrastructure.
  • VPC: Secure networking with public and private subnets.
  • Aurora Serverless v2 (PostgreSQL): Scalable relational database.
  • Valkey (Redis): In-memory data store for caching and queues.
• StorageStack: S3 buckets for file storage (public and private assets).
• ApplicationStack: The main application logic.
  • AWS App Runner: Hosting for containerized services (API, Workers).
  • API Gateway: Centralized entry point for the API.
  • AWS WAF: Web Application Firewall for security.
• BastionStack: EC2 Bastion host for secure access to the private database.
• ClientsStack: Frontend application hosting (S3 + CloudFront).
• DocsStack: Documentation hosting (S3 + CloudFront).
• PipelineStack: CI/CD roles and permissions.

Deployment Process

1. Prerequisites

Before deploying, ensure you have:

• AWS CLI installed and configured with an AWS Account.
• Node.js and pnpm installed.
• Docker running (required for building assets).
• Route53 Hosted Zone with a valid domain associated.
• AWS App Runner Connection (GitHub connection) configured.
• AWS WAF Captcha enabled/configured for security.

2. Configuration

Two configuration files are required in infra/aws/ to set up the environment. You can use the provided example files as a base.

Infrastructure Environment (.env)

Copy infra/aws/.env.example to infra/aws/.env.

This file controls the AWS resources to be provisioned. You mainly need to update:

• Route53: Your hosted zone ID and domain name (INFRA_DOMAIN_NAME, INFRA_HOSTED_ZONE_ID).
• App Runner Connection: The ARN for your GitHub connection (APP_RUNNER_CONNECTION_ARN).

Example:

INFRA_AWS_ACCOUNT=123456789012
INFRA_AWS_REGION=us-east-1
INFRA_DOMAIN_NAME=example.com
APP_RUNNER_CONNECTION_ARN=arn:aws:apprunner:...

Worker Environment (.env.workers)

Copy infra/aws/.env.workers.example to infra/aws/.env.workers.

This file controls the runtime application logic. These variables are injected directly into the App Runner containers.

• Application Config: NODE_ENV, APP_PORT, API_PREFIX.
• Feature Flags: SWAGGER_ENABLED, etc.
• Secrets: API Keys, JWT Secrets.

Example:

NODE_ENV=production
AUTH_JWT_SECRET=super-secret-key
SWAGGER_ENABLED=true

Note: Database credentials and internal hostnames are automatically injected by the CDK stack and do not need to be manually defined here.

3. Deploy

To deploy the entire infrastructure:

cd infra/aws
pnpm install
pnpm run build:infra && pnpm run deploy:all

You can also deploy specific stacks:

pnpm cdk deploy CoreStack
pnpm cdk deploy ApplicationStack

4. CI/CD Pipelines

The PipelineStack defines the Continuous Integration and Continuous Deployment (CI/CD) pipelines for the project.

Frontend Deployment

The frontend applications (Admin, Docs, Landing Page) have dedicated pipelines that automatically build and deploy changes to the respective S3 buckets and CloudFront distributions.

• Build Process: The pipeline installs dependencies, builds the static assets (React/Next.js), and optimizes them for production.
• Deployment: The built assets are synced to the S3 bucket defined in ClientsStack or DocsStack.
• Cache Invalidation: After deployment, the CloudFront distribution cache is invalidated to ensure users see the latest version immediately.