# tdsmith/github-snooze-button architecture

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

- Interactive diagram: https://gitdiagram.com/tdsmith/github-snooze-button
- Repository: https://github.com/tdsmith/github-snooze-button

## Overview

##### Project type and purpose
- This is a Python-based, event-driven, serverless “wrapper” around GitHub issues/PRs: it watches for comments and PR updates on GitHub, and when you “snooze” an issue (by adding a label), it automatically unsnoozes (removes the label) once activity resumes.
- It ships as a CLI/packaged PyPI module and can run either in AWS Lambda (via SNS) or locally by polling an SQS queue.

##### File structure
- Top-level:
- setup.py / setup.cfg, tox.ini / .travis.yml → build, test, CI.
- snooze/
– deploy_lambda.py → CLI entrypoint `snooze_deploy`, builds AWS infra: IAM role, SNS topics, Lambda functions.
– lambda_handler.py → the AWS Lambda handler receiving SNS events.
– repository_listener.py → polling client for SQS in “listen” mode.
– callbacks.py → encapsulates the core logic that inspects events and calls GitHub to remove labels.
– config.py, constants.py, version.py → config loading and versioning.
– snooze.py → shared routines.
– test/ → unit tests for each component.

##### README for additional insights
- Two modes:
Option 1: AWS Lambda deployment.
Option 2: Local/SQS polling.
- Uses GitHub Webhooks → AWS SNS → AWS Lambda (or SQS) → Python handler → GitHub API.
- Configuration via an INI file: GitHub credentials, AWS credentials, label names per repo.

##### Detail
- Break out modules in the snooze/ directory and map them onto runtime components:
- deploy_lambda.py → “Infra Provisioner”
- lambda_handler.py + callbacks.py → “Event Processor”
- repository_listener.py → “SQS Poller”
- config.py → “Config Loader”
- AWS resources (IAM role, SNS topics, Lambda) and code boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Event Source
    GitHub["GitHub (Webhooks)"]:::external

    %% Infra Provisioner
    subgraph "Infrastructure Provisioner"
        Provisioner["Infra Provisioner\n(snooze_deploy)"]:::code
    end

    %% AWS Infrastructure
    subgraph "AWS Infrastructure"
        IAM["IAM Role"]:::aws
        SNS["SNS Topic 'repo'"]:::aws
        Lambda["Lambda Function 'snooze'"]:::code
        SQS["SQS Queue 'repo'"]:::aws
    end

    %% Code Modules
    subgraph "Code Modules"
        Handler["AWS Lambda Handler"]:::code
        Processor["Event Processor\n(callbacks)"]:::code
        Poller["SQS Poller\n(repository_listener)"]:::code
        Config["Config Loader\n(config.ini)"]:::config
        Const["Constants\n(constants.py)"]:::code
        Utils["Shared Utilities\n(snooze.py)"]:::code
        Version["Version Metadata\n(version.py)"]:::code
        Setup["Package Metadata\n(setup.py, setup.cfg)"]:::code
        Tests["Unit Tests\n(test/)"]:::code
    end

    %% External API
    GitHubAPI["GitHub API"]:::external

    %% Connections - Provisioning
    Provisioner -->|boto3 create| IAM
    Provisioner -->|boto3 create| SNS
    Provisioner -->|boto3 create| Lambda
    SNS -->|subscription| Lambda
    SNS -->|subscription| SQS

    %% Event Flow - Serverless Mode
    GitHub -->|issue_comment / pull_request / push| SNS
    Lambda --> Handler
    Handler --> Processor
    Processor -->|reads| Config
    Processor -->|reads| Const
    Processor -->|invokes| Utils
    Processor -->|calls| GitHubAPI

    %% Event Flow - Polling Mode
    GitHub -->|events| SNS
    SNS -->|fanout| SQS
    Poller -->|polls| SQS
    Poller --> Processor

    %% Tests exercise modules
    Tests --> Handler
    Tests --> Processor
    Tests --> Poller
    Tests --> Utils

    %% Click Events
    click Provisioner "https://github.com/tdsmith/github-snooze-button/blob/master/snooze/deploy_lambda.py"
    click Handler "https://github.com/tdsmith/github-snooze-button/blob/master/snooze/lambda_handler.py"
    click Processor "https://github.com/tdsmith/github-snooze-button/blob/master/snooze/callbacks.py"
    click Poller "https://github.com/tdsmith/github-snooze-button/blob/master/snooze/repository_listener.py"
    click Config "https://github.com/tdsmith/github-snooze-button/blob/master/snooze/config.py"
    click Const "https://github.com/tdsmith/github-snooze-button/blob/master/snooze/constants.py"
    click Utils "https://github.com/tdsmith/github-snooze-button/blob/master/snooze/snooze.py"
    click Version "https://github.com/tdsmith/github-snooze-button/blob/master/snooze/version.py"
    click Setup "https://github.com/tdsmith/github-snooze-button/blob/master/setup.py"
    click Tests "https://github.com/tdsmith/github-snooze-button/tree/master/snooze/test/"

    %% Styles
    classDef aws fill:#fdae6b,stroke:#e6550d,color:#000
    classDef code fill:#9ecae1,stroke:#3182bd,color:#000
    classDef external fill:#bc80bd,stroke:#7b4173,color:#000
    classDef config fill:#f0f0f0,stroke:#636363,color:#000
```
