mirror of
https://github.com/Sea-Haven-Industries/front-integrations.git
synced 2026-09-30 15:23:12 +00:00
Adam Moussa
1ad265b177
Freeze SAM CD and add Terraform for seahaven-prod (Lambdas, DynamoDB, EventBridge, alarms) so HCP becomes the sole deploy path. Include prod secret ARNs in the tfvars example for workspace wiring.
192 lines
8.3 KiB
Markdown
192 lines
8.3 KiB
Markdown
# front-integrations
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Front platform integrations for Sea Haven Industries. Two scheduled Lambdas deployed to **seahaven-prod** via HCP Terraform workspace `front-integrations-prod` (PLAT-72).
|
|
|
|
1. **SLA Monitor** — checks Front conversations for SLA breaches and sends tiered Slack alerts
|
|
2. **User Sync** — pulls Google Workspace user profiles and syncs job title + phone to Front teammate custom fields
|
|
|
|
## Architecture
|
|
|
|
```
|
|
EventBridge (every 15 min, 8 AM-5 PM ET, Mon-Fri)
|
|
|
|
|
v
|
|
front-sla-monitor (Python 3.12, arm64)
|
|
|
|
|
+-- Secrets Manager --> front-integrations/front-api-token
|
|
+-- Secrets Manager --> front-integrations/slack-bot-token
|
|
|
|
|
+-- GET Front API /inboxes --> filter to configured inboxes
|
|
+-- GET Front API /inboxes/{id}/conversations --> open conversations
|
|
|
|
|
+-- DynamoDB (front-sla-alerts) --> dedup + first-run-of-day detection
|
|
|
|
|
+-- Morning (first run) --> summary to #front-sla-alerts
|
|
+-- Tier 1 (1 hr) --> Slack DM assignee or #front-sla-alerts
|
|
+-- Tier 2 (1 day) --> Slack DM Adam
|
|
|
|
|
|
EventBridge (weekdays 6:00 AM ET)
|
|
|
|
|
v
|
|
front-user-sync (Python 3.12, arm64)
|
|
|
|
|
+-- Secrets Manager --> front-integrations/google-service-account
|
|
+-- Secrets Manager --> front-integrations/front-api-token
|
|
|
|
|
+-- GET Google Admin Directory API --> list users in target OUs
|
|
+-- PATCH Front API /teammates/alt:email:{email} --> update custom_fields
|
|
```
|
|
|
|
## SLA Rules
|
|
|
|
| Tier | Threshold | Action |
|
|
|---|---|---|
|
|
| 1 | 1 business hour without reply | Slack DM the assignee, or post to #front-sla-alerts if unassigned |
|
|
| 2 | 1 business day without reply | Slack DM Adam |
|
|
|
|
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/
|
|
├── terraform/ # HCP Terraform config (sole deploy path)
|
|
│ ├── build_packages.sh # Pip-install user_sync deps for arm64 Lambda zips
|
|
│ └── *.tf
|
|
├── template.yaml # Legacy SAM template (retained until post-cutover hygiene)
|
|
├── 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
|
|
|
|
- **Account / region:** seahaven-prod `011934824531`, `us-east-1`
|
|
- **IaC:** Terraform under `terraform/` (HCP remote apply, Manual until sealed)
|
|
- **Lambda:** `front-sla-monitor` — Python 3.12, arm64, 256 MB, 300s timeout, 60-day log retention
|
|
- **Lambda:** `front-user-sync` — Python 3.12, arm64, 256 MB, 300s timeout, 60-day log retention
|
|
- **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
|
|
- **IAM:** Execution roles under path `/tf-managed/` with `seahaven-lambda-execution-boundary`
|
|
- **Secrets:** ARNs as Terraform variables; values never in state
|
|
|
|
## Monitoring
|
|
|
|
CloudWatch alarms publish to the shared `site-alerts` SNS topic in seahaven-prod. All alarms are ALARM-only (no OK/recovery notification) and treat missing data as `notBreaching`.
|
|
|
|
| Alarm | Metric | Trigger |
|
|
|---|---|---|
|
|
| `front-sla-monitor-errors` | Lambda `Errors` (Sum) | Any invocation error in a 5-min window |
|
|
| `front-sla-monitor-throttles` | Lambda `Throttles` (Sum) | Any throttled invocation in a 5-min window |
|
|
| `front-sla-monitor-duration` | Lambda `Duration` (Max) | Run exceeds 270s (90% of the 300s timeout) |
|
|
| `front-user-sync-errors` | Lambda `Errors` (Sum) | Any invocation error in a 5-min window |
|
|
| `front-user-sync-throttles` | Lambda `Throttles` (Sum) | Any throttled invocation in a 5-min window |
|
|
| `front-user-sync-duration` | Lambda `Duration` (Max) | Run exceeds 270s (90% of the 300s timeout) |
|
|
| `front-sla-alerts-read-throttle` | DynamoDB `ReadThrottleEvents` (Sum) | Any read throttle on the table |
|
|
| `front-sla-alerts-write-throttle` | DynamoDB `WriteThrottleEvents` (Sum) | Any write throttle on the table |
|
|
|
|
## Secrets (Secrets Manager)
|
|
|
|
| Secret | Purpose |
|
|
|---|---|
|
|
| `front-integrations/front-api-token` | Front API token (shared by both Lambdas) |
|
|
| `front-integrations/slack-bot-token` | Slack Bot User OAuth Token for SLA alerts |
|
|
| `front-integrations/google-service-account` | Google Cloud service account JSON key |
|
|
|
|
## Documentation
|
|
|
|
The canonical map of Sea Haven's AWS infrastructure lives in Confluence. This project's `front-integrations` stack is represented there as a Mermaid subgraph.
|
|
|
|
- **[AWS Architecture Map](https://seahaven.atlassian.net/wiki/spaces/IT/pages/1540098)** (Confluence, IT space, page 1540098)
|
|
|
|
## Setup
|
|
|
|
### 1. Create the Slack App
|
|
|
|
1. Go to https://api.slack.com/apps and create **Front SLA Monitor** (see `slack-app-manifest.yaml`)
|
|
2. Add Bot Token Scopes: `chat:write`, `users:read`, `users:read.email`
|
|
3. Install to workspace, copy Bot User OAuth Token
|
|
4. Create `#front-sla-alerts` channel and invite the bot
|
|
|
|
### 2. Create a Front API Token
|
|
|
|
1. Front > Settings > Developers > API tokens
|
|
2. Create a token with conversation read + teammate read/write scope
|
|
|
|
### 3. Set Up Google Workspace Service Account
|
|
|
|
1. Enable **Admin SDK API** in Google Cloud Console
|
|
2. Create service account `front-directory-sync`, create JSON key
|
|
3. Enable Domain-Wide Delegation, copy Client ID
|
|
4. In Google Workspace Admin: Security > API Controls > Domain-Wide Delegation
|
|
5. Add Client ID with scope: `https://www.googleapis.com/auth/admin.directory.user.readonly`
|
|
|
|
### 4. Create Custom Fields in Front
|
|
|
|
1. Settings > Custom Fields > Teammates tab
|
|
2. Create: **Job Title** (String) and **Phone** (String)
|
|
|
|
### 5. Store Secrets in seahaven-prod
|
|
|
|
Create secrets in seahaven-prod (exact ARNs are wired into the Lambda boundary and Terraform variables). Strip trailing newlines before `put-secret-value`.
|
|
|
|
```bash
|
|
aws secretsmanager create-secret \
|
|
--name "front-integrations/front-api-token" \
|
|
--secret-string "YOUR_FRONT_API_TOKEN" \
|
|
--region us-east-1 --profile seahaven-prod
|
|
|
|
aws secretsmanager create-secret \
|
|
--name "front-integrations/slack-bot-token" \
|
|
--secret-string "xoxb-YOUR-SLACK-BOT-TOKEN" \
|
|
--region us-east-1 --profile seahaven-prod
|
|
|
|
aws secretsmanager create-secret \
|
|
--name "front-integrations/google-service-account" \
|
|
--secret-string file://path-to-service-account-key.json \
|
|
--region us-east-1 --profile seahaven-prod
|
|
```
|
|
|
|
### 6. Deploy
|
|
|
|
1. Set workspace variables in HCP (`front-integrations-prod`) from `terraform/terraform.tfvars.example`.
|
|
2. Keep `schedules_enabled=false` until DynamoDB row copy and cutover.
|
|
3. Apply from the HCP workspace (Manual apply until the stack is sealed). Do not use local `terraform apply` against prod.
|
|
|
|
## Manual Testing
|
|
|
|
```bash
|
|
aws lambda invoke --function-name front-sla-monitor --payload '{}' /dev/stdout --region us-east-1 --profile seahaven-prod
|
|
aws lambda invoke --function-name front-user-sync --payload '{}' /dev/stdout --region us-east-1 --profile seahaven-prod
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### SLA Monitor
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `ack_sla_minutes` | 60 | Business minutes before Tier 1 alert |
|
|
| `action_sla_minutes` | 1440 | Business minutes before Tier 2 alert |
|
|
| `adam_email` | adam@seahavenind.com | Tier 2 escalation recipient |
|
|
| `slack_alert_channel` | — | Channel ID for broadcast alerts |
|
|
| `monitor_inboxes` | Triage,California,... | Inbox names to monitor (empty = all shared) |
|
|
| `sla_monitor_start_date` | 2026-05-14 | Date monitoring begins |
|
|
|
|
### User Sync
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `google_admin_email` | adam@seahavenind.com | Google Workspace admin to impersonate |
|
|
| `google_org_units` | /Office/Scheduling,/Office/Operations | Org unit paths to sync |
|