AWS Architecture

All backend infrastructure is managed by Terraform. Production runs in ap-south-1 (Mumbai). Staging runs in ap-southeast-1 (Singapore). Frontend SPAs are on Cloudflare Pages and are not in Terraform scope.

Environments

Network Layout

Each environment has a VPC with 3 public and 3 private subnets across availability zones (a, b, c), one NAT Gateway in public subnet 1a, and one Internet Gateway.

VPC (10.0.0.0/16)
├── Public subnets:  10.0.1.0/24  10.0.2.0/24  10.0.3.0/24
│   └── Bastion EC2, NAT Gateway, ALB/NLB
└── Private subnets: 10.0.10.0/24 10.0.11.0/24 10.0.12.0/24
    └── ECS tasks, Aurora, ElastiCache, ClickHouse EC2

ECS Services

Load Balancers

Databases

Aurora MySQL (RDS)

Aurora MySQL 8.0 Serverless v2. Scales automatically between min and max ACU when queries arrive, drops to near-zero ACU when idle.

• Master credentials stored in Secrets Manager: zelly/aurora/master
• Deletion protection enabled in production
• Schemas: astro_primary, ecom_store_front, backoffice — created by app migrations, not Terraform
• Staging: publicly accessible (connect directly without VPN)
• Production: private subnet only (requires WireGuard VPN via bastion)

ElastiCache Redis

Redis 7.x single-node cluster in private subnet. Used for BullMQ job queues and application caching (tenant tokens, sessions).

• Auth token in Secrets Manager: zelly/redis/auth
• Queue names: store-events, SHOPIFY_WEBHOOK, SHOPIFY_SETTINGS_PUSH, SHOPIFY_SETTINGS_FETCH, SHOPIFY_CATALOG_SYNC

ClickHouse (EC2)

ClickHouse 24.3 running in Docker on a private EC2 instance. Used exclusively for analytics — events-consumer writes, orion-backend reads.

• HTTP API on port 8123, native protocol on port 9000
• Init SQL from store-events-consumer/docker/clickhouse/init/
• EBS volume for persistence (gp3)

Bastion & WireGuard VPN

A t3.micro EC2 bastion in public subnet 1a provides access to private resources.

• SSH key pair required (provide public key in terraform.tfvars)
• WireGuard VPN server on UDP port 51820 — VPN subnet: 10.10.0.0/24
• Once connected to VPN, all private resources are reachable by private IP — no per-resource SSH tunnels needed
• Client config generated as Terraform output (one peer config per developer)

# After terraform apply, get your client config:
terraform output wireguard_client_config_peer1

# Save to /etc/wireguard/wg0.conf, then:
sudo wg-quick up wg0

# Now private resources are reachable:
mysql -h <aurora_endpoint> -u root -p
redis-cli -h <elasticache_endpoint> -a <token>
curl http://<clickhouse_private_ip>:8123/?query=SELECT+1

Secrets Management

All sensitive values live in AWS Secrets Manager. ECS task execution role has secretsmanager:GetSecretValue on zelly/*.

Terraform Execution

Prerequisites

Bootstrap the S3 state backend once (run manually before the first terraform init):

aws s3api create-bucket \
  --bucket zelly-terraform-state \
  --region ap-south-1 \
  --create-bucket-configuration LocationConstraint=ap-south-1

aws s3api put-bucket-versioning \
  --bucket zelly-terraform-state \
  --versioning-configuration Status=Enabled

aws dynamodb create-table \
  --table-name zelly-terraform-locks \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST \
  --region ap-south-1

Apply staging

cd terraform/environments/staging

terraform init

# Create terraform.tfvars from the example and fill in real values
cp ../../terraform.tfvars.example terraform.tfvars
# Edit: bastion_ssh_public_key, cloudflare_api_token, domain names, alert email

terraform plan
terraform apply

Apply production

cd terraform    # root directory — NOT environments/production/

terraform init

cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars

terraform plan
terraform apply

EFS (Caddy Certificate Storage)

EFS is mounted to the Caddy container in the storefront ECS task at /data. Caddy uses this to persist ACME certificates across task restarts and replacements. Without EFS, every new task would request a fresh cert and hit Let's Encrypt rate limits.

Observability