# rockroman/slack_automation architecture

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

- Interactive diagram: https://gitdiagram.com/rockroman/slack_automation
- Repository: https://github.com/rockroman/slack_automation

## Overview

##### Project type and purpose
- This is a lightweight Python-script automation project that integrates with Slack and Google Sheets, persists state in JSON, and will eventually incorporate an LLM.
- From the README “plan” we know it will run on a schedule (via GitHub Actions), fetch Slack data, update sheets, handle timestamps, revisit or flag unresolved issues, and later add LLM features.

##### File structure
Top-level artifacts:
- Python entry points & logic:
- extract_from_link.py – pulls URLs or resources from Slack messages
- refactored_slack.py – core Slack-API integration
- revisit_issue.py & unresolved_issues.py – logic around unresolved items
- sheet_auto.py – Google Sheets integration
- timestap_utils.py – timestamp read/write helpers
- State storage:
- last_timestamp.json – last run marker
- unresolved.json – persisted list of open or pending items
- CI/CD / scheduling:
- .github/workflows/slack_actions.yml – triggers these scripts on a schedule
- Requirements.txt – Python dependencies

##### README for additional insights
- The README confirms development milestones: basic automation, timestamp fixes, scaling date ranges, scheduling via GitHub, and LLM integration as future work.

##### Components
a. Main components:
1. Scheduler (GitHub Actions cron job)
2. Orchestrator script (could be a single script or entry point that calls sub-modules)
3. Slack API client
4. Local JSON storage (last_timestamp.json, unresolved.json)
5. Business-logic modules (extract_from_link, revisit_issue, unresolved_issues)
6. Google Sheets API client
7. (Future) LLM service
b. Relationships & data flows:
- Scheduler triggers the orchestrator on a fixed interval
- Orchestrator reads last_timestamp.json via timestap_utils → calls Slack API → retrieves new messages
- extract_from_link filters and extracts relevant links/issues → business logic modules process them → updates unresolved.json
- sheet_auto.py writes results/updates to Google Sheets
- timestap_utils writes the new last_timestamp back to JSON
- (Future) orchestrator sends unresolved items or context to the LLM service and receives enriched output
c. Architectural patterns/design principles:
- Modular scripting: each functional area is a separate Python module
- Persistence-as-JSON: lightweight state management
- CI-driven scheduling: no on-prem server required
- Clear separation between I/O (APIs), business logic, and storage
d. Key technologies/frameworks:
- Python 3.x
- Slack SDK / REST API
- Google Sheets API (via gspread or similar)
- GitHub Actions for scheduling
- JSON file storage
- Planned LLM API (e.g., OpenAI)

##### Detail
- How the timestamp fix loop runs after each invocation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Scheduler
    subgraph "Scheduler"
        GitHubActions["GitHub Actions Cron"]:::scheduler
    end

    %% Orchestrator
    subgraph "Orchestrator"
        OrchestratorScript["Orchestrator Script"]:::logic
    end

    %% Business Logic Modules
    subgraph "Business Logic Modules"
        Extract["Link Extraction"]:::logic
        Revisit["Revisit Issues"]:::logic
        Unresolved["Unresolved Issues Processing"]:::logic
    end

    %% JSON Storage
    subgraph "JSON Storage"
        TimestampStore["Last Run Timestamp"]:::storage
        UnresolvedStore["Unresolved Items"]:::storage
        TimestampUtils["Timestamp Utilities"]:::logic
    end

    %% External Services
    subgraph "External Services"
        SlackAPI["Slack API Client"]:::external
        SheetsAPI["Google Sheets API Client"]:::external
        LLMService["LLM Service (Future)"]:::external
    end

    %% Connections
    GitHubActions -->|"trigger"| OrchestratorScript
    OrchestratorScript -->|"uses"| TimestampUtils
    TimestampUtils -->|"read_timestamp"| TimestampStore
    OrchestratorScript -->|"list_conversations"| SlackAPI
    SlackAPI -->|"messages"| Extract
    Extract -->|"extract links"| Revisit
    Revisit -->|"process issues"| Unresolved
    Unresolved -->|"update state"| UnresolvedStore
    Unresolved -->|"update timestamp"| TimestampStore
    Unresolved -->|"append_row"| SheetsAPI
    Unresolved -.->|"send context"| LLMService
    LLMService -.->|"enriched output"| Unresolved

    %% Click Events
    click GitHubActions "https://github.com/rockroman/slack_automation/blob/main/.github/workflows/slack_actions.yml"
    click SlackAPI "https://github.com/rockroman/slack_automation/blob/main/refactored_slack.py"
    click Extract "https://github.com/rockroman/slack_automation/blob/main/extract_from_link.py"
    click Revisit "https://github.com/rockroman/slack_automation/blob/main/revisit_issue.py"
    click Unresolved "https://github.com/rockroman/slack_automation/blob/main/unresolved_issues.py"
    click TimestampUtils "https://github.com/rockroman/slack_automation/blob/main/timestap_utils.py"
    click SheetsAPI "https://github.com/rockroman/slack_automation/blob/main/sheet_auto.py"
    click TimestampStore "https://github.com/rockroman/slack_automation/blob/main/last_timestamp.json"
    click UnresolvedStore "https://github.com/rockroman/slack_automation/blob/main/unresolved.json"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#000,stroke-width:1px
    classDef storage fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef scheduler fill:#FFA500,stroke:#000,stroke-width:1px
```
