aws-webapp-infra

AWS CDK application written in Java that provisions a complete serverless web application infrastructure with authentication, database, email services, and API Gateway for building modern web applications.

Overview

This CDK application provisions a complete serverless web application infrastructure with five main components, designed to integrate seamlessly with the Fastish platform services. The architecture follows AWS Serverless Application Lens best practices.

System Architecture

flowchart TB
    subgraph "Public Subnet"
        IGW[Internet Gateway]
        NAT[NAT Gateway]
    end

    subgraph "Private Subnet"
        subgraph "Authentication"
            COG[Cognito User Pool]
            COGCLIENT[App Client]
        end

        subgraph "API Layer"
            APIGW[API Gateway]
            AUTH[Cognito Authorizer]
            LAMBDA[Lambda Functions]
        end

        subgraph "Data Layer"
            DDB[(DynamoDB Tables)]
        end
    end

    subgraph "Edge Services"
        SES[SES Email Service]
        R53[Route 53 DNS]
    end

    Client([Client]) --> IGW
    IGW --> APIGW
    APIGW --> AUTH
    AUTH --> COG
    APIGW --> LAMBDA
    LAMBDA --> DDB
    COG --> SES
    SES --> R53
    LAMBDA --> NAT
    NAT --> IGW

Request Flow

sequenceDiagram
    participant Client
    participant APIGW as API Gateway
    participant Auth as Cognito Authorizer
    participant Lambda as Lambda Function
    participant DDB as DynamoDB

    Client->>APIGW: HTTPS Request + JWT
    APIGW->>Auth: Validate Token
    Auth->>Auth: Verify JWT Signature
    Auth-->>APIGW: Claims + Context

    APIGW->>Lambda: Invoke with Context
    Lambda->>DDB: Query/Update
    DDB-->>Lambda: Results
    Lambda-->>APIGW: Response
    APIGW-->>Client: JSON Response

Infrastructure Components

1. Network (VPC)

The network layer establishes isolated cloud infrastructure following AWS VPC best practices:

flowchart TB
    subgraph "VPC (10.0.0.0/16)"
        subgraph "AZ-a"
            PUB_A[Public Subnet<br/>10.0.0.0/24]
            PRIV_A[Private Subnet<br/>10.0.2.0/24]
        end

        subgraph "AZ-b"
            PUB_B[Public Subnet<br/>10.0.1.0/24]
            PRIV_B[Private Subnet<br/>10.0.3.0/24]
        end

        IGW[Internet Gateway]
        NAT_A[NAT Gateway A]
        NAT_B[NAT Gateway B]
    end

    Internet([Internet]) --> IGW
    IGW --> PUB_A
    IGW --> PUB_B
    PUB_A --> NAT_A
    PUB_B --> NAT_B
    NAT_A --> PRIV_A
    NAT_B --> PRIV_B

Component	Purpose	Reference
Public Subnets	Host NAT gateways and internet-facing resources	VPC Subnets
Private Subnets	Isolate backend resources (Cognito, Lambda functions)	Private Subnets
Internet Gateway	Enable outbound internet access	Internet Gateways
NAT Gateways	Allow private subnet resources to access the internet	NAT Gateways
Route Tables	Manage traffic flow between subnets and internet	Route Tables

2. Authentication (Cognito)

User authentication and identity management powered by Amazon Cognito:

flowchart LR
    subgraph "User Pool"
        POOL[Cognito User Pool]
        MFA[MFA Configuration]
        PWD[Password Policy]
        ATTR[User Attributes]
    end

    subgraph "App Integration"
        CLIENT[App Client]
        DOMAIN[Hosted UI Domain]
        CALLBACK[Callback URLs]
    end

    subgraph "Triggers"
        PRE[Pre Sign-up]
        POST[Post Confirmation]
        CUSTOM[Custom Message]
    end

    POOL --> CLIENT
    POOL --> MFA
    POOL --> PWD
    POOL --> ATTR
    CLIENT --> DOMAIN
    CLIENT --> CALLBACK
    POOL --> PRE
    POOL --> POST
    POOL --> CUSTOM

Feature	Configuration	Reference
User Pool	Manages user registration, authentication, and profile data	User Pools
Password Policy	Enforces minimum length of 8 characters	Password Policies
MFA Configuration	Supports optional multi-factor authentication	MFA
Standard Attributes	Email (required and mutable)	User Attributes
Email Verification	Automated via SES integration	Email Verification
Account Recovery	Email-based password reset flow	Account Recovery
VPC Integration	Deployed in private subnets for enhanced security	Lambda Triggers

3. Database (DynamoDB)

NoSQL data storage using Amazon DynamoDB:

flowchart TB
    subgraph "DynamoDB Table"
        PK[Partition Key]
        SK[Sort Key]

        subgraph "Item Collection"
            I1[Item 1]
            I2[Item 2]
            I3[Item 3]
        end

        subgraph "GSI"
            GSI1[Global Secondary Index]
        end
    end

    subgraph "Features"
        TTL[TTL Expiration]
        PITR[Point-in-Time Recovery]
        STREAM[DynamoDB Streams]
    end

    PK --> I1
    PK --> I2
    PK --> I3
    SK --> I1
    SK --> I2
    SK --> I3
    I1 --> GSI1
    I2 --> GSI1
    I3 --> GSI1

Feature	Configuration	Reference
Tables	NoSQL tables for application data storage	Core Components
Partition Keys	Optimized for access patterns	Partition Key Design
Billing Mode	Pay-per-request (on-demand) or provisioned capacity	Read/Write Capacity
Encryption	Server-side encryption at rest enabled by default	Encryption at Rest
Point-in-Time Recovery	Optional backup and restore capability	PITR
Global Secondary Indexes	Additional query patterns as needed	GSI

4. Email Service (SES)

Transactional email delivery via Amazon SES:

flowchart LR
    subgraph "Domain Verification"
        DOMAIN[Domain Identity]
        DKIM[DKIM Records]
        SPF[SPF Record]
        DMARC[DMARC Policy]
    end

    subgraph "Route 53"
        R53[Hosted Zone]
        MX[MX Records]
        TXT[TXT Records]
        CNAME[CNAME Records]
    end

    subgraph "Email Flow"
        COG[Cognito Triggers]
        LAMBDA[Lambda Functions]
        SES[SES API]
    end

    DOMAIN --> R53
    DKIM --> CNAME
    SPF --> TXT
    DMARC --> TXT

    COG --> SES
    LAMBDA --> SES
    SES --> DOMAIN

Feature	Configuration	Reference
Domain Identity	Verifies your domain for sending emails	Domain Verification
Email Identity	Verifies specific email addresses	Email Verification
DKIM Signing	Authenticates emails to prevent spoofing	DKIM
Route 53 Integration	Automatically creates required DNS records	Route 53 DNS
Sending Authorization	IAM policies for secure email sending	Authorization

5. API Gateway

RESTful API infrastructure using Amazon API Gateway:

flowchart TB
    subgraph "API Gateway"
        REST[REST API]

        subgraph "Resources"
            R1[/users]
            R2[/orders]
            R3[/products]
        end

        subgraph "Methods"
            GET[GET]
            POST[POST]
            PUT[PUT]
            DELETE[DELETE]
        end

        subgraph "Integration"
            AUTH[Cognito Authorizer]
            LAMBDA[Lambda Proxy]
            MOCK[Mock Integration]
        end
    end

    subgraph "Stages"
        DEV[dev]
        STAGING[staging]
        PROD[prod]
    end

    REST --> R1
    REST --> R2
    REST --> R3
    R1 --> GET
    R1 --> POST
    R2 --> GET
    R2 --> PUT
    R3 --> DELETE

    GET --> AUTH
    POST --> AUTH
    AUTH --> LAMBDA

    REST --> DEV
    REST --> STAGING
    REST --> PROD

Feature	Configuration	Reference
REST API	HTTP endpoints for client-server communication	REST APIs
Cognito Authorizer	Validates JWT tokens from Cognito user pool	Cognito Authorizer
Lambda Integration	Routes requests to backend Lambda functions	Lambda Integration
CORS Configuration	Enables cross-origin requests from web clients	CORS
Deployment Stages	Separate environments (dev, staging, prod)	Stages
Request Validation	Schema-based validation of API requests	Request Validation
Usage Plans	Optional rate limiting and throttling	Usage Plans

Stack Architecture

The webapp infrastructure uses a layered architecture with CloudFormation nested stacks:

flowchart TB
    subgraph "DeploymentStack (main)"
        MAIN[Main Stack]
    end

    subgraph "Nested Stacks"
        NET[NetworkNestedStack]
        SES[SesNestedStack]
        AUTH[AuthNestedStack]
        DB[DbNestedStack]
        API[ApiNestedStack]
    end

    MAIN --> NET
    MAIN --> SES
    MAIN --> AUTH
    MAIN --> DB
    MAIN --> API

    SES -.->|depends on| AUTH
    AUTH -.->|depends on| API

Dependency Chain:

Network and SES are created first (independent)
Auth waits for SES (email verification dependency)
API waits for Auth (Cognito authorizer dependency)
DB is created independently

Platform Integration

When deployed through the Fastish platform, this infrastructure integrates with internal platform services for automated deployment and management.

Platform Component	Integration Point	Purpose
Orchestrator	Release pipeline automation	Automated CDK synthesis and deployment via CodePipeline
Portal	Subscriber management	Tenant provisioning and access control
Network	Shared VPC peering	Cross-stack connectivity for platform services
Reporting	Usage metering	Pipeline execution tracking and cost attribution

These integrations are managed automatically when deploying via the platform's release workflows.

Prerequisites

Requirement	Version	Installation	Verification
Java	21+	SDKMAN	`java --version`
Maven	3.8+	Maven Download	`mvn --version`
AWS CLI	2.x	AWS CLI Install	`aws --version`
AWS CDK CLI	2.221.0+	CDK Getting Started	`cdk --version`
GitHub CLI	Latest	GitHub CLI	`gh --version`

Additional Requirements:

Registered domain in Route 53 for SES integration
AWS account bootstrapped for CDK:

cdk bootstrap aws://<account-id>/<region>

Replace <account-id> with your AWS account ID and <region> with your desired AWS region (e.g., us-west-2). This sets up necessary resources for CDK deployments including an S3 bucket for assets and CloudFormation execution roles. See: CDK Bootstrapping | Bootstrap CLI Reference

Deployment

Step 1: Clone Repositories

gh repo clone fast-ish/cdk-common
gh repo clone fast-ish/aws-webapp-infra

Step 2: Build Projects

mvn -f cdk-common/pom.xml clean install
mvn -f aws-webapp-infra/pom.xml clean install

Step 3: Setup Local Maven Repository Symlink

The infrastructure configuration references Lambda function artifacts from the Maven local repository at /root/.m2/repository. This path works in AWS CodePipeline (which runs as root), but locally your Maven repository is at ~/.m2/repository.

To ensure the same configuration works in both environments:

sudo ln -s ~/.m2 /root/.m2

Environment	Maven Repository Path	Notes
Local Development	`~/.m2/repository`	User home directory
AWS CodePipeline	`/root/.m2/repository`	Runs as root user

Step 4: Configure Deployment

Create aws-webapp-infra/infra/cdk.context.json from aws-webapp-infra/infra/cdk.context.template.json:

Required Configuration Parameters:

Parameter	Description	Example
`:account`	AWS account ID (12-digit number)	`123456789012`
`:region`	AWS region for deployment	`us-west-2`
`:domain`	Registered domain in Route 53 for SES	`example.com`
`:ses:hosted:zone`	Route 53 hosted zone ID for DNS records	`Z1234567890ABC`
`:ses:email`	Email address for SES verification	`[email protected]`
`:environment`	Environment name (do not change)	`prototype`
`:version`	Resource version identifier	`v1`

Notes:

:environment and :version map to resource files at aws-webapp-infra/infra/src/main/resources/prototype/v1
Domain must be registered and hosted in Route 53 before deployment
Email address will receive a verification link from SES

Step 5: Deploy Infrastructure

cd aws-webapp-infra/infra

# Preview changes
cdk synth

# Deploy all stacks
cdk deploy

See: CDK Deploy Command | CDK Synth Command

What Gets Deployed:

Resource Type	Count	Description	Reference
CloudFormation Stacks	6	1 main + 5 nested stacks	Nested Stacks
VPC	1	2 AZs, public/private subnets	VPC Documentation
Cognito User Pool	1	With VPC endpoints	Cognito User Pools
DynamoDB Tables	Variable	As defined in configuration	DynamoDB Tables
SES Identities	2	Domain + email with DKIM	SES Identities
API Gateway	1	With Lambda integrations	REST APIs

Step 6: Verify SES Email

After deployment completes:

Check the email inbox for :ses:email
Click the verification link from Amazon SES
Confirmation is required before Cognito can send emails

See: SES Email Verification

Configuration Reference

CDK Context Variables

The build process uses Mustache templating to inject context variables into configuration files. See cdk-common for the complete build process documentation.

Variable	Type	Description
`{{account}}`	String	AWS account ID
`{{region}}`	String	AWS region
`{{domain}}`	String	Route 53 domain
`{{environment}}`	String	Environment name
`{{version}}`	String	Resource version

Template Structure

src/main/resources/
└── prototype/
    └── v1/
        ├── conf.mustache           # Main configuration
        ├── network/
        │   └── vpc.mustache        # VPC configuration
        ├── auth/
        │   └── cognito.mustache    # Cognito configuration
        ├── db/
        │   └── dynamodb.mustache   # DynamoDB configuration
        ├── ses/
        │   └── ses.mustache        # SES configuration
        └── api/
            └── gateway.mustache    # API Gateway configuration

Security Considerations

Layer	Implementation	Reference
Network	Private subnets, security groups, NACLs	VPC Security
Authentication	Cognito JWT validation, MFA support	Cognito Security
API	Request validation, throttling, WAF integration	API Gateway Security
Data	DynamoDB encryption at rest, IAM policies	DynamoDB Security
Email	DKIM, SPF, DMARC	SES Authentication

Troubleshooting

For common deployment issues and resolutions, see the Troubleshooting Guide.

Quick Diagnostics

# Check stack status
aws cloudformation describe-stacks --stack-name <stack-name> --query 'Stacks[0].StackStatus'

# View recent stack events
aws cloudformation describe-stack-events --stack-name <stack-name> --query 'StackEvents[0:5]'

# Test API Gateway endpoint
curl -I $(aws cloudformation describe-stacks --stack-name <stack-name> \
  --query 'Stacks[0].Outputs[?OutputKey==`ApiEndpoint`].OutputValue' --output text)

# Check Cognito User Pool status
aws cognito-idp describe-user-pool --user-pool-id <pool-id> --query 'UserPool.Status'

License

MIT License

For your convenience, you can find the full MIT license text at:

https://opensource.org/license/mit/ (Official OSI website)
https://choosealicense.com/licenses/mit/ (Choose a License website)

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.github		.github
fn		fn
infra		infra
releases		releases
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CHECKSTYLE_SETUP.md		CHECKSTYLE_SETUP.md
COMMIT_CONVENTIONS.md		COMMIT_CONVENTIONS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
LOCAL_VALIDATION.md		LOCAL_VALIDATION.md
Makefile		Makefile
README.md		README.md
RELEASE_GUIDE.md		RELEASE_GUIDE.md
RELEASING.md		RELEASING.md
USAGE.md		USAGE.md
build-release.sh		build-release.sh
checkstyle.xml		checkstyle.xml
dependency-check-suppressions.xml		dependency-check-suppressions.xml
eclipse-formatter.xml		eclipse-formatter.xml
pom.xml		pom.xml
renovate.json		renovate.json
spotbugs-exclude.xml		spotbugs-exclude.xml

Resource	Description
Fastish Documentation	Main documentation hub
Troubleshooting	Common issues and resolutions
Deployment Validation	Post-deployment health checks
Upgrade Guide	Version upgrade procedures
Capacity Planning	Sizing recommendations
IAM Permissions	Required IAM policies
Network Requirements	CIDR and port requirements

Resource	Description
cdk-common	Shared CDK constructs library
AWS CDK Developer Guide	Official CDK documentation
AWS CDK API Reference	CDK construct API reference
AWS Well-Architected Framework	Architecture best practices
Serverless Application Lens	Serverless-specific guidance
CloudFormation User Guide	CloudFormation documentation
Lambda Developer Guide	AWS Lambda documentation
DynamoDB Developer Guide	DynamoDB documentation
API Gateway Developer Guide	API Gateway documentation

License

fast-ish/aws-webapp-infra

Folders and files

Latest commit

History

Repository files navigation

aws-webapp-infra

Overview

System Architecture

Request Flow

Infrastructure Components

1. Network (VPC)

2. Authentication (Cognito)

3. Database (DynamoDB)

4. Email Service (SES)

5. API Gateway

Stack Architecture

Platform Integration

Prerequisites

Deployment

Step 1: Clone Repositories

Step 2: Build Projects

Step 3: Setup Local Maven Repository Symlink

Step 4: Configure Deployment

Step 5: Deploy Infrastructure

Step 6: Verify SES Email

Configuration Reference

CDK Context Variables

Template Structure

Security Considerations

Troubleshooting

Quick Diagnostics

Related Documentation

Platform Documentation

AWS Documentation

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Packages