Add README with architecture, deployment, and maintenance docs
This commit is contained in:
Adam Moussa
parent
f7e63e50c9
commit
f01c3f81ce
1 changed files with 130 additions and 0 deletions
130
README.md
Normal file
130
README.md
Normal file
|
|
@ -0,0 +1,130 @@
|
|||
# Seahaven Slack Bot
|
||||
|
||||
Internal Slack DM assistant for Sea Haven Industries, powered by AWS Bedrock. Employees can ask questions about vendors, company policies, SOPs, and SA8000 compliance via direct message.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
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
|
||||
│
|
||||
▼
|
||||
Bedrock Agent (Claude 3.5 Sonnet)
|
||||
├── Knowledge Base (AOSS + S3) ← SA8000 docs, SOPs, employee handbook
|
||||
├── QBO_Lookup action group ← QuickBooks vendor search
|
||||
└── Google_Maps_Lookup action group ← fallback vendor search
|
||||
```
|
||||
|
||||
### Vendor Query Priority
|
||||
1. **QBO** — existing vetted vendors in QuickBooks Online
|
||||
2. **Knowledge Base** — approved vendor lists in internal docs
|
||||
3. **Google Maps** — fallback for net-new vendor discovery
|
||||
|
||||
## Stack
|
||||
|
||||
| Resource | Details |
|
||||
|---|---|
|
||||
| AWS Account | 328440206208, us-east-1 |
|
||||
| CDK | TypeScript, v2 |
|
||||
| LLM | Claude 3.5 Sonnet v2 (`anthropic.claude-3-5-sonnet-20241022-v2:0`) |
|
||||
| Embeddings | Amazon Titan Embed Text V2 (1024 dimensions) |
|
||||
| Vector Store | OpenSearch Serverless (VECTORSEARCH) |
|
||||
| Conversation Log | DynamoDB `seahaven-conversations` (90-day TTL) |
|
||||
| Webhook URL | `https://bot.seahaven.com/slack/events` |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 22+
|
||||
- AWS CDK (`npm install -g aws-cdk`)
|
||||
- Docker Desktop (required by `@cdklabs/generative-ai-cdk-constructs` for Lambda bundling)
|
||||
- AWS credentials configured locally
|
||||
|
||||
## Secrets Manager
|
||||
|
||||
These three secrets must exist before deploying. Create them via the AWS Console or CLI:
|
||||
|
||||
| Secret Name | Structure |
|
||||
|---|---|
|
||||
| `seahaven/slack/credentials` | `{ "botToken": "xoxb-...", "signingSecret": "..." }` |
|
||||
| `seahaven/qbo/oauth` | `{ "clientId": "", "clientSecret": "", "refreshToken": "", "realmId": "" }` |
|
||||
| `seahaven/google/maps-api-key` | `{ "apiKey": "" }` |
|
||||
|
||||
## Deployment
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npx cdk bootstrap aws://328440206208/us-east-1 # first time only
|
||||
npx cdk deploy
|
||||
```
|
||||
|
||||
The deploy takes ~15 minutes on first run. The AOSS collection and vector index creation are the slow steps — both handled automatically.
|
||||
|
||||
Stack outputs after deploy:
|
||||
- `KBDocsBucketName` — S3 bucket to upload knowledge base documents
|
||||
- `AgentId` — Bedrock Agent ID
|
||||
- `SlackWebhookUrl` — URL to register in Slack app settings
|
||||
|
||||
## Post-Deployment Setup
|
||||
|
||||
### 1. Upload knowledge base documents
|
||||
|
||||
Upload SA8000 compliance docs, SOPs, and the employee handbook to the S3 bucket printed in stack outputs. Supported formats: PDF, DOCX, TXT, HTML, CSV, XLSX.
|
||||
|
||||
```bash
|
||||
aws s3 cp ./your-docs/ s3://<KBDocsBucketName>/ --recursive
|
||||
```
|
||||
|
||||
### 2. Trigger KB sync
|
||||
|
||||
```bash
|
||||
aws bedrock-agent start-ingestion-job \
|
||||
--knowledge-base-id <AgentId from outputs> \
|
||||
--data-source-id <DataSourceId> \
|
||||
--region us-east-1
|
||||
```
|
||||
|
||||
Or trigger from the Bedrock console: **Knowledge Bases → seahaven-kb → Sync**.
|
||||
|
||||
### 3. Configure Slack app
|
||||
|
||||
In the [Slack API dashboard](https://api.slack.com/apps):
|
||||
|
||||
1. **Event Subscriptions** → enable → set Request URL to `https://bot.seahaven.com/slack/events`
|
||||
2. Subscribe to bot event: `message.im`
|
||||
3. **OAuth & Permissions** → Bot Token Scopes: `chat:write`, `im:history`
|
||||
4. **App Home** → Messages Tab → enable, allow users to send messages
|
||||
5. Reinstall to workspace if prompted
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
bin/
|
||||
seahaven-slack-bot.ts CDK app entry point
|
||||
lib/
|
||||
seahaven-slack-bot-stack.ts Main stack
|
||||
constructs/
|
||||
knowledge-base.ts Bedrock KB + AOSS + S3 (via @cdklabs L2 construct)
|
||||
bedrock-agent.ts Bedrock Agent + QBO/Maps action groups
|
||||
slack-handler.ts API Gateway + webhook/processor Lambdas
|
||||
conversation-log.ts DynamoDB table
|
||||
lambda/
|
||||
slack-webhook/ Verifies Slack signature, fires processor async
|
||||
slack-processor/ Calls agent, writes DynamoDB, posts Slack reply
|
||||
qbo-lookup/ Bedrock action group — QuickBooks vendor search
|
||||
maps-lookup/ Bedrock action group — Google Maps Places search
|
||||
scripts/
|
||||
create-aoss-index.ts Manual fallback for AOSS index creation (not needed in normal deploy)
|
||||
```
|
||||
|
||||
## 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.
|
||||
- **KB sync** must be triggered manually after uploading new documents. Consider adding a scheduled EventBridge rule for automatic nightly syncs.
|
||||
Reference in a new issue