feat(infra): Add complete main.tf, variables.tf, outputs.tf for Terraform module (#372)

* feat(infra): Add complete main.tf, variables.tf, outputs.tf for Terraform module

Resolves #164 - Refactor infrastructure/terraform/ from flat .tf files into a composable module structure with network, compute, and data submodules.

* style(terraform): fix formatting in main.tf via terraform fmt

Author: Moonwalker-rgb

infrastructure/terraform/README.md

@@ -1,19 +1,95 @@
 # Terraform Configurations
 
-Infrastructure as Code for cloud resource provisioning.
+Infrastructure as Code for VertexChain cloud resource provisioning.
 
 ## Overview
 
-Terraform modules for provisioning cloud infrastructure for VertexChain.
+Terraform modules for provisioning AWS infrastructure for VertexChain,
+a location-aware micro-messaging platform built on Stellar.
 
-## Contents
+## Module Structure
 
-- AWS/GCP/Azure resource definitions
-- Network configurations
-- Database provisioning
-- Storage buckets
-- Load balancers
+```
+infrastructure/terraform/
+├── main.tf            # Root module entry point
+├── variables.tf       # Root module input variables
+├── outputs.tf         # Root module outputs (ARNs for every resource)
+├── providers.tf       # Terraform and provider configuration
+├── modules/
+│   ├── network/       # VPC, subnets, gateways, NACLs, security groups
+│   ├── compute/       # EKS, ASG, ALB, launch templates, target groups
+│   └── data/          # RDS, ElastiCache, S3, backup vaults & plans
+├── envs/              # Per-environment tfvars files
+│   ├── terraform.tfvars.dev
+│   ├── terraform.tfvars.staging
+│   ├── terraform.tfvars.prod
+│   └── terraform.tfvars.example
+├── tests/             # Terratest integration tests
+│   └── test_helper.go
+└── archive/           # Previous flat .tf files (kept for reference)
+```
 
 ## Usage
 
-Run `terraform plan` and `terraform apply` to provision resources.
+```bash
+# Initialize Terraform
+terraform init
+
+# Select workspace
+terraform workspace select dev || terraform workspace new dev
+
+# Plan with environment-specific variables
+terraform plan -var-file=envs/terraform.tfvars.dev
+
+# Apply changes
+terraform apply -var-file=envs/terraform.tfvars.dev
+```
+
+## Workspace Strategy
+
+Per-environment state isolation is handled by workspaces. Each environment
+uses its own `tfvars` file while sharing the same root module:
+
+| Environment | Workspace | Variable file            |
+|-------------|-----------|--------------------------|
+| dev         | `dev`     | `envs/terraform.tfvars.dev` |
+| staging     | `staging` | `envs/terraform.tfvars.staging` |
+| prod        | `prod`    | `envs/terraform.tfvars.prod` |
+
+## Outputs
+
+All resource ARNs are surfaced through the root module's `outputs.tf`.
+Run `terraform output` to see the full list after an apply.
+
+```bash
+terraform output
+# vpc_id                  = "vpc-xxx"
+# alb_arn                 = "arn:aws:elasticloadbalancing:..."
+# rds_instance_arn        = "arn:aws:rds:..."
+# redis_replication_group_arn = "arn:aws:elasticache:..."
+# s3_uploads_bucket_arn   = "arn:aws:s3:::..."
+# eks_cluster_arn         = "arn:aws:eks:..."
+# waf_web_acl_arn         = "arn:aws:wafv2:..."
+# cloudfront_distribution_arn = "arn:aws:cloudfront:..."
+# ...and many more
+```
+
+## Migrating from the flat structure
+
+The previous flat `.tf` files (vpc.tf, rds.tf, etc.) have been refactored into
+the submodule structure above. The original files are preserved in the
+`archive/` directory for reference and should be removed once the new modular
+structure is validated.
+
+Before applying the new module structure to an existing deployment:
+
+1. Import existing resources into the new module state:
+   ```bash
+   terraform import module.network.aws_vpc.this vpc-xxx
+   terraform import module.data.aws_db_instance.postgres db-xxx
+   # ... etc.
+   ```
+
+2. Run `terraform plan` to verify no unexpected changes.
+
+3. Apply once all differences are reconciled.

infrastructure/terraform/archive/README.md

@@ -0,0 +1,24 @@
+# Archived Terraform files
+
+This directory contains the previous flat `.tf` files that were in the root
+`infrastructure/terraform/` directory before the module-based refactoring
+(see issue #164).
+
+## Why was this refactored?
+
+The old structure had 40+ `.tf` files in a single flat directory with no
+`main.tf` entry point, scattered variable declarations, duplicate resource
+definitions (e.g., `aws_security_group.alb` defined in both `alb.tf` and
+`security-groups.tf`), and no outputs for resource ARNs.
+
+The new structure:
+- **`main.tf`** — clear root module entry point
+- **`outputs.tf`** — ARNs for every created resource
+- **`variables.tf`** — consolidated variable declarations (no duplicates)
+- **`modules/`** — clean split into `network`, `compute`, and `data` submodules
+
+## Removal
+
+These archive files can be safely removed once the new modular structure has
+been validated with `terraform plan` against a live environment. They are kept
+only as a reference during the migration period.

infrastructure/terraform/archive/alarms.tf

@@ -0,0 +1,35 @@
+resource "aws_cloudwatch_metric_alarm" "cpu_high" {
+  alarm_name          = "vertexchain-cpu-high"
+  comparison_operator = "GreaterThanThreshold"
+  evaluation_periods  = 2
+  metric_name         = "CPUUtilization"
+  namespace           = "AWS/ECS"
+  period              = 300
+  statistic           = "Average"
+  threshold           = 80
+  alarm_actions       = [aws_sns_topic.vertexchain_alerts.arn]
+}
+
+resource "aws_cloudwatch_metric_alarm" "memory_high" {
+  alarm_name          = "vertexchain-memory-high"
+  comparison_operator = "GreaterThanThreshold"
+  evaluation_periods  = 2
+  metric_name         = "MemoryUtilization"
+  namespace           = "AWS/ECS"
+  period              = 300
+  statistic           = "Average"
+  threshold           = 80
+  alarm_actions       = [aws_sns_topic.vertexchain_alerts.arn]
+}
+
+resource "aws_cloudwatch_metric_alarm" "errors_high" {
+  alarm_name          = "vertexchain-errors-high"
+  comparison_operator = "GreaterThanThreshold"
+  evaluation_periods  = 1
+  metric_name         = "5XXError"
+  namespace           = "AWS/ApplicationELB"
+  period              = 60
+  statistic           = "Sum"
+  threshold           = 10
+  alarm_actions       = [aws_sns_topic.vertexchain_alerts.arn]
+}

infrastructure/terraform/archive/alb-listeners.tf

@@ -0,0 +1,32 @@
+variable "certificate_arn" {
+  description = "ACM certificate ARN for HTTPS"
+  type        = string
+}
+
+resource "aws_lb_listener" "https" {
+  load_balancer_arn = aws_lb.main.arn
+  port              = 443
+  protocol          = "HTTPS"
+  ssl_policy        = "ELBSecurityPolicy-TLS13-1-2-2021-06"
+  certificate_arn   = var.certificate_arn
+
+  default_action {
+    type             = "forward"
+    target_group_arn = aws_lb_target_group.app.arn
+  }
+}
+
+resource "aws_lb_listener" "http_redirect" {
+  load_balancer_arn = aws_lb.main.arn
+  port              = 80
+  protocol          = "HTTP"
+
+  default_action {
+    type = "redirect"
+    redirect {
+      port        = "443"
+      protocol    = "HTTPS"
+      status_code = "HTTP_301"
+    }
+  }
+}

infrastructure/terraform/archive/alb.tf

@@ -0,0 +1,46 @@
+resource "aws_lb" "main" {
+  name               = "${var.project_name}-${var.environment}-alb"
+  internal           = false
+  load_balancer_type = "application"
+  security_groups    = [aws_security_group.alb.id]
+  subnets            = var.public_subnet_ids
+
+  enable_deletion_protection = var.environment == "production" ? true : false
+
+  tags = {
+    Environment = var.environment
+    Project     = var.project_name
+  }
+}
+
+resource "aws_security_group" "alb" {
+  name        = "${var.project_name}-${var.environment}-alb-sg"
+  description = "Security group for ALB"
+  vpc_id      = var.vpc_id
+
+  ingress {
+    from_port   = 80
+    to_port     = 80
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  ingress {
+    from_port   = 443
+    to_port     = 443
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  tags = {
+    Environment = var.environment
+    Project     = var.project_name
+  }
+}

infrastructure/terraform/archive/asg.tf

@@ -0,0 +1,27 @@
+resource "aws_autoscaling_group" "app" {
+  name                = "${var.project_name}-${var.environment}-asg"
+  min_size            = var.asg_min_size
+  max_size            = var.asg_max_size
+  desired_capacity    = var.asg_desired_size
+  vpc_zone_identifier = var.private_subnet_ids
+
+  launch_template {
+    id      = aws_launch_template.app.id
+    version = "$Latest"
+  }
+
+  health_check_type         = "ELB"
+  health_check_grace_period = 300
+
+  tag {
+    key                 = "Name"
+    value               = "${var.project_name}-${var.environment}-app"
+    propagate_at_launch = true
+  }
+
+  tag {
+    key                 = "Environment"
+    value               = var.environment
+    propagate_at_launch = true
+  }
+}

infrastructure/terraform/archive/backup-plans.tf

@@ -0,0 +1,44 @@
+# Weekly backup plan. Adds a higher frequency cold-storage tier on top
+# of the daily plan so we keep monthly snapshots for a full year without
+# paying hot-storage costs.
+#
+# `backup_retention_days` is declared in variables.tf; it controls the
+# DR-region copy retention, matching the primary tier so DR capacity
+# planning stays predictable.
+
+resource "aws_backup_plan" "weekly" {
+  name = "${var.project_name}-${var.environment}-weekly-plan"
+
+  rule {
+    rule_name         = "weekly_backup"
+    target_vault_name = aws_backup_vault.main.name
+    schedule          = "cron(0 3 ? * SUN *)"
+    start_window      = 60
+    completion_window = 360
+
+    lifecycle {
+      cold_storage_after = 30
+      delete_after       = 365
+    }
+
+    # Mirror the weekly snapshot into the DR-region vault so a single
+    # regional outage does not lose the last good monthly copy.
+    dynamic "copy_action" {
+      for_each = var.enable_cross_region_backup ? [1] : []
+      content {
+        destination_vault_arn = aws_backup_vault.dr[0].arn
+
+        lifecycle {
+          # Match the on-primary retention for consistency.
+          cold_storage_after = 30
+          delete_after       = var.backup_retention_days
+        }
+      }
+    }
+  }
+
+  tags = {
+    Environment = var.environment
+    Project     = var.project_name
+  }
+}