# liam-johnston/wwc-sentiment-bot architecture

> Architecture diagram of the GitHub repository liam-johnston/wwc-sentiment-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liam-johnston/wwc-sentiment-bot
- Repository: https://github.com/liam-johnston/wwc-sentiment-bot

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        SlackPlatform["Slack Platform"]:::external
        LanguageAPI["Cloud Language API"]:::external
    end

    %% GCP Project
    subgraph "GCP Project"
        direction TB
        EntryPoint["Entry-Point Function (HTTP)"]:::function
        PubSubTopic["Pub/Sub Topic"]:::storage
        SentimentBot["Sentiment-Bot Function (Pub/Sub)"]:::function
        Firestore["Firestore"]:::storage
        SecretManager["Secret Manager"]:::storage
    end

    %% Infrastructure (Terraform)
    Terraform["Terraform / CI"]:::iac

    %% Local Development
    subgraph "Local Development"
        direction TB
        DockerCompose["Docker Compose & Emulators"]:::dev
        Builder["builder/Dockerfile"]:::dev
    end

    %% Environment & Automation
    Env[".env.template / Makefile / README.md"]:::dev

    %% Data Flows
    SlackPlatform -->|"HTTP Event"| EntryPoint
    EntryPoint -->|"Publish Message"| PubSubTopic
    PubSubTopic -->|"Push Subscription"| SentimentBot
    SentimentBot -->|"Call API"| LanguageAPI
    SentimentBot -->|"Post Reply"| SlackPlatform
    SentimentBot -->|"Leasing/Dedupe"| Firestore

    %% Terraform wiring
    Terraform -.-> EntryPoint
    Terraform -.-> PubSubTopic
    Terraform -.-> SentimentBot
    Terraform -.-> Firestore
    Terraform -.-> SecretManager

    %% Local Dev relationships
    DockerCompose -.-> PubSubTopic
    DockerCompose -.-> Firestore
    DockerCompose -.-> EntryPoint
    DockerCompose -.-> SentimentBot
    Builder -.-> EntryPoint
    Builder -.-> SentimentBot

    Env -.-> Terraform

    %% Click Events - Slack Platform
    click SlackPlatform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/slack-config/app-manifest.yaml"

    %% Click Events - Entry-Point Function
    click EntryPoint "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/entry-point/src/index.js"
    click EntryPoint "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/entry-point/src/repositories/adaptors/pubsub.js"
    click EntryPoint "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/entry-point/src/utils/validation.js"
    click EntryPoint "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/entry-point/src/utils/sanitation.js"
    click EntryPoint "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/entry-point/src/utils/logger.js"
    click EntryPoint "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/entry-point/package.json"

    %% Click Events - Pub/Sub Topic
    click PubSubTopic "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/pubsub.tf"

    %% Click Events - Sentiment-Bot Function
    click SentimentBot "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/sentiment-bot/src/index.js"
    click SentimentBot "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/sentiment-bot/src/repositories/eventLease.js"
    click SentimentBot "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/sentiment-bot/src/repositories/language.js"
    click SentimentBot "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/sentiment-bot/src/repositories/slack.js"
    click SentimentBot "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/sentiment-bot/src/service/bot.js"
    click SentimentBot "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/sentiment-bot/src/utils/logger.js"
    click SentimentBot "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/sentiment-bot/src/utils/tools.js"
    click SentimentBot "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/sentiment-bot/package.json"

    %% Click Events - Firestore
    click Firestore "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/firestore.tf"

    %% Click Events - Secret Manager
    click SecretManager "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/secrets.tf"

    %% Click Events - Terraform modules
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/alerts.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/entry-point-function.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/sentiment-bot-function.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/iam.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/locals.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/meta.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/outputs.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/pubsub.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/secrets.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/deploy/variables.tf"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/tree/main/deploy/modules/alerts"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/tree/main/deploy/modules/functions"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/tree/main/deploy/modules/pubsub"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/tree/main/deploy/modules/firestore"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/tree/main/deploy/modules/iam"
    click Terraform "https://github.com/liam-johnston/wwc-sentiment-bot/tree/main/deploy/modules/secrets"

    %% Click Events - Local Development
    click DockerCompose "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/docker-compose.yaml"
    click Builder "https://github.com/liam-johnston/wwc-sentiment-bot/tree/main/builder/Dockerfile"

    %% Click Events - Env & Automation
    click Env "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/.env.template"
    click Env "https://github.com/liam-johnston/wwc-sentiment-bot/tree/main/Makefile"
    click Env "https://github.com/liam-johnston/wwc-sentiment-bot/blob/main/README.md"

    %% Styles
    classDef external fill:#D0E6FF,stroke:#0366d6
    classDef function fill:#FFF4B1,stroke:#D4A017
    classDef storage fill:#D6F5D6,stroke:#2F8F2F
    classDef iac fill:#E8D0F6,stroke:#8000FF
    classDef dev fill:#F5E1D0,stroke:#CC6600
```
