Production-ready AI/ML platform with AWS Bedrock integration, weather intelligence, and modern web UI

A FedRAMP-compliant, multi-environment application platform featuring serverless Lambda functions, AI/ML capabilities via AWS Bedrock, and real-time weather intelligence with a modern React UI.

The Fearless Factory Accelerator provides two complementary approaches for infrastructure deployment:

Best for: New applications, rapid deployment, consistent standards

Define your application in a YAML manifest, then automatically generate production-ready Terraform infrastructure:

# 1. Choose or create a manifest
cp orchestration/examples/multi-tier-complex.yaml my-app.yaml

# 2. Generate Terraform infrastructure
cd generator
python3 generate_terraform.py ../my-app.yaml ../output/my-app/ --environment dev

# 3. Deploy to AWS
cd ../output/my-app/
terraform init
terraform plan
terraform apply

Benefits:

• ⚡ Fast: Infrastructure in minutes, not hours
• 📋 Consistent: Standardized naming, tagging, security
• 🎯 Simple: Describe what you want, not how to build it
• ✅ Validated: Schema validation catches errors early

Learn More:

• 📖 Manifest-Driven Guide - Complete documentation
• 📝 Example Manifests - Working examples
• 🔄 Comparison Doc - Traditional vs. Manifest approaches

Best for: Existing infrastructure, custom requirements, advanced users

Manually configure and deploy Terraform for full control over every resource:

# Bootstrap state backend (one-time)
cd terraform/bootstrap
terraform init && terraform apply

# Deploy environment
cd ../environments/dev
terraform init && terraform plan && terraform apply

When to Use:

• You need fine-grained control over specific resources
• You're working with existing Terraform infrastructure
• You have custom requirements not covered by manifests
• You're an advanced Terraform user

Continue to Prerequisites section below for detailed setup.

This project has evolved through several phases:

1. Phase 1 (Original): Manual Terraform infrastructure

   • Located in terraform/ directory
   • Direct resource configuration
   • Full control, more complexity

2. Phase 2 (Current): Manifest-driven generation

   • Define apps in YAML (orchestration/)
   • Generate Terraform automatically (generator/)
   • Faster, more consistent, less error-prone

3. Phase 3 (Future): Full orchestration API

   • Self-service deployment portal
   • Approval workflows
   • Centralized tracking

Essential Reading (Priority Order):

• Start Here: orchestration/README.md - Understand manifest-driven approach
• Examples: orchestration/examples/ - See working manifests
• Generator: generator/README.md - Learn the generation tool
• Comparison: FACTORY_IAC_GENERATION_COMPARISON.md - Why we evolved

Getting Your Environment Set Up:

# 1. Install prerequisites
./scripts/install-tools.sh

# 2. Configure AWS
aws configure

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your settings
source .env

# 4. Try generating infrastructure from a manifest
cd generator
python3 generate_terraform.py \
  ../orchestration/examples/multi-tier-complex.yaml \
  ../output/test/ \
  --environment dev

Q: Which approach should I use for a new project?
A: Use the manifest-driven approach (Option 1). It's faster, more consistent, and includes best practices by default.

Q: Can I customize the generated Terraform?
A: Yes! The generator creates standard Terraform files you can modify. For extensive customization, you can also extend the generator templates.

Q: What if I need something not in the manifest schema?
A: You have three options:

1. Generate infrastructure, then manually add custom resources
2. Request schema enhancements (if the need is common)
3. Use direct Terraform (Option 2) for full control

Q: Where do I find examples?
A: Check orchestration/examples/ for working manifests:

• multi-tier-complex.yaml - Full-featured enterprise app
• app-orchestrator-demo-manifest.yaml - Simple demo

The project supports two deployment paths from manifest to infrastructure:

┌─────────────────────────────────────────────────┐
│  Developer Creates Manifest (YAML)              │
│  - Application requirements                      │
│  - Infrastructure specifications                 │
│  - Environment configurations                    │
└────────────────────┬────────────────────────────┘
                     │
         ┌───────────┴───────────┐
         │                       │
         ▼                       ▼
┌──────────────────┐    ┌──────────────────┐
│ Manual Generator │    │ Orchestration    │
│ (Fast, Local)    │    │ API (Governed)   │
│ See generator/   │    │ See orchestration/│
└────────┬─────────┘    └────────┬─────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
         ┌─────────────────────┐
         │ Generated Terraform │
         │ (in output/ dir)    │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │ AWS Infrastructure  │
         │ - VPC, Lambda, etc. │
         └─────────────────────┘

Once deployed, the application runs with this architecture:

┌─────────────────────────────────────────────────┐
│  React UI (CloudFront + S3)                     │
│  - Weather dashboard with AI chat               │
│  - Real-time forecasts and alerts               │
└────────────────────┬────────────────────────────┘
                     │ HTTPS
                     ▼
┌─────────────────────────────────────────────────┐
│  API Gateway + WAF                              │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│  Lambda (Python 3.11 - FastAPI)                 │
│  - /ai/* endpoints (Bedrock AI/ML)              │
│  - /weather/* endpoints (NWS + AI)              │
│  - /health (monitoring)                         │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
            AWS Bedrock (Claude Models)
            National Weather Service API

• Frontend: React/TypeScript UI with Tailwind CSS v4, hosted on CloudFront + S3
• Backend: Python FastAPI on Lambda for AI and weather services
• VPC: Multi-AZ VPC with public and private subnets
• Security: KMS encryption, AWS Secrets Manager, CloudTrail, GuardDuty, AWS Config, Security Hub
• Compute: AWS Lambda for serverless functions
• API: API Gateway for RESTful APIs with WAF protection
• AI/ML: AWS Bedrock for generative AI capabilities (Claude models)
• Weather: National Weather Service API integration with caching
• CDN: CloudFront for global UI distribution
• Storage: S3 buckets with versioning and lifecycle policies
• Monitoring: CloudWatch Logs, Metrics, and Alarms
• Networking: NAT Gateways, VPC Endpoints, Network ACLs

• dev: Development environment (single-AZ, minimal resources)
• test: Testing environment (multi-AZ, moderate resources)
• prod: Production environment (multi-AZ, HA, scaled resources)

A production-ready FastAPI application providing REST API access to AWS Bedrock AI/ML capabilities.

• AI Chat: Conversational AI with Claude 3.5 Sonnet, Claude 3 Haiku, Claude 3 Sonnet
• Text Embeddings: Semantic search with Amazon Titan
• Model Discovery: List and query available Bedrock models
• OpenAPI Integration: Automatic spec generation for Stoplight.ai
• Secure by Design: Input validation, structured error handling
• Observability: JSON logging, CloudWatch metrics
• FedRAMP Aligned: Compliance controls built-in

AI Services (/ai):

GET  /ai/models        - List available Bedrock models
POST /ai/chat          - Conversational AI (Claude models)
POST /ai/embeddings    - Text embeddings (Titan)

Weather Services (/weather):

GET  /weather/forecast?zip_code=10001  - 7-day weather forecast
GET  /weather/alerts?zip_code=10001    - Active weather alerts
POST /weather/chat                     - AI weather conversation
POST /weather/advice                   - Personalized weather advice

System:

GET  /health           - Health check
GET  /openapi.json     - OpenAPI specification
GET  /docs             - Interactive API docs (Swagger UI)
GET  /redoc            - Alternative API docs (ReDoc)

Local Development:

cd app
pip install -r requirements.txt
python main.py
# Access http://localhost:8000/docs

Deploy to AWS:

# Automatic: Push changes to app/ directory
cd app
# Make changes...
git add app/
git commit -m "feat: Update FastAPI"
git push origin feature/cline_generation_az  # Or your branch

# The unified pipeline will automatically:
# - Detect app/ changes
# - Build Docker image
# - Deploy to Lambda

Get API Endpoint (No Terraform Required):

# Get API Gateway ID from AWS
API_ID=$(aws apigateway get-rest-apis \
  --query 'items[?name==`dev-mes-accelerator-demo-api`].id' \
  --output text)

# Construct endpoint URL
API_ENDPOINT="https://${API_ID}.execute-api.us-east-1.amazonaws.com/dev"
echo "API Endpoint: $API_ENDPOINT"

# Or use the direct endpoint if you know it:
API_ENDPOINT="https://555jtireoa.execute-api.us-east-1.amazonaws.com/dev"

Test FastAPI Bedrock Endpoints:

# Health check
curl "$API_ENDPOINT/health" | jq .

# List available AI models (Claude, Titan)
curl "$API_ENDPOINT/ai/models" | jq .

# Interactive Swagger UI documentation
open "$API_ENDPOINT/docs"

# Chat with Claude 3.5 Sonnet
curl -X POST "$API_ENDPOINT/ai/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain serverless architecture benefits",
    "model_id": "anthropic.claude-3-5-sonnet-20241022-v2:0"
  }' | jq .

# Generate text embeddings
curl -X POST "$API_ENDPOINT/ai/embeddings" \
  -H "Content-Type: application/json" \
  -d '{"text": "Machine learning and AI"}' | jq .

# Get OpenAPI specification
curl "$API_ENDPOINT/openapi.json" | jq . > openapi.json

• 📖 Quick Start Guide: docs/QUICK_START.md
• 📖 Deployment Guide: docs/DEPLOYMENT.md
• 📖 Stoplight Integration: docs/STOPLIGHT_INTEGRATION.md
• 📖 App Documentation: app/README.md

Run the installation script to install all required tools:

./scripts/install-tools.sh

This installs:

• Terraform (>= 1.5.0)
• AWS CLI v2
• Docker
• Python 3.11+
• pre-commit
• jq
• terraform-docs
• tfsec
• checkov
• tflint

1. AWS Credentials: Configure AWS CLI with appropriate credentials

   aws configure

2. Required Permissions: Your AWS user/role needs permissions to create:

   • VPC, Subnets, Route Tables, NAT Gateways
   • S3 Buckets
   • Lambda Functions
   • API Gateway REST APIs
   • KMS Keys
   • Secrets Manager Secrets, SSM Parameters
   • IAM Roles and Policies
   • CloudTrail, GuardDuty, AWS Config, Security Hub
   • CloudWatch Log Groups

IMPORTANT: Set up environment variables before running Terraform to avoid unexpected state changes.

1. Create Local Environment File: Copy the example file and configure your values

   cp .env.example .env

2. Configure Required Variables: Edit .env and set the required Terraform variables. Variables prefixed with TF_VAR_ are automatically picked up by Terraform.

   Critical for CI/CD Module - Add the GitHub token secret ARN if you need webhook integration:

   # Add to your .env file
   export TF_VAR_github_token_secret_arn="arn:aws:secretsmanager:us-east-1:YOUR_ACCOUNT_ID:secret:dev/mes-demo/github-token-XXXXX"  # pragma: allowlist secret

   Note: Without this variable, Terraform will plan to destroy the aws_codebuild_source_credential resource and remove GitHub webhook authentication from your CodeBuild projects.

3. Load Environment Variables: Before running any Terraform commands, source the environment file:

   source ./.env

   This loads all environment variables into your current shell session. You'll need to run this command in each new terminal session.

4. Verify Variables Are Set: Confirm your Terraform variables are loaded:

   # Check if GitHub token ARN is set
   echo $TF_VAR_github_token_secret_arn

Why This Matters: Terraform uses conditional resource creation based on these variables. Missing variables can cause Terraform to plan unexpected resource deletions, particularly for CI/CD resources like GitHub webhooks and source credentials.

The easiest way to set up the Terraform infrastructure is using the automated setup script:

# Make the script executable (if not already)
chmod +x setup-terraform.sh

# Run the automated setup
./setup-terraform.sh

The script will:

1. ✅ Check prerequisites (Terraform, AWS CLI, AWS credentials)
2. ✅ Display your AWS account and region
3. ✅ Create or verify the Terraform backend (S3 + DynamoDB)
4. ✅ Initialize the dev environment
5. ✅ Provide next steps for deployment

What it handles for you:

• Detects if backend already exists (won't recreate)
• Provides clear colored output with progress indicators
• Handles errors gracefully with helpful messages
• Gives you the option to skip existing infrastructure

After the script completes, you can proceed with deploying your infrastructure:

cd terraform/environments/dev
terraform plan
terraform apply

If you prefer to run the setup steps manually, follow these instructions:

IMPORTANT: Run this ONCE before any environment deployment:

cd terraform/bootstrap
terraform init
terraform plan
terraform apply

# Save outputs for reference
terraform output -json > bootstrap-outputs.json

IMPORTANT: Load your environment variables before deploying:

# From the project root, load environment variables
source ./.env

# Verify critical variables are set
echo $TF_VAR_github_token_secret_arn

cd terraform/environments/dev

# Initialize Terraform
terraform init

# Review the plan
terraform plan

# Apply the infrastructure
terraform apply

# Save outputs
terraform output -json > outputs.json

Note: If you see unexpected resource deletions in the plan (especially aws_codebuild_source_credential), verify your environment variables are properly loaded with source ./.env.

After successful deployment, test your API endpoints:

# Get the API Gateway endpoint URL
API_ENDPOINT=$(terraform output -raw api_gateway_endpoint)

# Test the health check endpoint (public - no authentication required)
curl $API_ENDPOINT/health

# Expected response:
# {"success":true,"status":"healthy","environment":"dev","service":"lambda-api-handler","version":"1.0.0"}

Testing the /hello Endpoint (API Key Required):

The /hello endpoint is protected with API key authentication for security. Retrieve and use the API key:

# Option 1: Get API key from Secrets Manager (recommended)
API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id dev/api-gateway/hello-api-key \
  --query SecretString --output text | jq -r '.api_key_value')

# Option 2: Get API key from Terraform output
API_KEY=$(terraform output -raw api_key_value)

# Test the hello endpoint with API key
curl -H "x-api-key: $API_KEY" "$API_ENDPOINT/hello"

# Expected response:
# {"success":true,"message":"Hello, World!","environment":"dev"}

# Test with custom name parameter
curl -H "x-api-key: $API_KEY" "$API_ENDPOINT/hello?name=John"

# Expected response:
# {"success":true,"message":"Hello, John!","environment":"dev"}

# Test without API key (should fail with 403 Forbidden)
curl "$API_ENDPOINT/hello"

# Expected response:
# {"message":"Forbidden"}

View Complete API Key Details:

# View all API key metadata from Secrets Manager
aws secretsmanager get-secret-value \
  --secret-id dev/api-gateway/hello-api-key \
  --query SecretString --output text | jq '.'

# Output includes:
# {
#   "api_key_id": "...",
#   "api_key_value": "...",
#   "api_key_name": "dev-mes-accelerator-demo-hello-api-key",  # pragma: allowlist secret
#   "endpoint": "/hello",
#   "description": "API key for accessing the /hello endpoint",
#   "created_date": "..."
# }

View Lambda Logs:

# Get the Lambda function name
FUNCTION_NAME=$(terraform output -raw lambda_function_name)

# View recent logs
aws logs tail /aws/lambda/$FUNCTION_NAME --follow

Retrieve Secrets (stored in Secrets Manager):

# Get application API keys (for external services)
aws secretsmanager get-secret-value \
  --secret-id dev/app/api-keys \
  --query SecretString --output text | jq '.'

# Get API Gateway API key (for /hello endpoint)
aws secretsmanager get-secret-value \
  --secret-id dev/api-gateway/hello-api-key \
  --query SecretString --output text | jq '.'

fearless-factory-accelerator/
├── generator/              # 🆕 Manifest → Terraform Generator
│   ├── generate_terraform.py    # CLI entry point
│   ├── terraform_generator.py   # Core generation logic
│   ├── manifest_parser.py       # YAML manifest parser
│   ├── sizing_calculator.py     # Resource sizing algorithms
│   ├── requirements.txt         # Python dependencies
│   ├── templates/              # Jinja2 templates
│   │   ├── main.tf.j2          # Main Terraform file
│   │   ├── variables.tf.j2     # Variable definitions
│   │   ├── outputs.tf.j2       # Output values
│   │   └── backend.tf.j2       # S3 backend config
│   └── README.md               # Generator documentation
│
├── orchestration/          # 🆕 Orchestration Layer
│   ├── README.md          # Complete orchestration guide
│   ├── FACTORY_IAC_GENERATION_COMPARISON.md  # Approach comparison
│   ├── schemas/           # Manifest schemas
│   │   ├── manifest-schema-v1.0.yaml  # JSON Schema (YAML format)
│   │   ├── convert-to-json.sh         # Schema conversion script
│   │   └── README.md                  # Schema documentation
│   ├── examples/          # Example manifests
│   │   ├── multi-tier-complex.yaml    # Enterprise example
│   │   └── app-orchestrator-demo-manifest.yaml  # Simple demo
│   └── CLEANUP_DESIGN.md  # Cleanup procedures
│
├── app/                    # Python FastAPI Backend
│   ├── api/
│   │   ├── models/        # Pydantic request/response models
│   │   ├── routes/        # API route handlers
│   │   │   ├── bedrock.py      # AI/ML endpoints
│   │   │   ├── weather.py      # Weather endpoints
│   │   │   └── health.py       # Health check
│   │   └── services/      # Business logic
│   │       ├── bedrock_service.py
│   │       ├── weather_service.py
│   │       └── geocoding_service.py
│   ├── core/              # Configuration and logging
│   ├── main.py            # FastAPI application
│   ├── requirements.txt   # Python dependencies
│   └── README.md          # Backend documentation
│
├── ui/                     # Frontend Applications
│   └── weather/           # Weather UI (React/TypeScript)
│       ├── components/    # React components
│       ├── lib/           # API client and utilities
│       ├── styles/        # Tailwind CSS
│       ├── package.json   # Node.js dependencies
│       └── README.md      # UI documentation
│
├── terraform/              # Infrastructure as Code (Direct Deployment)
│   ├── bootstrap/         # State backend setup
│   ├── modules/          # Reusable modules
│   │   ├── vpc/          # VPC and networking
│   │   ├── security/     # KMS, Secrets, security services
│   │   ├── orchestration/  # 🆕 Orchestration infrastructure
│   │   ├── cicd/         # CodeBuild, CodeDeploy
│   │   ├── cloudfront/   # CloudFront + S3 for UI
│   │   └── waf/          # Web Application Firewall
│   ├── environments/     # Environment configs
│   │   ├── dev/          # Development
│   │   ├── test/         # Testing
│   │   └── prod/         # Production
│   └── README.md         # Infrastructure documentation
│
├── output/                # Generated Terraform (from generator/)
│   └── */                # Per-project generated code
│
├── .github/workflows/     # GitHub Actions CI/CD
├── docs/                  # Documentation
├── prompts/              # AI prompt files for code generation
├── buildspec.yml          # AWS CodeBuild configuration
└── README.md              # This file (start here!)

This project includes AI-optimized prompt files for automated infrastructure generation. These files are designed for AI assistants like Cline to generate infrastructure code, CI/CD pipelines, and related components for new client projects.

Location: prompts/

For detailed information about the prompt files, their purpose, and usage instructions, see the Prompts Directory README.

The prompts directory contains comprehensive specifications for:

• Foundation Standards (factory-common-prompt.md) - Naming conventions, tagging strategy, security requirements, and compliance standards
• Infrastructure Specifications (factory-terraform-prompt.md) - AWS infrastructure definitions including VPC, security, Lambda, API Gateway, and monitoring
• CI/CD Pipeline (factory-cicd-prompt.md) - GitHub Actions workflow specifications with security scanning, testing, and deployment automation
• REST API (factory-apigateway-prompt.md) - Lambda + API Gateway specifications with Cognito authentication (optional component)
• Templates & Guides - Master template for creating new prompts and comprehensive dependency matrix

✅ Rapid Deployment: 1-2 hours for serverless infrastructure setup ✅ Consistency: Standardized naming, tagging, and security across all client projects ✅ Compliance: Built-in FedRAMP Moderate and HIPAA controls ✅ Quality: Best practices, comprehensive testing, and security scanning ✅ AI-Optimized: Designed for efficient AI processing ✅ Production-Ready: Complete specifications with examples and troubleshooting guides

These files enable rapid, consistent serverless infrastructure deployment across multiple client projects while maintaining enterprise-grade security, compliance, and quality standards.

This project uses a symlink strategy to maintain DRY principles:

• Common Code: main.tf, variables.tf, outputs.tf in dev/ directory
• Environment-Specific: backend.tf, provider.tf, terraform.tfvars in each environment
• Symlinks: test/ and prod/ symlink to common files in dev/

# Test Environment
cd terraform/environments/test
terraform init
terraform plan
terraform apply

# Prod Environment
cd terraform/environments/prod
terraform init
terraform plan
terraform apply

This infrastructure implements FedRAMP Moderate security controls:

• Encryption: All data encrypted at rest (KMS) and in transit (TLS 1.2+)
• Logging: CloudTrail, VPC Flow Logs, application logs
• Monitoring: CloudWatch metrics, GuardDuty threat detection
• Access Control: IAM with least privilege, Zero Trust model
• Compliance: AWS Config rules, Security Hub standards

• ✅ KMS encryption for all storage and logs
• ✅ AWS Secrets Manager for sensitive data
• ✅ API key authentication for API endpoints (CKV_AWS_59 compliant)
• ✅ Usage plans with rate limiting and quotas
• ✅ Network isolation with private subnets
• ✅ Security groups with minimal ingress rules
• ✅ CloudTrail with log file validation
• ✅ GuardDuty for threat detection
• ✅ AWS Config for compliance monitoring
• ✅ Security Hub with CIS and FedRAMP standards
• ✅ Automated security scanning in CI/CD

This section tracks remaining security enhancements identified by Checkov security scanning. The infrastructure currently achieves 68.75% reduction in security findings (from 16 to 5), with the following items remaining for production environments.

• ✅ Passed Checks: 233
• ⚠️ Remaining Issues: 5 (Phase 3 - Production Readiness)
• ⏭️ Justified Skips: 5 (documented design decisions)

The following security enhancements are recommended for production environments. All are lower priority for development but important for compliance and production-grade security.

Issue: CKV_AWS_173 - Lambda environment variables not encrypted with Customer Managed Key Current State: Environment variables exist but use AWS-managed encryption Priority: Medium Effort: Low (30 minutes) Compliance Impact: Required for FedRAMP High, HIPAA strict compliance

Implementation:

# File: terraform/modules/lambda/main.tf
resource "aws_lambda_function" "api_handler" {
  # ... existing config ...

  kms_key_arn = var.kms_key_arn  # Add this line

  environment {
    variables = {
      # Existing variables...
    }
  }
}

Benefits:

• Full control over encryption keys
• Enhanced audit trail for key usage
• Ability to rotate keys independently
• Better compliance posture

Testing:

# Verify encryption after deployment
aws lambda get-function --function-name <function-name> \
  | jq '.Configuration.KMSKeyArn'

Issue: CKV_AWS_119 - DynamoDB state lock table uses AWS-managed key Current State: Table encrypted with AWS-managed key Priority: Low for Dev, High for Prod Effort: Low (15 minutes) Compliance Impact: Required for FedRAMP Moderate+, recommended for HIPAA

Implementation:

# File: terraform/bootstrap/main.tf
resource "aws_dynamodb_table" "terraform_state_lock" {
  # ... existing config ...

  server_side_encryption {
    enabled     = true
    kms_key_arn = aws_kms_key.terraform_state.arn
  }
}

Benefits:

• Centralized key management
• Enhanced security posture for state management
• Better audit and compliance reporting

Note: This change requires recreating the DynamoDB table. Plan carefully for production.

Issue: CKV_AWS_147 - CodeBuild projects not encrypted with CMK Current State: Using AWS-managed encryption Priority: Low for Dev, Medium for Prod Effort: Low (20 minutes) Compliance Impact: Recommended for FedRAMP, required for highly sensitive builds

Implementation:

# File: terraform/modules/cicd/main.tf
resource "aws_codebuild_project" "main" {
  # ... existing config ...

  encryption_key = var.kms_key_arn  # Add this line

  # ... rest of config ...
}

Benefits:

• Encrypted build artifacts with customer-managed keys
• Better control over CI/CD pipeline security
• Enhanced compliance posture

Testing:

# Verify encryption after deployment
aws codebuild batch-get-projects \
  --names <project-name> \
  | jq '.projects[0].encryptionKey'

Issue: CKV_AWS_252 - CloudTrail not configured with SNS topic for alerts Current State: CloudTrail logging to S3 and CloudWatch only Priority: Low for Dev, Medium for Prod Effort: Medium (45 minutes) Compliance Impact: Recommended for real-time security monitoring

Implementation:

# File: terraform/modules/security/main.tf

# Create SNS topic for CloudTrail alerts
resource "aws_sns_topic" "cloudtrail_alerts" {
  name              = "${var.environment}-${var.project_name}-cloudtrail-alerts"
  kms_master_key_id = aws_kms_key.main.arn

  tags = merge(var.tags, {
    Name = "${var.environment}-${var.project_name}-cloudtrail-alerts"
  })
}

# Email subscription (optional)
resource "aws_sns_topic_subscription" "cloudtrail_email" {
  count     = var.security_alert_email != "" ? 1 : 0
  topic_arn = aws_sns_topic.cloudtrail_alerts.arn
  protocol  = "email"
  endpoint  = var.security_alert_email
}

# Update CloudTrail
resource "aws_cloudtrail" "main" {
  # ... existing config ...

  sns_topic_name = aws_sns_topic.cloudtrail_alerts.name  # Add this line
}

Benefits:

• Real-time notifications for CloudTrail events
• Integration with security monitoring systems
• Faster incident response

Use Cases:

• Alert on unauthorized API calls
• Notify on IAM policy changes
• Monitor security group modifications

Issue: CKV_AWS_272 - Lambda function not configured for code signing validation Current State: No code signing validation Priority: Low (Advanced security feature) Effort: High (2-3 hours for initial setup) Compliance Impact: Optional, enhances supply chain security

Implementation Overview:

Step 1: Create signing profile

# Create signing profile in AWS Signer
aws signer put-signing-profile \
  --profile-name lambda-signing-profile \
  --platform-id AWSLambda-SHA384-ECDSA

Step 2: Create code signing configuration

# File: terraform/modules/lambda/main.tf
resource "aws_lambda_code_signing_config" "main" {
  allowed_publishers {
    signing_profile_version_arns = [
      var.signing_profile_arn
    ]
  }

  policies {
    untrusted_artifact_on_deployment = "Warn"  # or "Enforce"
  }

  description = "Code signing config for ${var.environment} Lambda functions"
}

resource "aws_lambda_function" "api_handler" {
  # ... existing config ...

  code_signing_config_arn = aws_lambda_code_signing_config.main.arn
}

Step 3: Sign deployment packages

# Sign the Lambda deployment package
aws signer start-signing-job \
  --source 's3={bucketName=my-bucket,key=lambda.zip,version=1}' \
  --destination 's3={bucketName=signed-bucket}' \
  --profile-name lambda-signing-profile

Benefits:

• Ensures only signed code is deployed
• Prevents unauthorized code modifications
• Enhanced supply chain security
• Audit trail for code deployments

Considerations:

• Requires CI/CD pipeline modifications
• Additional step in deployment process
• May impact deployment speed slightly

• ✅ Phase 1 & 2 Complete - Current implementation sufficient
• ⚠️ Phase 3 Optional - Implement only if needed for specific compliance requirements

• ✅ Phase 1 & 2 Complete - Foundation established
• 🔴 Immediate: Lambda Environment CMK (CKV_AWS_173)
• 🔴 Immediate: DynamoDB CMK (CKV_AWS_119)
• 🟡 High Priority: CodeBuild CMK (CKV_AWS_147)
• 🟡 High Priority: CloudTrail SNS (CKV_AWS_252)
• 🟢 Optional: Lambda Code Signing (CKV_AWS_272)

Full Checkov scan:

checkov --config-file .checkov.yml --directory terraform/ --compact

Scan specific modules:

# Scan Lambda module only
checkov --directory terraform/modules/lambda/ --compact

# Scan with detailed output
checkov --directory terraform/ --output cli

Generate compliance reports:

# JSON report
checkov --directory terraform/ \
  --output json \
  --output-file-path security-report.json

# JUnit XML for CI/CD
checkov --directory terraform/ \
  --output junitxml \
  --output-file-path security-junit.xml

Total remaining effort for production: 4-6 hours

Install pre-commit hooks:

pre-commit install

Run manually:

pre-commit run --all-files

The project uses a unified, intelligent CI/CD pipeline that automatically detects changes and deploys accordingly.

The pipeline automatically detects what changed and deploys only what's needed:

When you open a pull request, the pipeline runs:

• terraform fmt -check -recursive - Ensures code formatting
• terraform validate - Validates Terraform syntax and configuration

Note: Security scanning, Terraform plan preview, and other checks are intentionally excluded from PR validation per project requirements.

When code is merged to the develop branch, the unified pipeline:

1. Change Detection Phase

   • Analyzes git diff to detect Terraform changes (terraform/**)
   • Analyzes git diff to detect application changes (app/**)
   • Creates intelligent deployment plan

2. Infrastructure Deployment (if Terraform changes detected)

   • terraform fmt -check - Validates code formatting
   • terraform init - Initializes Terraform
   • terraform validate - Validates configuration
   • terraform plan - Creates execution plan
   • terraform apply - Deploys infrastructure changes

3. Application Deployment (if app changes detected)

   • Code quality checks (black, flake8)
   • Unit tests (pytest)
   • Docker build (Lambda deployment package)
   • Upload to S3
   • Update Lambda function
   • Tag with deployment metadata

4. Notifications

   • SNS notifications with deployment summary
   • Includes what was deployed (Terraform/Lambda/both)

Key Benefits:

• ⚡ Faster deployments - Only deploys what changed
• 🎯 Targeted updates - No unnecessary infrastructure changes
• 🔄 Correct order - Always deploys Terraform before Lambda
• 📊 Clear visibility - Know exactly what was deployed

Test and prod deployments must be done manually:

# For test
cd terraform/environments/test
terraform init && terraform plan && terraform apply

# For prod
cd terraform/environments/prod
terraform init && terraform plan && terraform apply

Monitor deployments in AWS CodeBuild:

# View build logs in real-time
aws logs tail /aws/codebuild/dev-mes-accelerator-demo --follow

# Check last build status
aws codebuild batch-get-builds \
  --ids $(aws codebuild list-builds-for-project \
    --project-name dev-mes-accelerator-demo-build-deploy \
    --query 'ids[0]' --output text)

• main: Production-ready code
• develop: Development branch
• feature/*: Feature branches
• hotfix/*: Hotfix branches

Access CloudWatch dashboards for:

• Lambda metrics (invocations, errors, duration, throttles)
• API Gateway metrics (requests, latency, 4xx/5xx errors)
• VPC Flow Logs
• Application logs

Configured CloudWatch alarms for:

• Lambda errors and throttles
• Lambda duration approaching timeout
• API Gateway 5xx errors
• VPC Flow Log analysis

cd terraform/environments/dev
terraform plan  # Review changes
terraform apply # Apply changes

# Rotate API keys
aws secretsmanager update-secret \
  --secret-id dev/app/api-keys \
  --secret-string '{"service1_api_key":"new-key-1","service2_api_key":"new-key-2"}'  # pragma: allowlist secret

Modify terraform.tfvars for each environment:

# Adjust Lambda memory and concurrency
lambda_memory_size                    = 1024  # Increase memory for better performance
lambda_reserved_concurrent_executions = 50    # Reserve more concurrent executions
lambda_timeout                        = 60    # Increase timeout if needed

# Adjust API Gateway throttling
api_gateway_throttle_burst_limit = 1000
api_gateway_throttle_rate_limit  = 500

• Bootstrap Infrastructure
• VPC Module
• Security Module
• Lambda Module
• API Gateway Module
• CI/CD Module
• GitHub Webhook Setup Guide - Complete guide for configuring GitHub webhooks with AWS CodeBuild

Unexpected Terraform Resource Changes

If Terraform plans to destroy resources that haven't changed in code (especially CI/CD resources like aws_codebuild_source_credential):

# The issue: You see changes like "index [0] is out of range for count"
# This means a conditional resource expects a variable that isn't set

# Solution: Ensure environment variables are loaded
source ./.env

# Verify the specific variable causing the issue
echo $TF_VAR_github_token_secret_arn

# If empty, add it to your .env file:
# export TF_VAR_github_token_secret_arn="arn:aws:secretsmanager:..."  # pragma: allowlist secret

# Re-run the plan after loading variables
cd terraform/environments/dev
terraform plan

Root Cause: The CI/CD module uses conditional resource creation based on github_token_secret_arn. When this variable is empty, Terraform's count evaluates to 0, causing resources to be destroyed. When set, count is 1, and resources are created/maintained. # pragma: allowlist secret

Terraform State Lock Error

# Force unlock (use with caution)
terraform force-unlock <LOCK_ID>

Lambda Function Errors

# Check Lambda logs
FUNCTION_NAME=$(terraform output -raw lambda_function_name)
aws logs tail /aws/lambda/$FUNCTION_NAME --since 1h

# Test Lambda directly
aws lambda invoke \
  --function-name $FUNCTION_NAME \
  --payload '{}' \
  response.json

API Gateway 5xx Errors

• Check Lambda function logs for errors
• Verify Lambda has correct IAM permissions
• Check VPC configuration and NAT Gateway
• Review API Gateway logs in CloudWatch

API Gateway 403 Forbidden Errors

If you receive 403 Forbidden when calling the /hello endpoint:

# Verify you're using the API key header
curl -H "x-api-key: YOUR_KEY_HERE" "$API_ENDPOINT/hello"

# Retrieve the current API key
API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id dev/api-gateway/hello-api-key \
  --query SecretString --output text | jq -r '.api_key_value')

# Test again with the correct key
curl -H "x-api-key: $API_KEY" "$API_ENDPOINT/hello"

# Verify the API key is associated with the usage plan
aws apigateway get-usage-plan-keys \
  --usage-plan-id $(terraform output -raw usage_plan_id)

VPC Connectivity Issues

• Verify NAT Gateway is running
• Check route table configurations
• Review security group rules
• Check VPC endpoint configurations

1. Create a feature branch from develop
2. Make your changes
3. Run pre-commit hooks
4. Submit a pull request
5. Wait for CI/CD validation
6. Address review feedback
7. Merge after approval

This project is licensed under the terms in the LICENSE file.

Built with ❤️ by Fearless Solutions

Be Remarkable. Be Fearless. 💜

• Never commit secrets to version control
• Always review Terraform plans before applying
• Test in dev before deploying to prod
• Monitor costs in AWS Cost Explorer
• Rotate API keys regularly
• Review Security Hub findings weekly
• Monitor Lambda costs and adjust memory/concurrency as needed

For issues or questions:

• Open a GitHub issue
• Contact the Fearless Solutions team
• Review CloudWatch logs
• Check AWS Service Health Dashboard