docs: audit Terraform storage accounts (closes #151)

docs/infra/README.md

@@ -0,0 +1,43 @@
+# Infrastructure overview
+
+Terraform configs under `infra/` provision the Azure resources for the
+PostgreDataMigrationAppWithCSVLoader platform.
+
+## Folder structure
+
+- `infra/terraform/` — shared config. The authoritative resource definitions
+  live here. Currently used by dev; adapted into per-environment folders as
+  each environment is spun up.
+- `infra/terraform-{prod,staging,test}/` — per-environment overrides. Each
+  carries its own `backend` block pointing at an environment-specific state
+  storage account.
+  - `terraform-prod/main.tf` — state in `sttfstateprod7u8hql`
+  - `terraform-staging/main.tf` — state account name placeholder (filled in
+    via the one-time setup script when the environment is provisioned, #31)
+  - `terraform-test/main.tf` — same pattern
+
+## Storage account inventory
+
+| Account | Purpose | Status |
+|---|---|---|
+| `stpgte{env}{suffix}` (via `pg_storage`) | Postgres `pgdata` file share (50 GB); plus `csv-input` and `run-reports` blob containers | Account active (pgdata is live); the two blob containers are provisioned but unused |
+| `sttfstateprod7u8hql` | Terraform state backend for prod | Active |
+| staging / test state backends | Terraform state backends for those environments | Not yet provisioned (names will be filled in by the one-time setup script, #31) |
+
+## Where application file storage lives
+
+Not in Azure Blob. Per D4
+(`DECISIONS/2026-11-02-file-storage-backend.md`), uploaded CSV file bodies
+and row-level import records live in Postgres: BYTEA on
+`upload_blobs.content`, written in the same transaction as the audit entry.
+
+The `csv-input` and `run-reports` blob containers in `pg_storage` are
+provisioned but not wired to any Python code. See the comment above those
+resources in `infra/terraform/main.tf` for the review triggers that would
+reopen D4.
+
+## Related
+
+- D4 decision record: `DECISIONS/2026-11-02-file-storage-backend.md`
+- Storage audit issue: #151 (closed 2026-11-03)
+- One-time cloud setup: #31

infra/terraform/main.tf

@@ -73,6 +73,11 @@ resource "azurerm_container_registry" "acr" {
 }
 
 # --- Storage for PG persistent volume ------------------------------------
+#
+# The pg_storage account holds the Postgres data volume (pgdata) and two
+# blob containers that are provisioned but currently unused (see below).
+# The account itself must stay — pgdata depends on it. See docs/infra/README.md
+# for the full inventory.
 
 resource "azurerm_storage_account" "pg_storage" {
   name                     = "stpgte${var.environment}${local.suffix}"
@@ -83,14 +88,26 @@ resource "azurerm_storage_account" "pg_storage" {
   tags                     = local.tags
 }
 
+# The persistent volume for the PostgreSQL Container App. Database files
+# live here. Required by the pg Container App's volume mount.
 resource "azurerm_storage_share" "pg_data" {
   name                 = "pgdata"
   storage_account_id   = azurerm_storage_account.pg_storage.id
   quota                = 50 # GB
 }
 
 # --- Storage for CSV input + run reports ---------------------------------
-
+#
+# Provisioned ahead of time but currently unused — file bodies and migration
+# run reports both live in Postgres per D4
+# (DECISIONS/2026-11-02-file-storage-backend.md).
+#
+# Review trigger — revisit D4 if either:
+#   (a) pg_dump cycles become painful because BYTEA values bloat the dump; or
+#   (b) run reports grow past "a page of text" into large exports people
+#       download.
+# Either case = reopen D4 and wire these containers into the code.
+#
 resource "azurerm_storage_container" "csv_input" {
   name                  = "csv-input"
   storage_account_id    = azurerm_storage_account.pg_storage.id