# meetbryce/open-source-slack-ai architecture

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

- Interactive diagram: https://gitdiagram.com/meetbryce/open-source-slack-ai
- Repository: https://github.com/meetbryce/open-source-slack-ai

## Overview

##### Project type and purpose
- This is a full-stack, event-driven Slack integration service (“The Open-Source Slack AI App”) written in Python.
- Its core purpose is to receive slash-command events and message events from Slack, summarize threads or channels using OpenAI (GPT-3.5/4) and spaCy, then post results back into Slack.

##### File structure
- Top-level:
- `.github/`, `CONTRIBUTING.md`, `LICENSE.md`, `.gitignore`, CI workflows (`poetry-package.yml`, `python-app.yml`)
- `README.md`, `example.env`, `manifest.yaml`, `pyproject.toml`, `pytest.ini`
- `ossai/` – main application package
- `tests/` – unit tests for each module
- Under `ossai/`:
- `slack_server.py` – FastAPI app that exposes HTTP endpoints Slack invokes
- `handlers.py` – Orchestrates command routing (thread summary, channel summary, etc.)
- `summarizer.py` & `topic_analysis.py` – Implements LLM calls and spaCy analysis
- `slack_context.py` – Wraps Slack WebClient for posting responses, rich attachments
- `decorators/` – Error-handling (DM user on exception), PDF-conversion utilities
- `utils.py` & `logging_config.py` – Helper functions and logging setup
- No dedicated database; state is ephemeral or maintained by Slack.

##### README for additional insights
- Describes four main slash commands (`/tldr_thread`, `/tldr_overview`, `/tldr_since`, `/tldr_extended`).
- Shows technology stack: Python 3.9+, FastAPI (uvicorn), Poetry, OpenAI API, spaCy, Slack App.
- Specifies Slack App manifest (`manifest.yaml`) and use of ngrok for local tunneling.

##### Elements
- Labels: e.g., “Slack API”, “ngrok Tunnel”, “FastAPI Server”, “Handler Module”, “Summarizer Service”, “OpenAI API”
- Slack → FastAPI (webhook)
- FastAPI → Handler → Summarizer → OpenAI/spaCy → Handler → SlackContext → Slack
- Internal modules (FastAPI, handlers, summarizer) in another
- Cross-cutting utilities (decorators, utils) in a distinct style

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services
    subgraph "External Services"
        SlackUser["Slack User"]:::external
        SlackAPI["Slack API"]:::external
        ngrok["ngrok Tunnel"]:::external
        OpenAIAPI["OpenAI API"]:::external
        spaCyModel["spaCy Model"]:::external
    end

    %% Internal Application
    subgraph "Internal Application"
        FastAPIServer["FastAPI Server\n(ossai/slack_server.py)"]:::internal
        Handler["Request Router / Handlers\n(ossai/handlers.py)"]:::internal
        DecoratorError["Error-Handling Decorator\n(ossai/decorators/catch_error_dm_user.py)"]:::decorator
        DecoratorPDF["PDF-Conversion Decorator\n(ossai/decorators/to_pdf.py)"]:::decorator
        Summarizer["Summarizer Service\n(ossai/summarizer.py)"]:::internal
        TopicAnalysis["Topic Analysis Module\n(ossai/topic_analysis.py)"]:::internal
        SlackContext["SlackContext Adapter\n(ossai/slack_context.py)"]:::internal
    end

    %% Utilities
    subgraph "Utilities"
        Utils["Utility Functions\n(ossai/utils.py)"]:::util
        LoggingConfig["Logging Configuration\n(ossai/logging_config.py)"]:::util
    end

    %% Configuration
    subgraph "Configuration"
        Manifest["Slack App Manifest\n(manifest.yaml)"]:::config
        Env["Example Environment Variables\n(example.env)"]:::config
    end

    %% Flow
    SlackUser -->|"types slash command"| SlackAPI
    SlackAPI -->|"webhook POST"| ngrok
    ngrok -->|"forwards to"| FastAPIServer
    FastAPIServer -->|"routes event"| Handler

    Handler -->|applies| DecoratorError
    Handler -->|applies| DecoratorPDF
    DecoratorError -->|"calls"| Summarizer
    DecoratorPDF -->|"calls"| Summarizer

    Summarizer -->|"uses NLP"| TopicAnalysis
    Summarizer -->|"calls"| OpenAIAPI
    TopicAnalysis -->|"loads model"| spaCyModel

    Summarizer -->|"returns summary"| Handler
    Handler -->|"uses adapter"| SlackContext
    SlackContext -->|"posts message"| SlackAPI

    FastAPIServer -->|"loads config"| Manifest
    FastAPIServer -->|"loads env vars"| Env
    FastAPIServer -->|"initializes logging"| LoggingConfig
    FastAPIServer -->|"imports helpers"| Utils

    %% Click Events
    click FastAPIServer "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/slack_server.py"
    click Handler "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/handlers.py"
    click Summarizer "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/summarizer.py"
    click TopicAnalysis "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/topic_analysis.py"
    click SlackContext "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/slack_context.py"
    click DecoratorError "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/decorators/catch_error_dm_user.py"
    click DecoratorPDF "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/decorators/to_pdf.py"
    click Utils "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/utils.py"
    click LoggingConfig "https://github.com/meetbryce/open-source-slack-ai/blob/main/ossai/logging_config.py"
    click Manifest "https://github.com/meetbryce/open-source-slack-ai/blob/main/manifest.yaml"
    click Env "https://github.com/meetbryce/open-source-slack-ai/blob/main/example.env"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px;
    classDef decorator fill:#fbf,stroke:#333,stroke-width:1px;
    classDef util fill:#bfb,stroke:#333,stroke-width:1px;
    classDef config fill:#ffd,stroke:#333,stroke-width:1px;
```
