How liam-johnston/wwc-sentiment-bot works
Step 1: Identify the project type and purpose
• This is a serverless, full-stack bot application (“Sentiment Analysis Bot”) that integrates Slack events with Google Cloud services to analyze message sentiment and post replies.
• The bot consists of two Cloud Functions: one to receive Slack events (entry-point) and one to process sentiment (sentiment-bot). Infrastructure is defined and deployed via Terraform modules.
Step 2: Analyze the file structure
Top-level key directories and files:
• deploy/ – Terraform code provisioning GCP resources (Cloud Functions, Pub/Sub, Firestore, IAM, Secrets, Alerts)
• entry-point/ – HTTP-triggered Cloud Function code for receiving Slack events
• sentiment-bot/ – Pub/Sub-triggered Cloud Function code for sentiment analysis and Slack replies
• slack-config/ – Slack App manifest
• docker-compose.yaml & builder/Dockerfile – local development / build environment
• .env.template, Makefile – scripts and templates for env setup and deployment
Step 3: Examine the README
• Describes Slack App creation (app-manifest.yaml), environment setup (make env), GCP login, and make deploy (which invokes Terraform).
• After deployment, you wire the Slack Event Subscriptions to the generated entry_point_invoke_url.
Step 4: Main components and interactions
a. Components:
1. Slack Platform (Event Subscriptions, Slack API)
2. Entry-Point Cloud Function
3. Google Pub/Sub topic
4. Sentiment-Bot Cloud Function
5. Google Cloud Natural Language API
6. Firestore (for event leasing/deduplication)
7. Secret Manager (Slack secrets, OAuth tokens)
8. Terraform / CI (build & deploy)
9. Local dev containers (Docker Compose)
b. Relationships & data flow:
• Slack → (HTTP event) → Entry-Point Function
– Validates signature, sanitizes payload
– Writes event message → Pub/Sub topic
• Pub/Sub → (push/subscription) → Sentiment-Bot Function
– Reads event, uses Firestore for leasing/deduplication
– Calls Cloud Language API → receives sentiment score
– Calls Slack API → posts sentiment reply
• Terraform deploys and wires up all the above (topics, functions, IAM roles, secrets)
• Local dev: Docker Compose spins up emulators for Pub/Sub, Firestore, Functions (optional)
c. Architectural patterns & principles:
• Serverless microservices: each function has a single responsibility
• Event-driven design: Slack events land on Pub/Sub, decoupling ingestion from processing
• Infrastructure as Code: Terraform modules for repeatable, versioned deployments
• Secret management: Terraform pulls Slack tokens from Secret Manager
• Local emulation: Docker-compose for offline / TDD
d. Key technologies/frameworks:
• Node.js for Cloud Functions
• Google Cloud Functions, Pub/Sub, Firestore, Secret Manager, Cloud Language API
• Terraform for infra provisioning
• Slack SDK / HTTP API
• Docker & Docker Compose for local development
• Makefile for automation
• “Slack → Entry-Point Fn → Pub/Sub → Sentiment-Bot Fn → Slack API” flow
• Local/dev overlay with Docker Compose and emulators
• Slack Platform
– Event Subscriptions → invokes Entry-Point Function (HTTP)
– Slack API endpoint ← called by Sentiment-Bot Function
• Entry-Point Cloud Function
– Node.js: index.js, validation & sanitation utils
– Repository adaptor → Pub/Sub client
• Google Pub/Sub Topic
– decouples ingestion from processing
• Sentiment-Bot Cloud Function
– eventLease (Firestore client)
– language.js (Cloud Language API client)
– slack.js (Slack API client)
• Firestore
– used by eventLease to prevent duplicate processing
• Cloud Language API
– external, invoked over HTTPS
• Secret Manager
– stores Slack signing secret & OAuth token; mounted via Terraform
• Terraform (deploy/)
– modules: alerts, functions, pubsub, firestore, iam, secrets
– outputs entry_point_invoke_url
• Local Dev
– Docker Compose emulators (Pub/Sub, Firestore)
– builder/Dockerfile for packaging functions