From bd0682661f8c902255d4a21d72202deb98fa97c5 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Fri, 5 Jun 2026 17:26:22 -0400
Subject: [PATCH] Document purchase-orders table ownership (INFRA-1) (#49)

Add a Shared Resources section recording that this stack owns the
purchase-orders DynamoDB table and is the authoritative writer, with
payments-dashboard and seahaven-slack-bot as read-only consumers.
Note the cross-repo schema-coordination rule and the amazon-po-parser
direct-write exception being folded in under INFRA-51.
---
 README.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 16f74f9..98033c3 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ Coupa PO emails are received at `amazon_po@int.seahaven.com`, parsed by Claude H
 | `po-web-ui` | Function URL | HTML dashboard |
 
 **Tables:**
-- `purchase-orders` (PK: `po_number`, Streams: NEW_IMAGE) — shared with payments-dashboard and seahaven-slack-bot
+- `purchase-orders` (PK: `po_number`, Streams: NEW_IMAGE) — shared with seahaven-slack-bot (read-only; see Shared Resources)
 - `verified-sites` (PK: `siteCode`, GSI: `by-state`) — ~1,100 unique Amazon facility sites
 - `pending-site-review` (PK: `po_number`) — unresolvable POs for manual Payee Central verification
 
@@ -67,6 +67,24 @@ All Lambdas: Python 3.12, ARM64, 60-day log retention.
 
 **SES:** Both stacks add rules to the shared `INBOUND_MAIL` receipt rule set on `int.seahaven.com`.
 
+## Shared Resources
+
+### `purchase-orders` table (owned here)
+
+The `purchase-orders` DynamoDB table is **owned by this repo's `po-ingest` stack** (defined in `cdk/po_stack.py` with `RemovalPolicy.RETAIN` and `StreamViewType.NEW_IMAGE`). The `po-email-processor` Lambda is the authoritative writer — it performs the conditional inserts, revision overwrites, and cancellation updates described above.
+
+**Consumers (read-only):**
+
+| Repo | How it reads | Purpose |
+|---|---|---|
+| `seahaven-slack-bot` | `po-sync` (DynamoDB Streams + daily scan) and `wo-po-lookup` | Daily KB sync + Bedrock agent PO lookups |
+
+The consumer imports the table via `Table.fromTableName(...)` and is granted read-only access (`grantReadData`); it does not own or define it.
+
+**Schema-coordination rule:** Any change to the `purchase-orders` schema (partition key, item shape, attribute names, streams view type) must be coordinated with `seahaven-slack-bot`. The owner here ships the change; the consumer must be updated in lockstep so its readers do not break. Treat schema changes as a cross-repo migration, not a local edit.
+
+**Known exception (INFRA-51):** `amazon-po-parser` currently writes directly to `purchase-orders` outside this stack (backfill/enrichment scripts). This second writer is being folded into the `po-ingest` pipeline so this stack is the sole writer; until INFRA-51 closes, coordinate any schema change with `amazon-po-parser` as well.
+
 ## CI/CD
 
 GitHub Actions with reusable workflows from `Sea-Haven-Industries/.github`: