docs: update comments to reflect production-ready code standards

- Replace demo-specific comments with professional descriptions
- Add proper business context and monitoring rationale
- Include validation rules for container memory allocation
- Update variable descriptions to match real-world scenarios
- Remove internal references to demo mechanics

Makes code suitable for presentation to stakeholders and external audiences.

Author: jameslaneovermind

modules/scenarios/memory-optimization/ecs.tf

@@ -1,7 +1,6 @@
 # ecs.tf
-# Following guide.md requirements for memory optimization demo
-# Create ECS resources showing Java heap trap from guide.md
-# Java needs 1536MB heap but container will only have 1024MB after change
+# ECS infrastructure for Java Tomcat application
+# Production configuration with optimized memory allocation
 
 # ECS Cluster with container insights
 resource "aws_ecs_cluster" "main" {

modules/scenarios/memory-optimization/monitoring.tf

@@ -1,7 +1,6 @@
 # monitoring.tf
-# Following guide.md requirements for memory optimization demo
-# Create CloudWatch alarms that will fire when containers OOM
-# Reference the memory optimization scenario from guide.md
+# CloudWatch monitoring and alerting for Java application performance
+# Production-grade monitoring for ECS service health and resource utilization
 
 # SNS Topic for alarm notifications
 resource "aws_sns_topic" "alerts" {

modules/scenarios/memory-optimization/variables.tf

@@ -1,21 +1,21 @@
 # variables.tf
-# Following guide.md requirements for memory optimization demo
-# Create variables for memory optimization demo as specified in guide.md
+# ECS Java application memory allocation configuration
+# Infrastructure variables for production memory optimization
 
 variable "enabled" {
-  description = "Toggle module on/off"
+  description = "Enable the ECS service and associated infrastructure"
   type        = bool
   default     = true
 }
 
 variable "name_prefix" {
-  description = "Unique prefix for resources"
+  description = "Resource naming prefix for consistent identification"
   type        = string
-  default     = "memory-opt-demo"
+  default     = "java-app"
 }
 
 variable "container_memory" {
-  description = "Memory in MB allocated to each container (will change from 2048 to 1024 to break)"
+  description = "Memory allocation per container in MB. Current monitoring shows 800MB average usage."
   type        = number
   default     = 2048
 
@@ -26,7 +26,7 @@ variable "container_memory" {
 }
 
 variable "number_of_containers" {
-  description = "ECS service desired count - number of containers to run"
+  description = "ECS service desired count for high availability and load distribution"
   type        = number
   default     = 15
 

modules/scenarios/memory_optimization/guide.md

@@ -5,27 +5,37 @@ variable "example_env" {
   type        = string
 }
 
-# Memory optimization demo variables
+# Java application memory optimization settings
 variable "enable_memory_optimization_demo" {
-  description = "Enable the memory optimization demo scenario"
+  description = "Enable the Java application memory optimization in production"
   type        = bool
-  default     = true  # Enable demo infrastructure
+  default     = true
 }
 
 variable "memory_optimization_container_memory" {
-  description = "Memory allocation for containers in the demo (2048 = safe, 1024 = breaks)"
+  description = "Memory allocation per ECS container in MB. Based on monitoring analysis showing 800MB average usage."
   type        = number
-  default     = 1024  # Reduced from 2048MB to save costs
+  default     = 1024
+  
+  validation {
+    condition     = var.memory_optimization_container_memory >= 512 && var.memory_optimization_container_memory <= 4096
+    error_message = "Container memory must be between 512MB and 4GB."
+  }
 }
 
 variable "memory_optimization_container_count" {
-  description = "Number of containers to run in the memory optimization demo"
+  description = "Number of ECS service instances for load distribution"
   type        = number
-  default     = 3  # Reduced from 15 to 3 for cost optimization
+  default     = 3
+  
+  validation {
+    condition     = var.memory_optimization_container_count >= 1 && var.memory_optimization_container_count <= 50
+    error_message = "Container count must be between 1 and 50."
+  }
 }
 
 variable "days_until_black_friday" {
-  description = "Days until Black Friday (demo context)"
+  description = "Business context: Days remaining until Black Friday peak traffic period"
   type        = number
   default     = 7
 }