From 1f2237f4420c048ffd5bbe85b61f95429db71a3f Mon Sep 17 00:00:00 2001 From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com> Date: Tue, 12 May 2026 15:51:21 -0400 Subject: [PATCH] Update README for merged architecture and new features --- README.md | 93 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 54 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 8b6cb2c..b96f377 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # After-Hours Shift Manager -Slack bot for managing after-hours on-call shifts at Sea Haven Industries. Employees can pick up, drop, and swap shifts directly from Slack. Changes automatically update 3CX ring group 800 routing. +Slack bot for managing after-hours on-call shifts at Sea Haven Industries. Employees can pick up, drop, and swap shifts directly from Slack. Changes automatically update 3CX ring group routing via the integrated ring scheduler. ## How It Works -A recurring weekly schedule assigns employees to after-hours phone duty (5pm-8am). Any unassigned day shows as **Available** in Slack with a pickup button. When someone picks up or drops a shift for today, the 3CX phone system is updated immediately. Future changes take effect when the 3CX scheduler runs at 8am. +A recurring weekly schedule assigns employees to after-hours phone duty. Weekend shifts are split into Day (8am-5pm) and Night (5pm-8am). Any unassigned shift shows as **Available** in Slack with a pickup button. When someone picks up or drops a shift for today, the 3CX ring group is updated immediately. Future changes take effect when the ring scheduler runs at 8am daily and 5pm on weekends. + +The weekly schedule post is updated live when shifts change, and the previous week's post is automatically deleted when the new one goes out. ## Slack Commands @@ -23,15 +25,49 @@ A recurring weekly schedule assigns employees to after-hours phone duty (5pm-8am | `/oncall rate ` | Set a per-person shift rate | | `/oncall help` | Show help | +### Admin Commands + +Available to users listed in `admin_users` in the CONFIG record: + +| Command | Description | +|---|---| +| `/oncall admin override ` | Assign a shift to an extension | +| `/oncall admin open ` | Mark a shift as open | +| `/oncall admin clear ` | Remove override (revert to weekly) | +| `/oncall admin roster add ` | Add an employee to the roster | +| `/oncall admin roster remove ` | Remove an employee | +| `/oncall admin roster rename ` | Rename an employee | + Dates accept: `today`, `tomorrow`, `monday`-`sunday`, `4/5`, `2026-04-05` ## Architecture -- **Runtime**: Python 3.12 on AWS Lambda (via API Gateway) +- **Runtime**: Python 3.12 on AWS Lambda (arm64) - **Data**: DynamoDB single-table (`afterhours-shifts`) -- **IaC**: AWS SAM (`template.yaml`) +- **IaC**: AWS SAM (`template.yaml`) with shared Lambda Layer - **Slack**: Slack Bolt framework with `/oncall` slash command -- **3CX Integration**: Invokes the `3cx-ring-group-scheduler` Lambda for same-day changes; the scheduler reads DynamoDB for future dates +- **3CX Integration**: Ring group routing updated directly via 3CX RingGroup XAPI +- **Secrets**: AWS Secrets Manager (`afterhours-shift-manager/*`) + +### Lambda Functions + +| Function | Trigger | Purpose | +|---|---|---| +| `afterhours-shift-manager` | API Gateway (POST /slack/events) | Slack bot — handles `/oncall` commands and interactive buttons | +| `afterhours-weekly-post` | EventBridge (Monday 7am ET) | Posts weekly schedule to Slack, sends pay report email | +| `afterhours-roster-sync` | EventBridge (daily 6am ET) | Syncs employee roster from 3CX | +| `afterhours-ring-scheduler` | EventBridge (daily 8am ET + weekend 5pm ET) | Updates 3CX ring group routing based on who's on shift | + +### Project Layout + +``` +src/ + slack-bot/ Slack Bolt Lambda (handler + app) + weekly-post/ Monday schedule + pay post + roster-sync/ Daily 3CX roster sync + ring-scheduler/ 3CX ring group routing updates + shared/ Lambda Layer (schedule, blocks, 3CX client, secrets) +``` ### DynamoDB Schema @@ -42,12 +78,23 @@ Single table with `PK` / `SK` keys: | `ROSTER` | `` | Employee: name, extension, slack_user_id | | `WEEKLY` | `` | Default weekly schedule: extension, name | | `OVERRIDE` | `` | Date override from pickup/drop (or `OPEN`) | +| `SCHEDULE_POST` | `` | Current schedule message timestamp | | `PAY` | `` | Weekly pay record (Monday date key) | -| `CONFIG` | `CONFIG` | Settings: shift_rate, fallback_extension | +| `CONFIG` | `CONFIG` | Settings: shift_rate, fallback_extension, admin_users | + +### Secrets Manager + +| Secret | Description | +|---|---| +| `afterhours-shift-manager/slack-bot-token` | Slack bot OAuth token (`xoxb-...`) | +| `afterhours-shift-manager/slack-signing-secret` | Slack app signing secret | +| `afterhours-shift-manager/3cx-domain` | 3CX FQDN (e.g. `company.3cx.us`) | +| `afterhours-shift-manager/3cx-client-id` | 3CX OAuth2 client ID | +| `afterhours-shift-manager/3cx-client-secret` | 3CX OAuth2 client secret | ## Deployment -Merges to `main` are automatically deployed via **CodePipeline + CodeBuild**. The pipeline stack (`afterhours-shift-manager-pipeline`) watches the GitHub repo and runs `sam build && sam package` then deploys via CloudFormation changeset. +Merges to `main` are automatically deployed via **GitHub Actions** using reusable SAM workflows from the Sea Haven org. For manual deploys: @@ -57,35 +104,3 @@ sam deploy ``` See [SETUP.md](SETUP.md) for full deployment and Slack app creation instructions. - -### Version Bumps - -A GitHub Actions workflow runs daily at 6pm ET, collects all PRs merged since the last version tag, creates a semver patch bump (e.g. v1.6.0 → v1.6.1), updates the Slack changelog canvas, and posts a summary to the team channel. Minor bumps can be triggered manually via `workflow_dispatch`. - -### SSM Parameters - -| Parameter | Description | -|---|---| -| `/afterhours-shift-manager/slack-bot-token` | Slack bot OAuth token (`xoxb-...`) | -| `/afterhours-shift-manager/slack-signing-secret` | Slack app signing secret | -| `/afterhours-shift-manager/channel-id` | Slack channel ID for notifications | - -## Weekly Auto-Post - -Every Monday at 7am ET, the bot posts the week's schedule to the configured channel with pickup buttons for any available shifts. - -## Pay Report Email - -A weekly Bonus Pay Summary email is sent via SES to payroll@seahaven.com with a table showing each employee's name, rate, and total pay for the week. - -### Lambda Functions - -| Function | Trigger | Purpose | -|---|---|---| -| `afterhours-shift-manager` | API Gateway (POST /slack/events) | Slack bot — handles `/oncall` commands and interactive buttons | -| `afterhours-weekly-post` | EventBridge (Monday 7am ET) | Posts weekly schedule to Slack, sends pay report email | -| `afterhours-roster-sync` | EventBridge (daily 6am ET) | Syncs employee roster from 3CX | - -## Related - -- [3cx-ring-scheduler](https://github.com/Sea-Haven-Industries/3cx-ring-scheduler) — the Lambda that updates 3CX ring group routing daily