adam/front-integrations
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/front-integrations.git synced 2026-09-30 06:03:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document SAM template as IaC component in README

Browse source 
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.
This commit is contained in:
Adam Moussa 2026-07-10 15:56:42 -04:00
parent 16a8d789d2
commit f73dae860d
No known key found for this signature in database
1 changed files with 71 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
README.md
View file

@ -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`.