From 4506e3cbf70a50342741613011bc1714f9b4aa46 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:07:12 -0400
Subject: [PATCH] Document SAM template as IaC component in README (#23)

The README described the deployed AWS resources but never mentioned
template.yaml itself, the SAM project layout, the global function
defaults, the full parameter set, or the stack outputs. Add a
Project Structure section and an Infrastructure section so the
template.yaml infrastructure-as-code component is documented
accurately.
---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/README.md b/README.md
index 3a9869a..5b3e6cb 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,22 @@ front-user-sync (Python 3.12, arm64)
 
 Business time counts weekday hours only (Mon-Fri, Eastern time). Alerts are only sent during business hours (8 AM-5 PM ET). Overnight breaches produce a single morning summary.
 
+## Project Structure
+
+```
+front-integrations/
+├── template.yaml            # AWS SAM template — all infrastructure (see below)
+├── samconfig.toml.example   # Deploy config template (copy to samconfig.toml, gitignored)
+├── slack-app-manifest.yaml  # Slack app manifest for the SLA Monitor bot
+└── src/
+    ├── sla_monitor/         # front-sla-monitor Lambda
+    │   ├── app.py           # handler: app.handler
+    │   └── requirements.txt
+    └── user_sync/           # front-user-sync Lambda
+        ├── app.py           # handler: app.handler
+        └── requirements.txt
+```
+
 ## AWS Resources
 
 - **Stack:** `front-integrations` (SAM, us-east-1)
@@ -60,6 +76,61 @@ Business time counts weekday hours only (Mon-Fri, Eastern time). Alerts are only
 - **DynamoDB:** `front-sla-alerts` — alert history per conversation + monitor state, 7-day TTL
 - **EventBridge:** SLA check every 15 min during business hours; user sync daily at 6 AM ET weekdays
 
+## Infrastructure (`template.yaml`)
+
+All of the resources above are declared as code in a single AWS SAM template,
+[`template.yaml`](template.yaml) at the repository root (`Transform: AWS::Serverless-2016-10-31`).
+It is the only source of infrastructure truth — there are no console-created or
+CDK resources in this stack. `sam build` / `sam deploy` render it to a
+CloudFormation stack named `front-integrations` in `us-east-1`.
+
+### Global defaults
+
+`Globals.Function` applies to every Lambda unless overridden per-function:
+
+- Runtime `python3.12`, architecture `arm64`
+- 256 MB memory, 300s timeout
+- Permissions boundary `arn:aws:iam::328440206208:policy/seahaven-lambda-execution-boundary`
+
+### Resources declared
+
+| Logical ID | Type | Notes |
+|---|---|---|
+| `SlaMonitorFunction` | `AWS::Serverless::Function` | `front-sla-monitor`; `Schedule` event `cron(0/15 12-22 ? * MON-FRI *)` (UTC) |
+| `UserSyncFunction` | `AWS::Serverless::Function` | `front-user-sync`; `Schedule` event `cron(0 11 ? * MON-FRI *)` (UTC) |
+| `AlertsTable` | `AWS::DynamoDB::Table` | `front-sla-alerts`; PAY_PER_REQUEST, `conversationId` hash key, `ttl` TTL attribute |
+| `SlaMonitorLogGroup`, `UserSyncLogGroup` | `AWS::Logs::LogGroup` | 60-day retention; each function `DependsOn` its group |
+| 8 alarms | `AWS::CloudWatch::Alarm` | 3 per Lambda + 2 on the table — see [Monitoring](#monitoring) |
+
+Each function carries a least-privilege inline IAM policy: `secretsmanager:GetSecretValue`
+scoped to only the secret ARNs it reads. `SlaMonitorFunction` additionally gets a
+`DynamoDBCrudPolicy` scoped to `AlertsTable`.
+
+### Parameters
+
+Secret ARNs and the alert channel are passed in at deploy time (via `parameter_overrides`
+in `samconfig.toml` — see [`samconfig.toml.example`](samconfig.toml.example) — or the
+`SAM_PARAMETER_OVERRIDES` Actions secret). They have no defaults and must be supplied:
+
+| Parameter | Description |
+|---|---|
+| `FrontApiTokenSecretArn` | ARN of the Front API token secret |
+| `SlackBotTokenSecretArn` | ARN of the Slack bot token secret |
+| `GoogleServiceAccountSecretArn` | ARN of the Google service account key secret |
+| `SlackAlertChannel` | Slack channel ID for `#front-sla-alerts` |
+
+The remaining parameters (`AckSlaMinutes`, `ActionSlaMinutes`, `MonitorInboxes`,
+`GoogleOrgUnits`, etc.) tune behavior and ship with sensible defaults — see
+[Configuration](#configuration).
+
+### Outputs
+
+| Output | Value |
+|---|---|
+| `SlaMonitorFunctionArn` | `front-sla-monitor` Lambda ARN |
+| `UserSyncFunctionArn` | `front-user-sync` Lambda ARN |
+| `AlertsTableName` | `front-sla-alerts` table name |
+
 ## Monitoring
 
 CloudWatch alarms publish to the shared `site-alerts` SNS topic (`arn:aws:sns:us-east-1:328440206208:site-alerts`). All alarms are ALARM-only (no OK/recovery notification) and treat missing data as `notBreaching`.