# shawnsomething/slack-chat-blocker architecture

> Architecture diagram of the GitHub repository shawnsomething/slack-chat-blocker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shawnsomething/slack-chat-blocker
- Repository: https://github.com/shawnsomething/slack-chat-blocker

## Overview

##### Project type and purpose
- This is a Slack‐integration service (Slack “app”) written in Node.js/TypeScript.
- Its core purpose is to intercept or respond to outgoing Slack messages and prevent (“block”) potentially offensive content.

##### File structure
- Top level
- package.json / package-lock.json: Node.js dependencies and scripts
- tsconfig.json: TypeScript compiler settings
- README.md: project description
- build/
- index.js: compiled entry point for the message‐processing server
- slackOauth.js: compiled OAuth handler
- src/
- index.ts: source entry point—registers Slack event handlers, starts HTTP server or listener
- slackOauth.ts: source handling of OAuth handshake, token storage
- No database directory: likely uses environment variables or in‐memory storage for tokens (can extend with a key‐value store)

##### README for additional insights
- Very concise: “a slack chat blocker that stops you from sending messages that would offend office Karens.”
- Implies core flow: user installs the app (OAuth) → user sends/slack event occurs → text is scanned → offensive messages are blocked or an alert is sent.

##### Main components and their interactions
a. Slack Workspace & Clients
– End users and their Slack clients
b. Slack API / Events API
– Delivers message events to your service
– OAuth endpoints for installation
c. OAuth Module (slackOauth.ts)
– Handles “Add to Slack” OAuth flow
– Stores access tokens (in memory or external store)
d. Message Processor (index.ts)
– HTTP listener or event‐pipe for incoming Slack events
– Invokes filter logic
e. Filter Logic
– Text scanning engine (could be a simple keyword list, regex, or external NLP service)
– Decides “safe” vs. “offensive”
f. Slack API Client
– Deletes or modifies offending messages, posts ephemeral warning messages
g. (Optional) Storage / Logging
– Persist blocked message metadata, user metrics, audit logs

##### Relationships & data flow
1. User installs app ⇒ Slack OAuth server ⇒ Your OAuth endpoint ⇒ Store tokens
2. User sends message in channel ⇒ Slack Events API ⇒ Your message‐handler endpoint
3. Message Processor parses JSON ⇒ passes text to Filter Logic
4. Filter Logic decision:
- Safe ⇒ do nothing
- Offensive ⇒ call Slack API (delete or warn)
5. (Optional) Log event to storage or console

##### Architectural patterns & design principles
- Integration (webhook/event driven)
- Single responsibility modules: OAuth vs. message processing vs. filtering
- Use environment variables or secrets manager for tokens
- Can evolve into microservices: e.g., extract filter engine into separate service

##### Technologies & frameworks
- Node.js runtime
- TypeScript for type safety
- Express (or built‐in HTTP) for endpoints
- @slack/web-api and @slack/events-api SDKs
- npm scripts for build (tsc → build/)
- Deployment target: AWS Lambda / Heroku / any HTTP‐accessible host

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    SlackOAuth["Slack OAuth Server"]:::external
    SlackEvents["Slack Events API"]:::external
    SlackClient["Slack Clients"]:::external

    %% Slack App Service
    subgraph "Slack App Service"
        direction TB
        OAuthHandler["OAuth Handler"]:::service
        MsgProcessor["Message Processor"]:::service
        FilterLogic["Filter Logic"]:::filter
        SlackApiClient["Slack API Client"]:::service
        TokenStore["Token Store"]:::storage
        LogStore["Event Log Store"]:::storage
    end

    %% Flows
    SlackClient -->|Installs App| SlackOAuth
    SlackOAuth -->|OAuth code exchange| OAuthHandler
    OAuthHandler -->|Store tokens| TokenStore

    SlackClient -->|Sends message| SlackEvents
    SlackEvents -->|Event payload| MsgProcessor
    MsgProcessor -->|Extract text| FilterLogic
    FilterLogic -->|Safe? No| SlackApiClient
    SlackApiClient -->|delete/ warn message| SlackClient

    FilterLogic -->|All events| LogStore
    MsgProcessor -->|Optional logs| LogStore

    %% Click Events
    click OAuthHandler "https://github.com/shawnsomething/slack-chat-blocker/blob/main/src/slackOauth.ts"
    click OAuthHandler "https://github.com/shawnsomething/slack-chat-blocker/blob/main/build/slackOauth.js"
    click MsgProcessor "https://github.com/shawnsomething/slack-chat-blocker/blob/main/src/index.ts"
    click MsgProcessor "https://github.com/shawnsomething/slack-chat-blocker/blob/main/build/index.js"
    click README["README.md"] "README.md"
    click TSConfig["tsconfig.json"] "tsconfig.json"
    click PackageJSON["package.json"] "package.json"
    click PackageLock["package-lock.json"] "package-lock.json"

    %% Styles
    classDef external fill:#ffe0b2,stroke:#ff9800,color:#3e2723
    classDef service fill:#bbdefb,stroke:#2196f3,color:#0d47a1
    classDef filter fill:#c8e6c9,stroke:#4caf50,color:#1b5e20
    classDef storage fill:#f8bbd0,stroke:#e91e63,color:#880e4fclass README,TSConfig,PackageJSON,PackageLock external
    class OAuthHandler,MsgProcessor,SlackApiClient service
    class FilterLogic filter
    class TokenStore,LogStore storage
```
