diff --git a/terraform/aws-infrastructure/README.md b/terraform/aws-infrastructure/README.md
new file mode 100644
index 0000000..96612e9
--- /dev/null
+++ b/terraform/aws-infrastructure/README.md
@@ -0,0 +1,229 @@
+# 🏗️ AWS Multi-Tier Infrastructure - Terraform Project
+
+## 📋 Overview
+
+Production-ready Terraform project for complete AWS multi-tier infrastructure with HA, security, and scalability best practices.
+
+### 🏛️ Architecture
+
+```
+Internet → ALB → Public Subnets (Multi-AZ)
+              ↓
+           NAT Gateways
+              ↓
+    Private Subnets (App Tier + Auto Scaling)
+              ↓
+    Database Subnets (RDS PostgreSQL Multi-AZ)
+```
+
+### 📦 Components
+
+- **VPC** - Isolated network across 2 AZs
+- **ALB** - Application Load Balancer
+- **Auto Scaling** - EC2 with dynamic scaling  
+- **RDS PostgreSQL** - Managed database with backups
+- **S3** - Storage buckets (data/logs/backups)
+- **CloudWatch** - Monitoring & alerting
+- **IAM** - Security roles & policies
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# 1. Clone
+git clone http://git.thedevops.dev/admin/k3s-gitops.git
+cd k3s-gitops/terraform/aws-infrastructure
+
+# 2. Configure AWS
+export AWS_ACCESS_KEY_ID="your-key"
+export AWS_SECRET_ACCESS_KEY="your-secret"
+
+# 3. Create config
+cp environments/dev.tfvars terraform.tfvars
+vim terraform.tfvars  # Edit: project_name, db_password
+
+# 4. Deploy
+terraform init
+terraform plan
+terraform apply
+```
+
+**Deploy time:** ~15-20 minutes  
+**Dev cost:** ~$50-100/month
+
+---
+
+## 📁 Project Structure
+
+```
+terraform/aws-infrastructure/
+├── main.tf               # Main configuration
+├── variables.tf          # Input variables
+├── outputs.tf            # Output values
+├── Jenkinsfile           # CI/CD pipeline
+├── environments/         # Environment configs
+│   ├── dev.tfvars
+│   ├── staging.tfvars
+│   └── production.tfvars
+├── modules/              # Reusable modules
+│   ├── vpc/
+│   ├── alb/
+│   ├── asg/
+│   ├── rds/
+│   └── ...
+├── scripts/
+│   └── user-data.sh      # EC2 bootstrap
+└── docs/
+    ├── QUICKSTART.md     # 5-min setup guide
+    ├── ARCHITECTURE.md   # Detailed design
+    └── SECURITY.md       # Best practices
+```
+
+---
+
+## 🎯 Usage Examples
+
+### Development Environment
+
+```bash
+terraform apply -var-file="environments/dev.tfvars"
+```
+
+### Production Environment
+
+```bash
+terraform apply -var-file="environments/production.tfvars"
+```
+
+### Scale Application
+
+```bash
+# Edit terraform.tfvars
+asg_desired_capacity = 5
+
+terraform apply
+```
+
+---
+
+## 🔧 Configuration
+
+**Minimum required variables:**
+
+```hcl
+# terraform.tfvars
+project_name = "myapp"
+environment  = "dev"
+db_username  = "admin"
+db_password  = "SecurePassword123!"
+```
+
+**See `environments/` for full examples**
+
+---
+
+## 📊 Outputs
+
+```bash
+# View all outputs
+terraform output
+
+# Get ALB DNS
+terraform output alb_dns_name
+
+# Get RDS endpoint  
+terraform output rds_endpoint
+```
+
+---
+
+## 🔐 Security
+
+- ✅ State encryption in S3
+- ✅ Private subnets for apps
+- ✅ Isolated database subnets
+- ✅ Security groups with minimal permissions
+- ✅ Secrets in AWS Secrets Manager
+- ✅ VPC Flow Logs enabled
+- ✅ CloudTrail auditing
+
+**⚠️ NEVER commit secrets to Git!**
+
+---
+
+## 🔄 CI/CD
+
+Jenkins pipeline included with:
+- ✅ Terraform validation
+- ✅ Security scanning (tfsec)
+- ✅ Cost estimation (Infracost)
+- ✅ Approval gates for production
+- ✅ Automated smoke tests
+
+---
+
+## 📚 Documentation
+
+- [Quick Start Guide](docs/QUICKSTART.md) - 5-minute setup
+- [Architecture Details](docs/ARCHITECTURE.md) - Design deep-dive
+- [Security Best Practices](docs/SECURITY.md) - Hardening guide
+- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues
+
+---
+
+## 💰 Cost Estimates
+
+| Environment | Monthly Cost |
+|-------------|--------------|
+| Development | $50-100 |
+| Staging | $200-400 |
+| Production | $500-1000 |
+
+*Actual costs depend on usage and instance types*
+
+---
+
+## 🧪 Testing
+
+```bash
+# Validate
+terraform validate
+
+# Format check
+terraform fmt -check -recursive
+
+# Security scan
+docker run --rm -v $(pwd):/src aquasec/tfsec /src
+```
+
+---
+
+## 🗑️ Cleanup
+
+```bash
+# Destroy dev
+terraform destroy -var-file="environments/dev.tfvars"
+
+# ⚠️ Production requires manual approval
+```
+
+---
+
+## 📞 Support
+
+- 🐛 [Issues](http://git.thedevops.dev/admin/k3s-gitops/issues)
+- 💬 Slack: #infrastructure  
+- 📧 Email: devops@example.com
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+**Status:** ✅ Production Ready  
+**Version:** 1.0.0  
+**Last Updated:** 2026-01-06