# github/emergency-pull-request-probot-app architecture

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

- Interactive diagram: https://gitdiagram.com/github/emergency-pull-request-probot-app
- Repository: https://github.com/github/emergency-pull-request-probot-app

## Overview

##### Project type and purpose
- This is a serverless, event-driven microservice implemented as a GitHub App (using Probot) that runs on AWS Lambda.
- Its sole purpose is to listen for “labeled” Pull Request events marked with an emergency label, then optionally approve, merge, audit (create an issue), and send Slack notifications—bypassing normal branch protection in emergencies.

##### File structure
- Top-level code:
– app.js: sets up the Probot event-handler logic.
– handler.js: AWS Lambda entry point (wraps Probot app for Lambda).
– test.js: unit tests for core logic.
- Configuration & infrastructure:
– template.yml: AWS SAM template describing the Lambda function, API Gateway, IAM roles, environment variables.
– Dockerfile & .devcontainer/: for local development container.
– .env-sample: lists all runtime environment variables (APP_ID, PRIVATE_KEY, EMERGENCY_LABEL, etc.).
- CI/CD:
– .github/workflows/*.yml: GitHub Actions pipelines for build/test, Docker image build & publish, pull request checks.
- Supporting markdown:
– emergency-pr-manifest.yml: Slack App manifest.
– issueBody.md, slackMessage.txt: templates for GitHub issue bodies and Slack notifications.

##### Extract insights from README
- Describes event subscription (Pull Request “labeled”), env-vars toggles (APPROVE_PR, MERGE_PR, CREATE_ISSUE, SLACK_NOTIFY).
- Deployment flow:
– AWS SAM build/deploy guided by template.yml.
– Docker run for local debugging or container use.
– CI pipelines in GitHub Actions.
- External integrations: GitHub API, Slack API, AWS Lambda, AWS API Gateway, optionally smee.io for local webhook forwarding.

##### Main components
A. GitHub (source of webhooks and API)
B. AWS API Gateway (HTTP endpoint for GitHub webhooks)
C. AWS Lambda (Probot application code)
D. GitHub API (for approve-PR, merge-PR, create-issue operations)
E. Slack API (for notifications)
F. CI/CD Pipeline (GitHub Actions jobs: build, test, deploy, docker build & publish)
G. Local Dev Environment (Docker, SAM CLI + smee.io)

##### Relationships and data flow
1. Developer labels a PR in GitHub → GitHub emits PullRequest “labeled” webhook
2. Webhook routed to AWS API Gateway → invokes AWS Lambda (handler.js → app.js)
3. Lambda inspects label & env vars → calls:
- GitHub API to approve PR (if APPROVE_PR=true)
- GitHub API to merge PR (if MERGE_PR=true)
- GitHub API to create audit issue using issueBody.md (if CREATE_ISSUE=true)
- Slack API to post message using slackMessage.txt (if SLACK_NOTIFY=true)
4. All AWS infrastructure deployed via AWS SAM (template.yml) from CI/CD or dev machine
5. CI/CD pipeline triggered on push/PR: runs tests (test.js), builds Docker image, publishes image or runs sam deploy

##### Architectural patterns & design principles
- Serverless, microservice, event-driven architecture
- Configuration-as-code: AWS SAM template & environment variables
- 12-factor app principles: all behavior driven by environment vars, logs to stdout
- Extensibility via templates (issueBody.md, slackMessage.txt)
- CI/CD best practices: automated testing, container builds, multi-stage workflows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services" 
        direction TB
        GH["GitHub Webhooks & API"]:::external
        Slack["Slack REST API"]:::external
    end

    %% AWS Infrastructure
    subgraph "AWS Cloud" 
        direction TB
        APIGW["API Gateway"]:::aws
        Lambda["Lambda Function\n(handler.js + app.js)\nENV: APPROVE_PR, MERGE_PR,\nCREATE_ISSUE, SLACK_NOTIFY"]:::aws
    end

    %% CI/CD Pipeline
    subgraph "CI/CD (GitHub Actions)" 
        direction TB
        CI["GitHub Actions"]:::ci
    end

    %% Local Development
    subgraph "Local Development" 
        direction TB
        DevDocker["Docker & SAM CLI"]:::local
        Smee["smee.io forwarding"]:::local
    end

    %% Project Templates & Metadata
    subgraph "Templates & Repo Metadata"
        direction TB
        Manifest["emergency-pr-manifest.yml"]:::template
        IssueTpl["issueBody.md"]:::template
        SlackTpl1["slackMessage.txt"]:::template
        SlackTpl2["slackMessageNoIssue.txt"]:::template
        EnvSample[".env-sample"]:::template
        RepoMeta["package.json,\npackage-lock.json,\nREADME.md,\nCODE_OF_CONDUCT.md,\nCONTRIBUTING.md,\nLICENSE,\nSECURITY.md,\n.gitignore,\n.github/CODEOWNERS,\n.github/dependabot.yml"]:::template
    end

    %% Tests
    subgraph "Testing"
        direction TB
        Tests["test.js"]:::ci
    end

    %% CI/CD to AWS
    CI -->|"sam build & deploy\nor Docker build & publish"| APIGW
    CI -->|deploy Lambda| Lambda
    CI -->|run tests| Tests

    %% Event Flow
    GH -->|"Pull Request labeled"| APIGW
    APIGW -->|"invoke"| Lambda
    Lambda -->|"approve PR"| GH
    Lambda -->|"merge PR"| GH
    Lambda -->|"create issue"| GH
    Lambda -->|"post notification"| Slack

    %% Local dev flow
    DevDocker -->|forward webhooks| Smee
    Smee --> APIGW
    DevDocker -->|sam local invoke| Lambda

    %% Templates use
    Lambda -->|uses manifest| Manifest
    Lambda -->|uses issue template| IssueTpl
    Lambda -->|uses slack templates| SlackTpl1
    Lambda -->|uses slack templates| SlackTpl2
    Lambda -->|reads env vars sample| EnvSample

    %% Click Events
    click app "https://github.com/github/emergency-pull-request-probot-app/blob/main/app.js"
    click handler "https://github.com/github/emergency-pull-request-probot-app/blob/main/handler.js"
    click Tests "https://github.com/github/emergency-pull-request-probot-app/blob/main/test.js"
    click template "https://github.com/github/emergency-pull-request-probot-app/blob/main/template.yml"
    click EnvSample "https://github.com/github/emergency-pull-request-probot-app/blob/main/.env-sample"
    click Dockerfile "https://github.com/github/emergency-pull-request-probot-app/tree/main/Dockerfile"
    click DevDocker "https://github.com/github/emergency-pull-request-probot-app/tree/main/.devcontainer/Dockerfile"
    click DevDocker "https://github.com/github/emergency-pull-request-probot-app/blob/main/.devcontainer/devcontainer.json"
    click CI "https://github.com/github/emergency-pull-request-probot-app/blob/main/.github/workflows/test.yml"
    click CI "https://github.com/github/emergency-pull-request-probot-app/blob/main/.github/workflows/docker-build-publish.yml"
    click CI "https://github.com/github/emergency-pull-request-probot-app/blob/main/.github/workflows/pr.yml"
    click CI "https://github.com/github/emergency-pull-request-probot-app/blob/main/.github/workflows/review-probot-prs.yml"
    click Manifest "https://github.com/github/emergency-pull-request-probot-app/blob/main/emergency-pr-manifest.yml"
    click IssueTpl "https://github.com/github/emergency-pull-request-probot-app/blob/main/issueBody.md"
    click SlackTpl1 "https://github.com/github/emergency-pull-request-probot-app/blob/main/slackMessage.txt"
    click SlackTpl2 "https://github.com/github/emergency-pull-request-probot-app/blob/main/slackMessageNoIssue.txt"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/blob/main/package.json"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/blob/main/package-lock.json"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/blob/main/README.md"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/blob/main/CODE_OF_CONDUCT.md"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/blob/main/CONTRIBUTING.md"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/tree/main/LICENSE"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/blob/main/SECURITY.md"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/blob/main/.gitignore"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/tree/main/.github/CODEOWNERS"
    click RepoMeta "https://github.com/github/emergency-pull-request-probot-app/blob/main/.github/dependabot.yml"

    %% Styles
    classDef aws fill:#f90,stroke:#333,stroke-width:1px;
    classDef external fill:#ccc,stroke:#333,stroke-width:1px;
    classDef ci fill:#09f,stroke:#333,stroke-width:1px;
    classDef local fill:#9f6,stroke:#333,stroke-width:1px;
    classDef template fill:#fcf,stroke:#333,stroke-width:1px;
```
