Clarify seed terraform

Author: mjewildnhs

infrastructure/terraform/components/callbacks/locals.tf

@@ -9,11 +9,11 @@ locals {
   mock_client_key  = replace(local.mock_client_file, ".json", "")
   mock_client_path = "${path.module}/../../../../tests/integration/fixtures/${local.mock_client_file}"
 
-  discovered_config_files = fileset(local.clients_dir_path, "*.json")
+  config_files_from_s3 = fileset(local.clients_dir_path, "*.json")
   config_files = var.deploy_mock_client_subscriptions ? setunion(
-    local.discovered_config_files,
+    local.config_files_from_s3,
     toset([local.mock_client_file])
-  ) : local.discovered_config_files
+  ) : local.config_files_from_s3
 
   config_clients = merge([
     for filename in local.config_files : {

infrastructure/terraform/components/callbacks/sync-client-config.sh

@@ -1,5 +1,20 @@
 #!/usr/bin/env bash
 
+# This script seeds local client subscription JSON files from the config bucket
+# before Terraform evaluates locals/fileset (see local.config_clients in locals.tf).
+# It handles the S3 bucket not existing on first apply.
+# Deployment Lifecycle:
+# - Sync client JSON files from S3 into "modules/clients" before Terraform runs.
+# - Terraform then reads the local fileset from "modules/clients" as input.
+# - On later deployments, files are refreshed from bucket state each run.
+#
+# Deployment Lifecycle dev/test environment:
+# - Special handling is needed to seed test data and have it take effect on the first apply, as the bucket and files won't exist yet
+# - Terraform merges in the local mock fixture config into local.config_clients
+# - Terraform uploads mock-it-client.json to the config bucket
+# - On subsequent deployments, that mock config is synced from S3 and handled
+#   through the normal fileset path.
+
 set -euo pipefail
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -26,6 +41,7 @@ if ! sync_output=$(aws s3 sync "s3://${bucket_name}/${s3_prefix}" "${clients_dir
   --include "*.json" \
   --only-show-errors 2>&1); then
   if [[ "${sync_output}" == *"NoSuchBucket"* ]]; then
+    # Expected on first apply before Terraform creates the bucket.
     echo "Client config bucket not found yet; skipping sync for first run"
   else
     echo "Failed to sync client config from S3" >&2