# ggstroligo/github-catcher architecture

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

- Interactive diagram: https://gitdiagram.com/ggstroligo/github-catcher
- Repository: https://github.com/ggstroligo/github-catcher

## Overview

##### Project type and purpose
- This is a Ruby on Rails “monolithic” backend service whose primary job is to receive GitHub “issues” webhooks, process and persist events (and issue data), expose an HTTP API for event/issue records, broadcast real-time updates via ActionCable, and optionally send email notifications.

##### File structure
- Top-level Rails MVC structure under app/:
- controllers/api/* → JSON API endpoints for events and issues
- controllers/webhook/github/issues_controller → GitHub webhook receiver
- models/event/* and models/issue/* → domain entities, records, and repository classes
- jobs/ and mailers/ → background processing and email notifications
- channels/ → ActionCable real-time broadcasting
- lib/auth/* → authentication modules for basic auth (users) and GitHub signature verification
- lib/base_service, lib/result → service-object pattern for business logic
- config/* → standard Rails configuration (database, cable, routes, initializers)
- db/* → migrations defining events and issues tables
- spec/* → RSpec test suite for models, services, and auth modules

##### Key architectural patterns & design principles
- MVC at the HTTP layer
- Service-object pattern (lib/base_service) for business logic
- Repository pattern (model/.../repository.rb) to encapsulate data access
- Layered separation: Controller → Auth & Validation → Service → Repository → Database
- Asynchronous jobs for mailers or any off-line processing
- Real-time push via ActionCable channels

##### Main components
A. External Systems
1. GitHub Webhook Sender
2. (Optional) API Consumers / Front-end Clients
3. Email SMTP Provider
B. Rails Application
1. HTTP Layer
- Webhook Controller (/webhook/github/issues)
- API Controllers (/api/events, /api/issues)
2. Auth Layer
- BasicAuth (lib/auth/user/basic_auth)
- GitHub Signature Verifier (lib/auth/webhook/github/signature)
3. Service Layer
- BaseService → IssueEventCreate, EventListFetch, etc.
4. Repository Layer
- Event::Repository, Issue::Repository, Event::List::Repository
5. Persistence
- SQLite3 (development/test) / PostgreSQL (production)
6. Background Processing
- ActiveJob / queuing backend
- Mailers (ApplicationMailer)
7. Real‐Time Messaging
- ActionCable channel (ApplicationCable)
C. Infrastructure Components
- Web Server (Puma)
- Environment variables (.env)
- ngrok / public endpoint for GitHub to reach your /webhook URL

##### Relationships and interactions
1. GitHub → HTTP POST → Rails Webhook Controller
2. Controller invokes Signature Verifier → BasicAuth (if configured)
3. On success, Controller delegates to Service Object to process the payload
4. Service calls Repository to upsert Issue and Event records into the DB
5. Service enqueues any Mailer jobs via ActiveJob
6. Service broadcasts updates to connected WebSocket clients via ActionCable
7. API clients GET /api/events or /api/issues → API Controller → Repository → JSON response

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        GitHub["GitHub Webhook Sender"]:::external
        Clients["API Consumers/Front-end Clients"]:::external
        SMTP["Email SMTP Provider"]:::external
    end

    %% Rails Application
    subgraph "Rails Application"
        subgraph "Controllers Layer"
            WebhookC["Webhook Controller"]:::controllers
            APIEvents["API Events Controller"]:::controllers
            APIIssues["API Issues Controller"]:::controllers
        end
        subgraph "Auth & Validation"
            SigVerifier["GitHub Signature Verifier"]:::auth
            BasicAuth["BasicAuth (User)"]:::auth
        end
        subgraph "Service Layer"
            BaseService["BaseService"]:::service
            ResultObj["Result Object"]:::service
            IssueEventCreate["IssueEventCreate Service"]:::service
        end
        subgraph "Repositories & Models"
            AppRecord["ApplicationRecord"]:::models
            EventRepo["Event Repository"]:::models
            EventListRepo["Event List Repository"]:::models
            IssueRepo["Issue Repository"]:::models
            IssueEventEntity["Issue Event Entity"]:::models
        end
        subgraph "Background & Mailers"
            AppJob["ApplicationJob"]:::infra
            AppMailer["ApplicationMailer"]:::infra
        end
        subgraph "Real-Time"
            CableConn["ActionCable Connection Base"]:::infra
            CableChan["ActionCable Channel Base"]:::infra
        end
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Puma["Puma Web Server"]:::infra
        DB["PostgreSQL/SQLite"]:::infra
        Env["Environment Variables (.env)"]:::infra
        Ngrok["ngrok/Public Endpoint"]:::infra
    end

    %% Relationships
    GitHub -->|POST /webhook| WebhookC
    WebhookC -->|verify signature| SigVerifier
    SigVerifier -->|auth check| BasicAuth
    WebhookC -->|delegate| IssueEventCreate
    IssueEventCreate -->|upsert| EventRepo
    IssueEventCreate -->|upsert| IssueRepo
    IssueEventCreate -->|fetch list| EventListRepo
    EventRepo -->|persist| DB
    IssueRepo -->|persist| DB
    EventListRepo -->|read| DB
    IssueEventCreate -->|enqueue job| AppJob
    AppJob -->|send mail| AppMailer
    AppMailer -->|SMTP delivery| SMTP
    IssueEventCreate -->|broadcast| CableChan
    CableConn <--> CableChan
    Clients -->|GET /api/events| APIEvents
    APIEvents -->|fetch| EventListRepo
    APIEvents -->|fetch| EventRepo
    APIEvents -->|respond JSON| Clients
    Clients -->|GET /api/issues| APIIssues
    APIIssues -->|fetch| IssueRepo
    APIIssues -->|respond JSON| Clients

    %% Infrastructure Links
    WebhookC -->|runs on| Puma
    APIEvents -->|runs on| Puma
    APIIssues -->|runs on| Puma
    Puma -->|connects to| DB
    WebhookC -->|exposed via| Ngrok
    WebhookC -->|loads env| Env

    %% Click Events
    click WebhookC "https://github.com/ggstroligo/github-catcher/blob/main/app/controllers/webhook/github/issues_controller.rb"
    click APIEvents "https://github.com/ggstroligo/github-catcher/blob/main/app/controllers/api/events_controller.rb"
    click APIIssues "https://github.com/ggstroligo/github-catcher/blob/main/app/controllers/api/issues_controller.rb"
    click BasicAuth "https://github.com/ggstroligo/github-catcher/blob/main/lib/auth/user/basic_auth.rb"
    click SigVerifier "https://github.com/ggstroligo/github-catcher/blob/main/lib/auth/webhook/github/signature.rb"
    click BaseService "https://github.com/ggstroligo/github-catcher/blob/main/lib/base_service.rb"
    click ResultObj "https://github.com/ggstroligo/github-catcher/blob/main/lib/result.rb"
    click EventRepo "https://github.com/ggstroligo/github-catcher/blob/main/app/models/event/repository.rb"
    click EventListRepo "https://github.com/ggstroligo/github-catcher/blob/main/app/models/event/list/repository.rb"
    click IssueRepo "https://github.com/ggstroligo/github-catcher/blob/main/app/models/issue/repository.rb"
    click IssueEventCreate "https://github.com/ggstroligo/github-catcher/blob/main/app/models/issue/event/create.rb"
    click IssueEventEntity "https://github.com/ggstroligo/github-catcher/blob/main/app/models/issue/event/entity.rb"
    click AppRecord "https://github.com/ggstroligo/github-catcher/blob/main/app/models/application_record.rb"
    click AppJob "https://github.com/ggstroligo/github-catcher/blob/main/app/jobs/application_job.rb"
    click AppMailer "https://github.com/ggstroligo/github-catcher/blob/main/app/mailers/application_mailer.rb"
    click CableChan "https://github.com/ggstroligo/github-catcher/blob/main/app/channels/application_cable/channel.rb"
    click CableConn "https://github.com/ggstroligo/github-catcher/blob/main/app/channels/application_cable/connection.rb"

    %% Styles
    classDef controllers fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef auth fill:#d4edda,stroke:#333,stroke-width:1px
    classDef service fill:#c3e6cb,stroke:#333,stroke-width:1px
    classDef models fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef infra fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#d6d8fb,stroke:#333,stroke-width:1px
```
