How ggstroligo/github-catcher works
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