front-integrations/README.md

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). The workspace working directory is terraform/. VCS file triggers use trigger-patterns = [terraform/**/*, src/**/*] because terraform/build_packages.sh builds every Lambda zip from src/. A src/-only merge must still queue a run.

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 (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.

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

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