Update README with QBO OAuth flow, VPC, and static IP details
This commit is contained in:
Adam Moussa
parent
d1b91ae661
commit
26598e8fff
1 changed files with 24 additions and 14 deletions
38
README.md
38
README.md
|
|
@ -10,18 +10,24 @@ Slack DM
|
|||
▼
|
||||
API Gateway (bot.seahaven.com)
|
||||
│
|
||||
▼
|
||||
slack-webhook Lambda ← verifies Slack signature, returns 200 immediately
|
||||
│ (async invoke)
|
||||
▼
|
||||
slack-processor Lambda ← calls Bedrock Agent, logs to DynamoDB, posts reply
|
||||
├── POST /slack/events
|
||||
│ ▼
|
||||
│ slack-webhook Lambda ← verifies Slack signature, returns 200 immediately
|
||||
│ │ (async invoke)
|
||||
│ ▼
|
||||
│ slack-processor Lambda ← calls Bedrock Agent, logs to DynamoDB, posts reply
|
||||
│ │
|
||||
│ ▼
|
||||
│ Bedrock Agent (Claude Sonnet 4.5)
|
||||
│ ├── Knowledge Base (AOSS + S3) ← SA8000 docs, SOPs, employee handbook, Notion pages, POs, work orders, site list
|
||||
│ ├── QBO_Lookup action group ← QuickBooks vendor search (VPC, static IP)
|
||||
│ ├── Google_Maps_Lookup action group ← fallback vendor search
|
||||
│ └── WO_PO_Lookup action group ← work order, purchase order, and site lookups (DynamoDB direct)
|
||||
│
|
||||
▼
|
||||
Bedrock Agent (Claude Sonnet 4.5)
|
||||
├── Knowledge Base (AOSS + S3) ← SA8000 docs, SOPs, employee handbook, Notion pages, POs, work orders, site list
|
||||
├── QBO_Lookup action group ← QuickBooks vendor search
|
||||
├── Google_Maps_Lookup action group ← fallback vendor search
|
||||
└── WO_PO_Lookup action group ← work order, purchase order, and site lookups (DynamoDB direct)
|
||||
└── GET /qbo/*
|
||||
▼
|
||||
qbo-oauth Lambda (VPC, static IP) ← OAuth 2.0 connect/callback/disconnect/launch
|
||||
Outbound IP: 52.202.83.13 (NAT Gateway in seahaven-vpc)
|
||||
|
||||
EventBridge (daily 02:00 UTC)
|
||||
│
|
||||
|
|
@ -48,7 +54,10 @@ EventBridge (daily 02:00 UTC)
|
|||
| PO Data Source | DynamoDB `purchase-orders` (via po-ingest) |
|
||||
| Work Order Data Source | DynamoDB `WorkOrders` + `WorkOrderComments` (via workorder-ingest) |
|
||||
| Site Assignments | DynamoDB `SiteAssignments` (seeded from CSV via `scripts/seed-sites.ts`) |
|
||||
| VPC | `seahaven-vpc` (`vpc-0d3d4b67bd0cf8a68`) — QBO Lambdas only |
|
||||
| Static Outbound IP | `52.202.83.13` (NAT Gateway for Intuit IP allowlist) |
|
||||
| Webhook URL | `https://bot.seahaven.com/slack/events` |
|
||||
| QBO OAuth URLs | `/qbo/connect`, `/qbo/callback`, `/qbo/disconnect`, `/qbo/launch` |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
|
@ -64,7 +73,7 @@ These secrets must exist before deploying. The Slack, QBO, and Maps secrets must
|
|||
| Secret Name | Created | Structure |
|
||||
|---|---|---|
|
||||
| `seahaven/slack/credentials` | Manual (pre-deploy) | `{ "botToken": "xoxb-...", "signingSecret": "..." }` |
|
||||
| `seahaven/qbo/oauth` | Manual (pre-deploy) | `{ "clientId": "", "clientSecret": "", "refreshToken": "", "realmId": "" }` |
|
||||
| `seahaven/qbo/oauth` | Manual (pre-deploy) | `{ "clientId": "", "clientSecret": "", "refreshToken": "", "realmId": "" }` — refreshToken and realmId are auto-populated via `/qbo/connect` OAuth flow |
|
||||
| `seahaven/google/maps-api-key` | Manual (pre-deploy) | `{ "apiKey": "" }` |
|
||||
| `seahaven/notion/api-key` | Auto (CDK) | `{ "apiKey": "secret_..." }` |
|
||||
|
||||
|
|
@ -145,7 +154,7 @@ lib/
|
|||
constructs/
|
||||
knowledge-base.ts Bedrock KB + AOSS + S3 (via @cdklabs L2 construct)
|
||||
bedrock-agent.ts Bedrock Agent + QBO/Maps/WO-PO-Site action groups
|
||||
slack-handler.ts API Gateway + webhook/processor Lambdas
|
||||
slack-handler.ts API Gateway + webhook/processor Lambdas + QBO OAuth Lambda
|
||||
conversation-log.ts DynamoDB table
|
||||
notion-sync.ts EventBridge daily cron + notion-sync Lambda + Secrets Manager
|
||||
po-sync.ts EventBridge daily cron + po-sync Lambda
|
||||
|
|
@ -153,6 +162,7 @@ lib/
|
|||
lambda/
|
||||
slack-webhook/ Verifies Slack signature, fires processor async
|
||||
slack-processor/ Calls agent, writes DynamoDB, posts Slack reply
|
||||
qbo-oauth/ OAuth 2.0 connect/callback/disconnect/launch for QuickBooks
|
||||
qbo-lookup/ Bedrock action group — QuickBooks vendor search
|
||||
maps-lookup/ Bedrock action group — Google Maps Places search
|
||||
wo-po-lookup/ Bedrock action group — WO, PO, and site code lookups (DynamoDB direct)
|
||||
|
|
@ -166,7 +176,7 @@ scripts/
|
|||
|
||||
## Known Maintenance Items
|
||||
|
||||
- **QBO refresh token** expires after 100 days of inactivity. Rotate via the [Intuit OAuth Playground](https://developer.intuit.com/app/developer/playground) and update the `seahaven/qbo/oauth` secret.
|
||||
- **QBO OAuth** — the refresh token auto-rotates on every API call (persisted back to Secrets Manager). If the token ever expires (100 days of inactivity), reconnect via `https://bot.seahaven.com/qbo/connect`. To disconnect, visit `/qbo/disconnect`.
|
||||
- **Notion sync** runs daily at 02:00 UTC automatically. To trigger an immediate sync, invoke `seahaven-notion-sync` manually via the Lambda console or CLI.
|
||||
- **PO sync** runs daily at 02:00 UTC. Scans the `purchase-orders` DynamoDB table (from [po-ingest](https://github.com/Sea-Haven-Industries/po-ingest)) and exports each PO as markdown to the KB. Manual trigger: invoke `seahaven-po-sync`.
|
||||
- **Work order sync** runs daily at 02:00 UTC. Scans `WorkOrders` and `WorkOrderComments` DynamoDB tables (from [workorder-ingest](https://github.com/Sea-Haven-Industries/workorder-ingest)) and exports each work order + comment history as markdown to the KB. Manual trigger: invoke `seahaven-workorder-sync`.
|
||||
|
|
|
|||
Reference in a new issue