# vapor/penny-bot architecture

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

- Interactive diagram: https://gitdiagram.com/vapor/penny-bot
- Repository: https://github.com/vapor/penny-bot

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Discord Cloud
    subgraph "Discord Cloud"
        direction TB
        DG["Discord Gateway"]:::external
        DR["Discord REST API"]:::external
    end

    %% Penny Service
    subgraph "Penny Service" 
        direction TB
        PSvc["Penny Service"]:::compute
        DEL["DiscordEventListener"]:::compute
        PH["Event Handlers"]:::compute
        PSMain["PennyService (Main)"]:::compute
        SHC["Shared HTTPClient"]:::compute
        SF["ServiceFactory & DI"]:::compute
        Rend["Rendering (Leaf)"]:::compute
        SM["Shared Models/Services"]:::compute
    end

    %% AWS Serverless
    subgraph "AWS"
        direction TB
        APIGW["API Gateway"]:::gateway

        subgraph "Lambda Functions"
            direction TB
            AF["AutoFaqs Lambda"]:::compute
            AP["AutoPings Lambda"]:::compute
            FQ["Faqs Lambda"]:::compute
            OAU["GHOAuth Lambda"]:::compute
            GH["GHHooks Lambda"]:::compute
            SP["Sponsors Lambda"]:::compute
            US["Users Lambda"]:::compute
        end

        subgraph "Shared for Lambdas"
            direction TB
            LS["LambdasShared"]:::compute
            GHA["GitHubAPI Client"]:::compute
        end

        subgraph "Storage"
            direction TB
            DBU["DynamoDB: UserTable"]:::storage
            DBM["DynamoDB: MessageLookup"]:::storage
            DBC["DynamoDB: CoinEntries"]:::storage
            S3P["S3: auto-pings"]:::storage
            S3F["S3: auto-faqs"]:::storage
            S3C["S3: caches"]:::storage
        end
    end

    %% External APIs
    subgraph "External APIs"
        direction TB
        GHR["GitHub REST API"]:::external
        OAUTH["GitHub OAuth Endpoints"]:::external
        SO["StackOverflow API"]:::external
        SR["SwiftReleases & Evolution API"]:::external
    end

    %% Flows
    DG -->|"WebSocket"| DEL
    DEL -->|dispatch| PH
    PH -->|invoke| PSMain
    PSMain -->|uses| SHC
    PSMain -->|inject| SF
    PSMain -->|renders| Rend
    PSMain -->|models| SM
    PSMain -->|"HTTPS"| DR
    PSMain -->|"AWS SDK"| DBU
    PSMain -->|"AWS SDK"| DBM
    PSMain -->|"AWS SDK"| DBC

    DR -->|"HTTPS"| APIGW
    APIGW -->|/auto-faqs| AF
    APIGW -->|/auto-pings| AP
    APIGW -->|/faqs| FQ
    APIGW -->|/oauth| OAU
    APIGW -->|/gh-hooks| GH
    APIGW -->|/sponsors| SP
    APIGW -->|/users| US

    AF -->|"S3 SDK"| S3F
    AP -->|"S3 SDK"| S3P
    FQ -->|"S3 SDK"| S3F
    US -->|"DynamoDB SDK"| DBU
    GH -->|handlers| PSMain
    OAU -->|"DynamoDB SDK"| DBU
    SP -->|monitors| GHR
    US -->|monitors| GHR

    AF -->|shared| LS
    AP -->|shared| LS
    FQ -->|shared| LS
    GH -->|shared| LS
    OAU -->|shared| LS
    SP -->|shared| LS
    US -->|shared| LS

    LS -->|uses| SHC
    LS -->|uses| SF
    LS -->|uses| GHA

    PSMain -->|calls| GHR
    PSMain -->|calls| SO
    PSMain -->|calls| SR
    GH -->|calls| GHR
    OAU -->|calls| GHR

    %% Click Events
    click PSvc "https://github.com/vapor/penny-bot/tree/main/Sources/Penny"
    click SM "https://github.com/vapor/penny-bot/tree/main/Sources/Models"
    click DEL "https://github.com/vapor/penny-bot/blob/main/Sources/Penny/DiscordEventListener.swift"
    click PH "https://github.com/vapor/penny-bot/tree/main/Sources/Penny/Handlers"
    click PSMain "https://github.com/vapor/penny-bot/blob/main/Sources/Penny/MainService/PennyService.swift"
    click SHC "https://github.com/vapor/penny-bot/blob/main/Sources/Shared/+HTTPClient.swift"
    click SF "https://github.com/vapor/penny-bot/blob/main/Sources/Shared/ServiceFactory.swift"
    click Rend "https://github.com/vapor/penny-bot/tree/main/Sources/Rendering"
    click SM "https://github.com/vapor/penny-bot/tree/main/Sources/Shared"
    click AF "https://github.com/vapor/penny-bot/blob/main/Lambdas/AutoFaqs/AutoFaqsHandler.swift"
    click AF "https://github.com/vapor/penny-bot/blob/main/Lambdas/AutoFaqs/S3AutoFaqsRepository.swift"
    click AP "https://github.com/vapor/penny-bot/blob/main/Lambdas/AutoPings/AutoPingsHandler.swift"
    click AP "https://github.com/vapor/penny-bot/blob/main/Lambdas/AutoPings/S3AutoPingsRepository.swift"
    click FQ "https://github.com/vapor/penny-bot/blob/main/Lambdas/Faqs/FaqsHandler.swift"
    click FQ "https://github.com/vapor/penny-bot/blob/main/Lambdas/Faqs/S3FaqsRepository.swift"
    click OAU "https://github.com/vapor/penny-bot/blob/main/Lambdas/GHOAuth/OAuthLambda.swift"
    click OAU "https://github.com/vapor/penny-bot/tree/main/Lambdas/GHOAuth/Models"
    click GH "https://github.com/vapor/penny-bot/blob/main/Lambdas/GHHooks/GHHooksHandler.swift"
    click GH "https://github.com/vapor/penny-bot/tree/main/Lambdas/GHHooks/EventHandler"
    click SP "https://github.com/vapor/penny-bot/blob/main/Lambdas/Sponsors/SponsorsLambda.swift"
    click US "https://github.com/vapor/penny-bot/blob/main/Lambdas/Users/UsersHandler.swift"
    click US "https://github.com/vapor/penny-bot/blob/main/Lambdas/Users/DynamoUserRepository.swift"
    click LS "https://github.com/vapor/penny-bot/tree/main/Lambdas/LambdasShared"
    click GHA "https://github.com/vapor/penny-bot/tree/main/Lambdas/GitHubAPI"

    %% Styles
    classDef compute fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px
    classDef storage fill:#D4EFDF,stroke:#145A32,stroke-width:1px
    classDef gateway fill:#E8DAEF,stroke:#4A235A,stroke-width:1px
    classDef external fill:#E5E7E9,stroke:#6E2C00,stroke-width:1px
```
