How vapor/penny-bot works
Project Type & Purpose
• Penny is a Swift-based, event-driven Discord bot for the Vapor community, combining a persistent service that listens to the Discord Gateway with a suite of AWS Lambda functions (slash-command handlers, GitHub webhook processors, OAuth callback) for on-demand work.
• The README and file tree show two halves:
• Sources/Penny = the long-running Discord Gateway client and core business logic
• Lambdas/... = AWS Lambda functions behind API Gateway for slash commands, webhooks, OAuth, and utility endpoints
Top-Level Components (to show
A. Discord Integration
• Discord Gateway (WebSocket) → Penny Service (DiscordEventListener → Handlers → Services)
• Discord REST API used by both Penny Service and Lambdas (via Shared/HTTPClient)
B. AWS Serverless Layer
• API Gateway
– /auto-pings → AutoPings Lambda
– /auto-faqs → AutoFaqs Lambda
– /faqs → Faqs Lambda
– /oauth → GHOAuth Lambda
– /gh-hooks → GHHooks Lambda
– /sponsors → Sponsors Lambda
– /users → Users Lambda
• LambdasShared code (APIGatewayV2 helpers, SecretsRetriever) and GitHubAPI client shared across many Lambdas
C. Data Stores
• DynamoDB tables (user repository, message lookup, coin entries)
• S3 buckets (auto-pings, auto-faqs, caches)
D. External APIs
• GitHub REST API (via Lambdas and Penny Service)
• OAuth endpoints (GitHub OAuth flow)
• StackOverflow API (via Penny Services)
• Swift Releases & Evolution APIs
Architectural Patterns & Design Principles
• Serverless micro-endpoints: each slash command or webhook is its own Lambda
• Shared libraries: LambdasShared, GitHubAPI, Rendering, Shared services to avoid duplication
• Handler/Service separation: EventHandler dispatchers invoke domain Services, which in turn call Repositories or external APIs
• Dependency injection via ServiceFactory/Shared utilities for testability (reflected in extensive Fake implementations under Tests)
How Components Interact (data-flow)
1. Discord Gateway event arrives → Penny Service → Dispatch to Handler → Service layer → optional external API or AWS SDK → respond over gateway
2. User issues slash command → Discord REST → API Gateway → corresponding Lambda → read/write S3 or DynamoDB → format response → API Gateway → Discord REST → user sees reply
3. GitHub webhook → API Gateway → GHHooks Lambda → EventHandler → various Handlers (e.g., ReleaseMaker, PRHandler) → post to Discord via DiscordService
4. OAuth callback → API Gateway → GHOAuth Lambda → validate token with GitHub → persist link in DynamoDB → redirect user