📖 Guide 06 — CDK Infrastructure Deep Dive

What you’ll learn: Every CDK stack in EPICBackendCDK — what AWS resources they create, how they connect, and why.
Prerequisite: Read Guide 03 (TypeScript and CDK) first.

Section 1 — Infrastructure Overview

The EPICBackendCDK defines ALL the AWS infrastructure that EPIC runs on. Think of it as blueprints for the entire cloud system.

What gets created:

• 30+ DynamoDB tables
• 40+ SQS queues (including Dead Letter Queues)
• 5 SNS topics
• 100+ Lambda functions
• Multiple API Gateways (REST APIs)
• 1 VPC (Virtual Private Cloud)
• 1 RDS/Aurora MySQL cluster
• Multiple IAM roles and policies
• CloudWatch alarms and metrics
• S3 buckets (for Axon traffic data, FMBI data)

Section 2 — The Root: app.ts

app.ts is the entry point. It instantiates all stacks in the right order:

// Simplified app.ts
const app = new App();

// Core infrastructure (created first, others depend on these)
const vpcStack = new VpcStack(app, 'VPC', { stage, env });
const apiStack = new ApiStack(app, 'API', { 
    stage, env, 
    vpc: vpcStack.vpc 
});

// Feature stacks (use resources from apiStack)
const hotwStack = new HOTWLambdaStack(app, 'HOTW', {
    stage, env,
    vpc: vpcStack.vpc,
    fleetTable: apiStack.fleetTable,
    serviceTable: apiStack.serviceTable,
    eventTable: apiStack.eventTable,
    // ...
});

const fleetStack = new FleetLambdaStack(app, 'Fleet', {
    vpc: vpcStack.vpc,
    fleetTable: apiStack.fleetTable,
    // ...
});

// ... many more stacks

Why split into multiple stacks?

• Smaller stacks deploy faster
• Failures affect only one stack
• Teams can own different stacks
• Parallel deployment possible

Section 3 — Foundation Stacks

vpcStack.ts — Networking

Creates the VPC (Virtual Private Cloud) that isolates EPIC’s resources:

// All Lambda functions run inside this VPC for security
// No direct internet access — all traffic goes through NAT gateway
// Private subnets protect the database

What’s in the VPC:

• Public subnets (with NAT gateway for outbound internet)
• Private subnets (where Lambda functions and database live)
• Security groups (firewall rules)

rdsStack.ts — MySQL Database

Creates the Aurora MySQL cluster:

// MySQL database for HOTW operational data:
// - hotw_run
// - hotw_execution  
// - asg_details
// - capacity_override_details
// - fulfillment_details
// - preferred_asg

Why MySQL instead of DynamoDB for HOTW?

• HOTW data has complex relationships (runs → fleets → ASGs)
• SQL JOIN queries are easier than DynamoDB’s single-table design
• Aggregate queries (SUM, COUNT) are native in SQL

apiStack.ts — Core DynamoDB Tables and Queues ⭐

The most important stack — creates all DynamoDB tables and SQS queues.

DynamoDB Tables Created:

SQS Queues Created (30+ queues!):

Why FIFO queues?

• FIFO = First In, First Out (order guaranteed)
• Also: exactly-once delivery (no duplicate processing)
• Used for operations where order and uniqueness matter (hardware orders, milestone updates)

Why Dead Letter Queues (DLQ)?

• If a message fails 3 times, it goes to the DLQ
• Team gets alerted
• Can inspect the failed message and retry manually

Section 4 — Lambda Feature Stacks

Fleet/fleetLambdaStack.ts

Creates Lambda functions for Fleet CRUD:

• createFleetLambda → handler.Fleet.createFleet
• getFleetLambda → handler.Fleet.getFleet
• updateFleetConfigurationLambda → handler.Fleet.updateFleetConfiguration
• etc.

Each gets read/write access to FleetTable, ServiceTable, EventTable.

Service/serviceLambdaStack.ts

Creates Lambda functions for Service CRUD.

Event/eventLambdaStack.ts

Creates Lambda functions for Event CRUD.

EventPlan/eventPlanLambdaStack.ts

Creates Lambda functions for EventPlan milestone management.

Projections/projectionsLambdaStack.ts

Creates Lambda functions for traffic projections.

HOTW/HOTWLambdaStack.ts ⭐

Creates all HOTW-related Lambda functions and the HOTW API Gateway.

Lambda functions in HOTWLambdaStack:

createOrUpdateHotwRunDetailsLambda     → creates/updates HOTW run record
updateHotwRunDetailsLambda             → updates run with order type
createHotwExecutionDetailsLambda       → stores execution details
createOrUpdateDashboardDetailsLambda   → updates dashboard + ASG details
getHotwDashboardDetailsLambda          → fetches dashboard data
getAsgDetailsTableLambda               → gets ASG config for fleet
getHotwExecutionHistoryLambda          → gets run history
getAsgDetailsTableForRunIdLambda       → gets ASG details for specific run
storePreferredASGSLmda                 → saves preferred ASG list
getPreferredASGSLmda                   → gets preferred ASG list

API Gateway Routes in HOTWLambdaStack:

/hotw/asgsPreference/{EventId}/{FleetId}
    PUT → storePreferredASGSLmda
    GET → getPreferredASGSLmda

EPICApiStack.ts — Main API Gateway

The biggest API Gateway. Creates ALL the REST routes for the main EPIC API:

/service                        GET → getAllServices
/service/{ServiceId}            GET → getService, PUT → updateService, POST → createService
/fleet                          POST → createFleet
/fleet/{FleetId}/{EventId}      GET → getFleet, PUT → updateFleet
/event                          GET → getAllEvents, POST → createEvent
/event/{EventId}                GET → getEvent
/event/{EventId}/dashboard      PUT → getServiceReadinessDashboard
/eventplan/{EventId}/{FleetId}  GET/POST/PUT → EventPlan operations
/projection/{...}               GET/POST/PUT → Projection operations
/hotw/dashboard/{EventId}/{Purpose}  GET → getHotwDashboardDetails
/hotw/runDetail                 POST/PUT → run detail management
/hotw/executionDetail/...       POST/GET → execution detail management
/hotw/dashboardDetail           POST → dashboard detail management
/hotw/asgDetail/{FleetId}       GET → getAsgDetails
/hotw/asgsPreference/{EventId}/{FleetId}  GET/PUT → preferred ASGs
/throttling/{...}               GET/POST/PUT → throttling config
/ticket/{...}                   GET/POST/PUT → SIM ticket management
/calendar/{...}                 GET/POST/PUT → EPIC calendar
/pmet/{...}                     GET/POST/PUT → PMET metric links
/schema/{...}                   GET/POST/PUT → schema management
/exception/{...}                GET/POST/PUT → exception management
/bulkjobs/{...}                 POST → bulk operations

Section 5 — Trigger Stacks (Java Lambdas)

triggersStack.ts — Java Lambda Triggers ⭐

This is the most complex stack. Creates all the Java Lambda functions:

HOTW Triggers:

// Main HOTW handler
HotwHandler (SNS trigger from Milestone SNS)
    handleRequest(SNSEvent) → triggers HotwUpscalingHelper.handle()
    
// SPCO validation scheduler
ScheduleHotwForSpcoValidation (cron: weekly)
    handleSQSRequestForUpdateSpco() → queues all services+events

// SPCO executor (SQS consumer)
validateAndUpdateSPCOSQSQueue → HotwHandler.validateAndUpdateSpco()

// Atomic HOTW (API trigger)
atomicHOTWSQSQueue → HotwHandler.atomicHotwExecutor()

// HOTW Audit (SQS consumer)
HotwAuditSQSQueue → HotwHandler.auditHotw()
    → HotwUpscalingHelper.printDetailTable()

Apollo Triggers:

// Apollo data sync
ApolloSQSQueue → ApolloHandler
    → fetches latest host counts from Apollo API
    → updates FleetTable in DynamoDB
    → triggers milestone status updates

// Cron: daily Apollo sync
DailyApolloSync (cron: daily) → queues all fleets for Apollo refresh

FMC Triggers:

// FMC order status fetcher
FmcSQSQueue → FmcHandler
    → fetches latest order status from FMC API
    → updates fulfillment details in MySQL
    → triggers notifications

// Cron: periodic FMC sync
FmcTrigger (cron: every few hours)

BAU Scaling:

// BAU capacity scaling
BAUScaling → BAUScalingHandler
    → computes BAU host requirements
    → places BAU SPCO orders if needed

Milestone Handlers:

// Each milestone has a handler:
MilestoneSQSQueue → WorkflowHandler
    → routes to appropriate milestone handler based on milestone ID
    → GatherProjectionsMilestoneHandler
    → HardwareOrderMilestoneHandler
    → HardwareFulfillmentMilestoneHandler
    → CommunicateTPMMilestoneHandler
    → UpdateThrottlingMilestoneHandler

Section 6 — Other Important Stacks

apolloStack.ts

• ApolloExecutionHandler — fetches Apollo data per fleet
• ApolloTriggerHandler — scheduler for Apollo syncs

fmcStack.ts

• FmcHandler — fetches FMC order status
• FmcTriggerHandler — periodic FMC sync

milestoneWorkflowStack.ts

• WorkflowHandler — processes milestone SQS messages
• Routes to specific milestone handlers

bauScalingStack.ts

• BAUScalingHandler — processes BAU capacity needs
• BAUScalingTriggerLambda — scheduled trigger

scalingPlannerStack.ts

• ScalingPlannerHandler — manages EAP enrollment
• Creates capacity overrides in ScalingPlanner

throttlingStack.ts

• ThrottlingExecutor — applies Gizmo throttling configs
• Processes throttling SQS messages

simStack.ts

• SIM ticket creation and management
• CutOrUpdateTicketSQSQueue → SIM Lambda

axonStack.ts

• Axon traffic data ingestion
• AxonS3Handler — processes Axon data from S3
• AxonDependencyHandler — builds service dependency graph

pmetStack.ts

• PMET metric link management
• APIPMETHandler — fetches PMET data

resilienceStack.ts

• ResilienceDataHandler — collects resilience scores
• ResilienceGatherServicesLambda — gets service list

consensusStack.ts

• Consensus (approval) workflow
• ApprovalsHandler — processes approvals/rejections

athenaS3BucketStack.ts

• S3 bucket for Athena queries
• Used for analytics and reporting

fmbiS3BucketStack.ts

• S3 bucket for FMBI (Fleet Management Business Intelligence)
• Stores hardware order analytics data

Section 7 — Email Templates

Located in lib/EmailTemplates/, these are HTML email templates:

Section 8 — CloudWatch Monitoring

Monitors/Constants/alarmConstants.ts

Defines alarm names and ARNs for all critical metrics.

Monitors/Constants/metricConstants.ts

Defines custom CloudWatch metric names:

export const HOTW_SUCCESS_COUNT = "HOTWSuccessCount";
export const HOTW_FAILURE_COUNT = "HOTWFailureCount";
export const SPCO_ORDERS_PLACED = "SPCOOrdersPlaced";
export const MILESTONE_UPDATES = "MilestoneUpdates";

Monitors/monitorsShared.ts

Creates CloudWatch alarms:

// Lambda error rate alarm
new Alarm(this, 'HotwErrorAlarm', {
    metric: hotwLambda.metricErrors(),
    threshold: 5,
    evaluationPeriods: 1,
    alarmDescription: 'HOTW Lambda errors exceeded threshold',
});

Section 9 — ARC (Availability and Recovery Coordination)

// lib/ARC/arcConfig.ts
// lib/ARC/arcStack.ts

// ARC routing controls allow EPIC to redirect traffic between regions
// during outages or planned maintenance

Section 10 — Deployment Process

Developer commits code
    ↓
Brazil build system builds the package
    ↓
Brazil Pipelines (CDK Pipelines) deploys:
    ↓
Stage 1: BETA environment
    ↓ (automated tests pass)
Stage 2: GAMMA environment
    ↓ (manual approval)
Stage 3: PROD environment (IAD, PDX, DUB)

CDK commands:

# Synthesize (generate CloudFormation templates)
cdk synth

# Deploy a specific stack
cdk deploy HOTWStack

# Compare changes before deploying
cdk diff

# List all stacks
cdk ls

Section 11 — How Resources Connect

app.ts creates all stacks
│
├── VpcStack creates VPC
│   └── All Lambda stacks receive vpc: vpcStack.vpc
│
├── ApiStack creates DynamoDB tables and SQS queues
│   └── All feature stacks receive tables and queues as props
│
├── HOTWLambdaStack creates HOTW Lambdas
│   ├── receives: fleetTable, serviceTable, eventTable, eventPlanTable
│   └── creates: HOTW API Gateway + Lambda functions
│
├── TriggersStack creates Java Lambda Triggers
│   ├── receives: SNS topics, SQS queues
│   └── creates: HotwHandler, ApolloHandler, etc.
│
└── EPICApiStack creates main API Gateway
    ├── receives: all Lambda functions from feature stacks
    └── creates: REST API with all routes

Section 12 — Security Model

How Lambdas are secured:

1. VPC — Lambdas run in private subnets, no direct internet access
2. IAM roles — Each Lambda has minimum required permissions only
3. Security groups — Firewall rules between services
4. API Gateway IAM Auth — Frontend must assume a role to call APIs
5. Harmony account principal — Frontend accounts are explicitly trusted

IAM permission example:

// Only grant what's needed
props.fleetTable.grantReadData(getFleetLambda);        // read only
props.fleetTable.grantReadWriteData(createFleetLambda); // read+write
// NOT: grantFullAccess() — too permissive!

Section 13 — Key CDK Concepts Summary