# ethereum/eip-review-bot architecture

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

- Interactive diagram: https://gitdiagram.com/ethereum/eip-review-bot
- Repository: https://github.com/ethereum/eip-review-bot

## Overview

##### Project type and purpose
- This is a GitHub Action (Node.js/TypeScript) named “eip-review-bot” whose sole purpose is to listen for pull-request events on the ethereum/EIPs repository and automatically assign or request appropriate reviewers based on a set of pluggable “rule” modules.

##### File structure
Top-level items:
- action.yml – Action metadata & inputs/outputs
- src/ – Core TypeScript code
– action.ts – Entry point called by the GitHub runner
– process.ts – Coordinator that applies all rules
– namePr.ts, merge.ts, localConfig.ts – Helper modules
– rules/ – One file per review rule + unit tests
- __tests__ & rules/__tests__ – Jest tests for each major component
- package.json, tsconfig.json – Build & compile configuration
- docs/exitcodes.md – Documentation of exit codes
- .github/workflows/*.yml – CI and build pipelines

##### README for additional insights
- The README is succinct: “Automatically request reviewers for the `ethereum/EIPs` repository.”

a. Main components
1. GitHub (Event Source)
2. GitHub Actions Runner (Hosted environment)
3. eip-review-bot Action Code
- EntryPoint (action.ts)
- Configuration Loader (localConfig.ts)
- Processor (process.ts)
- Rule Modules (rules/*.ts)
- Helpers (namePr.ts, merge.ts)
4. GitHub REST API (Octokit)
5. Testing/CI (Jest, GitHub Workflows)

b. Relationships & data flows
– Runner invokes EntryPoint → loads config → calls Processor
– Processor loops through Rule Modules; each emits reviewer decisions
– Aggregated decisions → Octokit client → POST /pulls/:number/requested_reviewers
– CI pipelines trigger on push/PR to validate code & tests

c. Architectural patterns & principles
– Modular “Pipeline”: each rule is an independent plugin
– Single Responsibility: each .ts file has one purpose (config, naming, merge logic, rule)
– Dependency injection of Octokit for easy mocking in tests
– Clear separation of “business logic” (rules) from “Action plumbing” (action.ts)

d. Key technologies & frameworks
– TypeScript, Node.js, Bun/npm
– Octokit (GitHub REST client)
– Jest (unit tests & mocks)
– GitHub Actions (action.yml, runner environment)
– GitHub Workflows for CI & code scanning

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Event Source
    GH["GitHub (pull_request event)"]:::external
    %% Runner Environment
    Runner["GitHub Actions Runner"]:::runner

    %% Action Code Subgraph
    subgraph "eip-review-bot Action Code"
        direction TB
        AY["action.yml"]:::internalModule
        Entry["action.ts"]:::internalModule
        Config["localConfig.ts"]:::internalModule
        Proc["process.ts"]:::internalModule
        Types["types.ts"]:::internalModule
        NamePR["namePr.ts"]:::internalModule
        Merge["merge.ts"]:::internalModule
        subgraph "Rules"
            direction TB
            RMDir["src/rules/"]:::internalModule
            Auth["authors.ts"]:::internalModule
            Editor["editorFile.ts"]:::internalModule
            NewRule["new.ts"]:::internalModule
            Stagnant["stagnant.ts"]:::internalModule
            StatusChange["statuschange.ts"]:::internalModule
            Terminal["terminal.ts"]:::internalModule
            Unknown["unknown.ts"]:::internalModule
        end
    end

    %% Octokit and API
    Octo["Octokit Client"]:::internalModule
    API["GitHub REST API"]:::externalService

    %% CI & Tests Side Panel
    subgraph "CI & Testing"
        direction TB
        BuildWF[".github/workflows/build.yml"]:::ci
        CIWF[".github/workflows/ci.yml"]:::ci
        CodeQL[".github/workflows/codeql-analysis.yml"]:::ci
        TestsCore["src/__tests__/"]:::ci
        TestsRules["src/rules/__tests__/"]:::ci
        MockOcto["generateMockOctokit.ts"]:::ci
        Docs["docs/exitcodes.md"]:::ci
        ConfigFiles["package.json, tsconfig.json"]:::ci
    end

    %% Main Flow
    GH -->|"JSON payload"| Runner
    Runner -->|"executes"| Entry
    Entry -->|"reads inputs"| Config
    Entry -->|"invokes"| Proc
    Proc -->|"uses types"| Types
    Proc -->|"calls"| NamePR
    Proc -->|"calls"| Merge
    Proc -->|"iterates rules"| Auth
    Proc --> Auth -->|"decision"| Octo
    Proc --> Editor -->|"decision"| Octo
    Proc --> NewRule -->|"decision"| Octo
    Proc --> Stagnant -->|"decision"| Octo
    Proc --> StatusChange -->|"decision"| Octo
    Proc --> Terminal -->|"decision"| Octo
    Proc --> Unknown -->|"decision"| Octo
    Octo -->|"POST reviewers"| API

    %% CI Flow (triggered on push/PR)
    GH -.->|"push/PR"| BuildWF
    BuildWF --> CIWF
    BuildWF --> CodeQL
    BuildWF --> TestsCore
    BuildWF --> TestsRules
    TestsCore --> MockOcto
    ConfigFiles --> BuildWF
    Docs --> BuildWF

    %% Click Events
    click AY "https://github.com/ethereum/eip-review-bot/blob/main/action.yml"
    click Entry "https://github.com/ethereum/eip-review-bot/blob/main/src/action.ts"
    click Config "https://github.com/ethereum/eip-review-bot/blob/main/src/localConfig.ts"
    click Proc "https://github.com/ethereum/eip-review-bot/blob/main/src/process.ts"
    click NamePR "https://github.com/ethereum/eip-review-bot/blob/main/src/namePr.ts"
    click Merge "https://github.com/ethereum/eip-review-bot/blob/main/src/merge.ts"
    click RMDir "https://github.com/ethereum/eip-review-bot/tree/main/src/rules/"
    click Auth "https://github.com/ethereum/eip-review-bot/blob/main/src/rules/authors.ts"
    click Editor "https://github.com/ethereum/eip-review-bot/blob/main/src/rules/editorFile.ts"
    click NewRule "https://github.com/ethereum/eip-review-bot/blob/main/src/rules/new.ts"
    click Stagnant "https://github.com/ethereum/eip-review-bot/blob/main/src/rules/stagnant.ts"
    click StatusChange "https://github.com/ethereum/eip-review-bot/blob/main/src/rules/statuschange.ts"
    click Terminal "https://github.com/ethereum/eip-review-bot/blob/main/src/rules/terminal.ts"
    click Unknown "https://github.com/ethereum/eip-review-bot/blob/main/src/rules/unknown.ts"
    click Types "https://github.com/ethereum/eip-review-bot/blob/main/src/types.ts"
    click TestsCore "https://github.com/ethereum/eip-review-bot/tree/main/src/__tests__/"
    click TestsRules "https://github.com/ethereum/eip-review-bot/tree/main/src/rules/__tests__/"
    click MockOcto "https://github.com/ethereum/eip-review-bot/blob/main/src/__tests__/generateMockOctokit.ts"
    click BuildWF "https://github.com/ethereum/eip-review-bot/blob/main/.github/workflows/build.yml"
    click CIWF "https://github.com/ethereum/eip-review-bot/blob/main/.github/workflows/ci.yml"
    click CodeQL "https://github.com/ethereum/eip-review-bot/blob/main/.github/workflows/codeql-analysis.yml"
    click Docs "https://github.com/ethereum/eip-review-bot/blob/main/docs/exitcodes.md"
    click ConfigFiles "https://github.com/ethereum/eip-review-bot/blob/main/package.json"
    click ConfigFiles "https://github.com/ethereum/eip-review-bot/blob/main/tsconfig.json"

    %% Styles
    classDef internalModule fill:#BBDEFB,stroke:#1976D2,stroke-width:1px
    classDef externalService fill:#C8E6C9,stroke:#388E3C,stroke-width:1px,shape:cylinder
    classDef runner fill:#FFE0B2,stroke:#F57C00,stroke-width:1px,shape:hexagon
    classDef ci fill:#E0E0E0,stroke:#757575,stroke-width:1px,shape:parallelogram
    classDef external fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px
```
