front-integrations/README.md

# front-integrations

![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)
![Terraform](https://img.shields.io/badge/Terraform-844FBA?logo=terraform&logoColor=white)
![Slack](https://img.shields.io/badge/Slack-integration-4A154B?logo=slack&logoColor=white)
![CI](https://github.com/Sea-Haven-Industries/front-integrations/actions/workflows/ci.yaml/badge.svg)

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