was-cf/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Common Development Commands

### Infrastructure Management
```bash
# Initialize OpenTofu (required after cloning)
tofu init

# Plan changes
tofu plan

# Apply changes
tofu apply

# Destroy infrastructure
tofu destroy
```

### Backend Setup (S3 + CloudFront Logs)
```bash
# Set up S3 backend and CloudFront logging buckets
./setup-backend.sh

# Migrate state to S3 backend (one-time operation)
echo "yes" | tofu init -migrate-state
```

### Validation and Formatting
```bash
# Validate Terraform configuration
tofu validate

# Format Terraform files
tofu fmt

# Check syntax and validate variables
tofu plan -var-file=terraform.tfvars
```

### AWS Resource Verification
```bash
# Check CloudFront distribution status
aws cloudfront get-distribution --id E1XR8P4ENGP8RU --query 'Distribution.Status' --output text

# List all CloudFront distributions
aws cloudfront list-distributions --query 'DistributionList.Items[*].[Id,Status,DistributionConfig.Enabled]' --output table

# Check S3 backend state
aws s3 ls s3://aws-cf-terraform-state-535294143817/aws-cf/

# View CloudFront logs
aws s3 ls s3://aws-cf-cloudfront-logs-535294143817/cloudfront-logs/ --recursive
```

## Architecture Overview

### Infrastructure Design
This is an AWS CloudFront CDN deployment using OpenTofu (Terraform fork) with the following key architectural decisions:

**Primary Components:**
- **CloudFront Distribution**: Main CDN with custom origin server
- **WAF v2 Web ACL**: Security layer with rate limiting and AWS managed rules
- **S3 Backend**: Remote state storage with versioning and encryption
- **Optional CloudFormation Stack**: VPC and networking resources

**Critical Configuration Constraints:**
- Origin server (`origin.servidor.it.com`) only supports HTTP, not HTTPS
- Using CloudFront default certificate (not custom ACM certificate)
- Route53 records disabled due to CAA restrictions
- DynamoDB state locking disabled due to permission constraints

### File Structure and Responsibilities

**Core Infrastructure:**
- `main.tf` - CloudFront distribution, origin configuration, cache behaviors, and optional CloudFormation stack
- `security.tf` - WAF Web ACL with rate limiting, managed rule sets, and security groups
- `variables.tf` - All configurable parameters with validation rules
- `outputs.tf` - CloudFront URLs, distribution IDs, and resource ARNs

**Configuration Management:**
- `backend.tf` - S3 remote state configuration (no DynamoDB locking)
- `versions.tf` - OpenTofu/Terraform and provider version constraints
- `acm.tf` - ACM certificate configuration (currently disabled)
- `terraform.tfvars.example` - Variable configuration template

**Operational Scripts:**
- `setup-backend.sh` - Automated S3 backend and logging bucket creation with proper permissions

### Key Architectural Patterns

**Multi-Environment Design:**
- Variables for `project_name` and `environment` enable multiple deployments
- Resource naming follows `${project_name}-${environment}-${resource}` pattern
- Tags applied consistently across all resources

**Security-First Approach:**
- WAF protection with AWS managed rules and rate limiting
- S3 buckets with encryption, versioning, and public access blocking
- Security groups with principle of least privilege (when VPC enabled)

**Cache Strategy:**
- Default behavior uses CachingDisabled policy for dynamic content
- API paths (`/api/*`) specifically configured with caching disabled
- Static content can be optimized by changing cache policy IDs

**Conditional Resource Creation:**
- Most resources controlled by boolean variables for flexible deployment
- ACM certificates, Route53 records, and CloudFormation stacks can be toggled
- Allows gradual feature enablement as permissions are acquired

## Important Configuration Notes

### Critical Settings in terraform.tfvars
- `origin_protocol_policy = "http-only"` - **Do not change to HTTPS** (causes 504 errors)
- `create_acm_certificate = false` - Custom certificates fail due to CAA restrictions
- `enable_waf = true` - WAF is working and provides important security
- `create_route53_records = false` - DNS management disabled due to CAA restrictions

### State Management
- Backend uses S3 without DynamoDB locking (single developer setup)
- State bucket: `aws-cf-terraform-state-535294143817`
- Logs bucket: `aws-cf-cloudfront-logs-535294143817`

### Security Considerations
- WAF provides protection against common attacks and rate limiting
- Origin-to-CloudFront traffic is unencrypted (HTTP-only constraint)
- SSH access defaults to 0.0.0.0/0 in variables - **restrict in production**
- CloudFront logs stored in S3 with 90-day lifecycle policy

### Performance Optimization
- Price class set to PriceClass_100 (US, Canada, Europe)
- Compression enabled for all content types
- Custom error pages redirect 404/403 to index.html for SPA support

### Working vs Disabled Features
**Currently Working:**
- CloudFront distribution with HTTP origin
- WAF v2 with managed rules
- S3 logging and state storage
- Custom cache behaviors for API paths

**Currently Disabled (can be enabled with proper permissions):**
- ACM custom certificates (CAA restrictions)
- Route53 DNS management (CAA restrictions)  
- CloudFormation VPC stack (permission constraints)
- DynamoDB state locking (permission constraints)